Phase 3: AgentKeys TypeScript SDK

[hanwencheng]

Context

The TypeScript SDK is the second SDK (Python is #119). Sister deliverable; same shape; different ecosystem.

Why TypeScript matters in M3:

• Node services that need to hold AgentKeys creds (vendor server-side automation, internal tooling)
• Browser apps (parent-control UI Phase 1: Parent-control web UI (mobile-responsive) for v0 demo #110 will eventually want a typed client instead of hand-rolled fetch calls)
• Cursor / VSCode / Continue.dev extensions that need to authenticate against AgentKeys per session
• Frontier model providers (Claude Code, Cursor) building their own MCP-adjacent integrations

Scope (M3)

SDK design

• Modern TypeScript (5.x), strict mode
• Browser-safe + Node-safe builds (the package ships both as conditional exports in package.json)
• Tool surface = MCP server's tool surface — same 7 active tools from Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107, mirrored exactly to the Python SDK (Phase 3: AgentKeys Python SDK #119)
  • client.identity.whoami(actor)
  • client.memory.get(...) / client.memory.put(...)
  • client.permission.check(...)
  • client.cap.mint(...) / client.cap.revoke(...)
  • client.audit.append(...)
• Type definitions cover every parameter + response — no any in the public API surface

Packaging

• Publish to npm as @agentkeys/sdk
• ESM + CJS dual build
• Tree-shakable for browser bundlers (Vite / webpack / Rollup tested)
• Semver from day one; v0.1.0 is the M3 release

Examples

• README quickstart
• Node example: server-side cred broker
• Browser example: parent-UI fetch wrapper (paths to migrate the M1 parent UI in Phase 1: Parent-control web UI (mobile-responsive) for v0 demo #110 to use the SDK)
• Cursor / VSCode extension example: how to integrate AgentKeys into a custom extension's authentication

Out of scope (defer)

• Bundle minification beyond what tsup/tsc produces by default (M4 if bundle size becomes a customer concern)
• React-specific hooks (useAgentKeys) — M4, after the parent-UI UI primitives stabilize
• Deno / Bun-specific builds (M4 — Node-compatible is enough)
• Auto-generated stubs from an OpenAPI spec (M4)

Acceptance criteria

• npm install @agentkeys/sdk works on Node 18, 20, 22
• TypeScript strict-mode passes for consumers; no implicit any in the public API surface
• Node example: server-side script mints a cap-token, writes to memory, reads it back, appends audit row — ≤30 lines
• Browser example: typed fetch wrapper integrated into a minimal Next.js page; SSE consumer works end-to-end
• Bundle size budget: < 30KB minified+gzipped for the core client (excluding optional helpers)
• CI publishes to npm on tag; automated changelog generation
• Identical functional behavior to the Python SDK (Phase 3: AgentKeys Python SDK #119) — both clients send the same wire requests for the same calls

Risks

Risk	Mitigation
ESM/CJS dual-build pitfalls (consumer can't import)	Use a known-good tool like tsup with documented dual-build config; test consumer import from a fresh npm init project
Bundle size grows from accidental dep bloat	CI gate: bundlesize check against the 30KB budget; PR fails on regression
Browser-side SSE handling differs across vendors	Wrap with EventSource polyfill where needed; document browser support matrix
API drift between SDK + Python SDK + MCP server	All 3 derive from a shared schema — if MCP server's shape changes, both SDKs regenerate

References

• docs/spec/plans/milestones-roadmap.md §4 (M3 scope)
• docs/research/agent-iam-strategy.md §5 Phase 3 (runtime neutrality + SDK ecosystem)
• Phase 1: AgentKeys MCP server — 7 active tools + 3 schema-only #107 (MCP server — tool-surface source)
• Phase 3: AgentKeys Python SDK #119 (Python SDK — sister deliverable; behavior identical)
• Phase 1: Parent-control web UI (mobile-responsive) for v0 demo #110 (M1 parent UI — eventual consumer; migrate after the SDK ships)

Effort

~1 week. Sequencing:

1. (Days 1-2) Skeleton + tsup dual-build config + auth + type definitions
2. (Days 2-4) All 7 tool methods + error envelope; verify wire-format identity with Python SDK
3. (Days 4-5) Browser example + bundle-size check + cross-runtime tests (Node 18/20/22, Bun-compat)
4. (Days 5-7) Docs + examples + npm publish CI

Pickup notes for the next agent / developer

• Wait until Phase 3: AgentKeys Python SDK #119 (Python SDK) lands first — same wire format; copy the type definitions if helpful
• Use tsup for the dual ESM/CJS build; it Just Works for this kind of SDK
• Use strict TypeScript ("strict": true in tsconfig) + no implicit any — the value of a typed SDK is what's typed
• For browser-safe builds: avoid Node-specific imports in the core client; keep fs, crypto.randomBytes, etc. behind environment-conditional imports
• For SSE in the browser: native EventSource is fine for most browsers; only polyfill if a vendor target is older
• Watch for: the SDK is the typed-by-default surface for vendor integrations. If you let any slip into the public API, vendor type-checkers will silently miss bugs.
• Use the /agentkeys-issue-create skill for follow-up issues (e.g., React hooks, Deno-specific build)

[jshaofa-ui]

Solution: AgentKeys TypeScript SDK

I've developed a comprehensive solution for the TypeScript SDK that mirrors the Python SDK's API surface for cross-language consistency.

Key Design Decisions

1. Dual build (ESM + CJS) — Works with Node.js, bundlers (webpack/vite), and browser CDN
2. Tree-shakeable — Named exports, sideEffects: false, zero barrel imports
3. Zero runtime deps — Uses native fetch API (Node 18+ / all modern browsers)
4. Same surface as Python SDK — Identical method names and signatures

Package Structure

• src/ — 11 modules (client, transport, models, 5 sub-clients, errors)
• dist/esm/ + dist/cjs/ — Dual build output
• tests/ — vitest suite targeting 90%+ coverage
• examples/ — Node.js, browser CDN, Cursor extension

Compatibility with Python SDK (#119)

All 5 sub-clients (memory, permission, cap, audit, credentials) have identical method signatures across both SDKs.

Estimated Effort: ~1 week

Full solution document available. Can be developed in parallel with #119.