{"_id":"@best-agent/sdk-ts","_rev":"3-611d3656afe670ac744dc187be1970c4","name":"@best-agent/sdk-ts","dist-tags":{"latest":"0.0.2-beta.8","beta":"0.0.2-beta.2"},"versions":{"0.0.1-beta.1":{"name":"@best-agent/sdk-ts","version":"0.0.1-beta.1","_id":"@best-agent/sdk-ts@0.0.1-beta.1","maintainers":[{"name":"simon_he","email":"13917107469@163.com"}],"dist":{"shasum":"95b4e56883133056fa55bfa90bdf433b2c4c0c56","tarball":"https://registry.npmjs.org/@best-agent/sdk-ts/-/sdk-ts-0.0.1-beta.1.tgz","fileCount":65,"integrity":"sha512-p5sHXSbd3k86/Q2vuF67nOJb1AN+25xrFYZALtWWZqci84dw8qWsHqX6/Qy/eRrAOcKJ1rjGp4RfGnURpgjtkw==","signatures":[{"sig":"MEUCIDTTp/BJQONk6rLSsX8v3G2b2bQ1l5+7qG6TbLLcFuARAiEAu405aKjpgxcLTl3gBSB/SBC+QORoKYlb3McEbVtTVfk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":489873},"main":"./dist/index.js","type":"module","_from":"file:best-agent-sdk-ts-0.0.1-beta.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./advanced":{"types":"./dist/advanced.d.ts","default":"./dist/advanced.js"}},"scripts":{"release":"pnpm -w build && pnpm publish --access public --no-git-checks"},"_npmUser":{"name":"simon_he","email":"13917107469@163.com"},"_resolved":"/private/var/folders/z8/w1qvd0cd46z6k8_swl1n33d00000gn/T/ea6bc60be91acba8f3609c6333dfc8c8/best-agent-sdk-ts-0.0.1-beta.1.tgz","_integrity":"sha512-p5sHXSbd3k86/Q2vuF67nOJb1AN+25xrFYZALtWWZqci84dw8qWsHqX6/Qy/eRrAOcKJ1rjGp4RfGnURpgjtkw==","_npmVersion":"10.9.2","description":"External TypeScript client for `best-agent`.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"@best-agent/protocol":"0.0.1-beta.1","@best-agent/foundation":"0.0.1-beta.1"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk-ts_0.0.1-beta.1_1779708565361_0.9769412077217088","host":"s3://npm-registry-packages-npm-production"}},"0.0.2-beta.2":{"name":"@best-agent/sdk-ts","version":"0.0.2-beta.2","_id":"@best-agent/sdk-ts@0.0.2-beta.2","maintainers":[{"name":"simon_he","email":"13917107469@163.com"}],"dist":{"shasum":"34d923c99e34a6f81e6e86f6de5153ecae1029f4","tarball":"https://registry.npmjs.org/@best-agent/sdk-ts/-/sdk-ts-0.0.2-beta.2.tgz","fileCount":65,"integrity":"sha512-EmkCWpl8BLs5xBTtrnd6oTB1dx6F802EY4OpP7e7Xa8yTnC8jQVwmu5TutJw510K1stgInJJCN/XPyLCJLIgDg==","signatures":[{"sig":"MEYCIQCE6QqrHvt1xxWHtjjuwUj/WQ9l0ADA8Gs9wYADo5D9NQIhAL2pZREo2rMxsoFwBPDOrce5q4EWtjM7yDMZR8lk5BnR","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":489873},"main":"./dist/index.js","type":"module","_from":"file:best-agent-sdk-ts-0.0.2-beta.2.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./advanced":{"types":"./dist/advanced.d.ts","default":"./dist/advanced.js"}},"scripts":{"release":"pnpm -w build && pnpm publish --access public --no-git-checks"},"_npmUser":{"name":"simon_he","email":"13917107469@163.com"},"_resolved":"/private/var/folders/z8/w1qvd0cd46z6k8_swl1n33d00000gn/T/71cc1b997a5bff6325168df0324f8645/best-agent-sdk-ts-0.0.2-beta.2.tgz","_integrity":"sha512-EmkCWpl8BLs5xBTtrnd6oTB1dx6F802EY4OpP7e7Xa8yTnC8jQVwmu5TutJw510K1stgInJJCN/XPyLCJLIgDg==","_npmVersion":"10.9.2","description":"External TypeScript client for `best-agent`.","directories":{},"_nodeVersion":"23.11.0","dependencies":{"@best-agent/protocol":"0.0.2-beta.2","@best-agent/foundation":"0.0.2-beta.2"},"_hasShrinkwrap":false,"readmeFilename":"README.md","_npmOperationalInternal":{"tmp":"tmp/sdk-ts_0.0.2-beta.2_1779794953042_0.6936977625794678","host":"s3://npm-registry-packages-npm-production"}},"0.0.2-beta.8":{"name":"@best-agent/sdk-ts","version":"0.0.2-beta.8","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./advanced":{"types":"./dist/advanced.d.ts","default":"./dist/advanced.js"}},"dependencies":{"@best-agent/foundation":"0.0.2-beta.8","@best-agent/protocol":"0.0.2-beta.8"},"scripts":{"release":"pnpm -w build && pnpm publish --access public --no-git-checks"},"_id":"@best-agent/sdk-ts@0.0.2-beta.8","description":"External TypeScript client for `best-agent`.","_integrity":"sha512-B2JLEagOy+4byduEAJyBWTTd34KvhHmoTgKj+Hf0PFdVfix2CNaELdSa3zhuyidTPnF5a4BJ4pzhC9MeNHFdaQ==","_resolved":"/private/var/folders/z8/w1qvd0cd46z6k8_swl1n33d00000gn/T/4cbde86d4b8833ff2e7e41f90cb7c6dc/best-agent-sdk-ts-0.0.2-beta.8.tgz","_from":"file:best-agent-sdk-ts-0.0.2-beta.8.tgz","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-B2JLEagOy+4byduEAJyBWTTd34KvhHmoTgKj+Hf0PFdVfix2CNaELdSa3zhuyidTPnF5a4BJ4pzhC9MeNHFdaQ==","shasum":"18a5ce02cd39527628c0efbdbce9d33411587a49","tarball":"https://registry.npmjs.org/@best-agent/sdk-ts/-/sdk-ts-0.0.2-beta.8.tgz","fileCount":65,"unpackedSize":492891,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIED8H7KMil5QKnhsaJnewkLw/6XxBO2wob+0mc1Ogb22AiEA4q1RCUPf5mDAQFjNdkax10HKiXS25r5X25O6fRcVv5E="}]},"_npmUser":{"name":"simon_he","email":"13917107469@163.com"},"directories":{},"maintainers":[{"name":"simon_he","email":"13917107469@163.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk-ts_0.0.2-beta.8_1780387072101_0.7184248602537349"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-25T11:29:25.239Z","modified":"2026-06-02T07:57:52.392Z","0.0.1-beta.1":"2026-05-25T11:29:25.529Z","0.0.2-beta.2":"2026-05-26T11:29:13.179Z","0.0.2-beta.8":"2026-06-02T07:57:52.256Z"},"description":"External TypeScript client for `best-agent`.","maintainers":[{"name":"simon_he","email":"13917107469@163.com"}],"readme":"# @best-agent/sdk-ts\n\nExternal TypeScript client for `best-agent`.\n\n## Quick Start\n\n```ts\nimport { Agent } from \"@best-agent/sdk-ts\";\n\nconst agent = await Agent.connect();\nconst answer = await agent.prompt(\"Summarize this repo\");\nconsole.log(answer.text);\nawait agent.memory.set(\"This repo uses pnpm.\");\nconsole.log(await agent.memory.get());\n```\n\n## Streaming\n\n```ts\nconst agent = await Agent.connect();\nconst stream = await agent.stream(\"Refactor the auth module\");\n\n// Simple: append-only preview text deltas\nfor await (const chunk of stream.text) {\n  process.stdout.write(chunk);\n}\n```\n\nUse `stream.textEvents` or `stream.events` when a live renderer needs to honor runtime text resets.\n\nStructured events (8-type high-level union):\n\n```ts\nfor await (const event of stream.events) {\n  switch (event.type) {\n    case \"text-delta\":\n      // preview delta only\n      process.stdout.write(event.text);\n      break;\n    case \"tool-call-start\":\n      console.log(`Calling ${event.toolName}...`);\n      break;\n    case \"approval-requested\":\n      console.log(`Approval needed: ${event.summary}`);\n      break;\n  }\n}\n```\n\nCollected result:\n\n```ts\nconst result = await stream.completed;\nconsole.log(result.text);       // settled final text\nconsole.log(result.toolCalls);  // all tool calls\nconsole.log(result.turnId);     // turn ID\n```\n\nFull protocol fidelity (65+ event types) via `stream.rawEvents`.\n\n## Thread Handles\n\n```ts\nconst agent = await Agent.connect();\nconst thread = await agent.threads.create({ mode: \"plan\" });\n\nawait thread.run(\"Build a REST API with auth\");\nawait thread.run(\"Now add rate limiting\");  // continues conversation\n\n// Plan operations\nconst plan = await thread.plan.get();\nawait thread.plan.approve();\n\n// Lifecycle\nawait thread.rename(\"API Project\");\nawait thread.archive();\n```\n\n## Structured Prompt Content\n\n```ts\nconst agent = await Agent.connect();\nconst thread = await agent.threads.create();\n\nawait thread.run({\n  promptContent: [\n    { type: \"text\", text: \"Describe the chart in this screenshot.\" },\n    { type: \"image\", path: \"/absolute/path/to/chart.png\", mediaType: \"image/png\" },\n  ],\n});\n\nawait thread.queue({\n  promptContent: [\n    { type: \"text\", text: \"Summarize this PDF.\" },\n    { type: \"file\", path: \"/absolute/path/to/report.pdf\", mediaType: \"application/pdf\" },\n  ],\n});\n```\n\nWhen `prompt` is omitted, the SDK derives transcript text from any `text` parts in `promptContent`.\n\n## Namespaced APIs\n\n```ts\nagent.threads.list()\nagent.threads.create()\nagent.threads.get(threadId)\nagent.threads.fork(threadId)\n\nagent.approvals.respond(approvalId, \"allow\", { scope: \"session\" })\nagent.approvals.grants.list()\nagent.approvals.grants.revoke(grantId)\n\nagent.tools.list()\nagent.skills.list()\nagent.extensions.list()\nagent.mcp.list()\nagent.profiles.list()\nagent.memory.get()\nagent.memory.set(\"Use pnpm, not npm\")\nagent.memory.clear()\nagent.status()\n```\n\n## Custom Tools & Skills\n\n```ts\nimport { Agent, defineTool, defineSkill } from \"@best-agent/sdk-ts\";\n\nconst agent = await Agent.connect({\n  tools: [\n    defineTool({\n      name: \"get_weather\",\n      description: \"Get current weather for a city\",\n      inputSchema: { type: \"object\", properties: { city: { type: \"string\" } }, required: [\"city\"] },\n      execute: async (input) => JSON.stringify({ temp: 22, city: input.city }),\n    }),\n  ],\n  skills: [\n    defineSkill({\n      name: \"code-review\",\n      description: \"Review code for best practices\",\n      content: \"Review the code for: correctness, performance, readability...\",\n    }),\n  ],\n});\n```\n\n## Connection Options\n\n```ts\n// Zero-config (auto-discovers server)\nconst agent = await Agent.connect();\n\n// Explicit server binary\nconst agent = await Agent.connect({ command: \"./my-server\", args: [\"--verbose\"] });\n\n// Connect to running daemon\nconst agent = await Agent.connect({ transport: \"daemon\", storageRoot: \"~/.best-agent\" });\n\n// Connect via HTTP\nconst agent = await Agent.connect({ transport: \"http\", baseUrl: \"http://localhost:3001\" });\n\n// With provider configuration\nconst agent = await Agent.connect({\n  provider: { kind: \"anthropic\", model: \"claude-sonnet-4-20250514\" },\n  guardian: { enabled: true, model: \"gpt-5-mini\", threshold: 60, timeoutMs: 10_000 },\n});\n```\n\n## Main Exports\n\nHigh-level (recommended):\n\n- `Agent` — the primary facade (`connect()`, `prompt()`, `stream()`)\n- `defineTool(...)` — tool authoring helper\n- `defineSkill(...)` — skill authoring helper\n\nTypes:\n\n- `ThreadHandle` — stateful thread interaction handle\n- `PromptInput` — string or structured multimodal prompt input\n- `TurnStream` — triple-mode streaming (`.text`, `.events`, `.rawEvents`, `.completed`)\n- `StreamEvent` — 8-type high-level event union\n- `TurnResult` — collected turn output\n\nSub-path `@best-agent/sdk-ts/advanced` (escape hatch):\n\n- `AgentClient` — low-level stdio transport client\n- `DaemonAgentClient` — low-level daemon transport client\n- `HttpAgentClient` — low-level HTTP transport client\n- `connectDaemonClient(...)` — daemon bootstrap\n- `connectHttpClient(...)` — HTTP client factory\n- `stopDaemonForStorageRoot(...)`\n\nWhen connecting to an authenticated HTTP server, pass headers through `connectHttpClient(...)`:\n\n```ts\nimport { connectHttpClient } from \"@best-agent/sdk-ts\";\n\nconst client = await connectHttpClient(\"http://127.0.0.1:3000\", {\n  headers: {\n    authorization: `Bearer ${process.env.BEST_AGENT_HTTP_TOKEN ?? \"\"}`,\n  },\n});\n```\n\n## Does Not Own\n\n- provider execution\n- runtime state\n- transport schema definitions\n\nUse this package when embedding the runtime from another Node or TypeScript app.\n","readmeFilename":"README.md"}