{"_id":"@anton-sifta/agents","name":"@anton-sifta/agents","dist-tags":{"latest":"0.0.42"},"versions":{"0.0.42":{"name":"@anton-sifta/agents","version":"0.0.42","description":"Browser-safe agent runtime for the next-generation Cline SDK","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/antonpictures/ANTON-SIFTA.git","directory":"Vendor/alice-cli/sdk/packages/agents"},"main":"dist/index.js","dependencies":{"@anton-sifta/llms":"workspace:*","@anton-sifta/shared":"workspace:*","nanoid":"^5.1.7"},"exports":{".":{"browser":"./dist/index.js","types":"./dist/index.d.ts","import":"./dist/index.js"}},"keywords":["llm","agents","ai","tool-calling"],"license":"Apache-2.0","scripts":{"build":"bun run bun.mts && bun tsc -p tsconfig.build.json","dev":"bun build ./src/index.ts --outdir ./dist --target node --format esm --watch","typecheck":"bun tsc -p tsconfig.dev.json --noEmit","test":"vitest run","test:watch":"vitest"},"engines":{"node":">=22"},"type":"module","types":"dist/index.d.ts","gitHead":"9f42aea85de581ac3a8053726d532f5d5a5463b3","_id":"@anton-sifta/agents@0.0.42","bugs":{"url":"https://github.com/antonpictures/ANTON-SIFTA/issues"},"homepage":"https://github.com/antonpictures/ANTON-SIFTA#readme","_nodeVersion":"25.4.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-SZhv+XcRw75Q5+mDGmiEx8g7A5JT0bmA+v75vP6K7dXaB0CAxe7tTsA3CI/JeLFqMZTwtwf58az0VbbF9juNiQ==","shasum":"ee0715425c9d7fc2c11d615d7bf22fbe65474882","tarball":"https://registry.npmjs.org/@anton-sifta/agents/-/agents-0.0.42.tgz","fileCount":11,"unpackedSize":4530081,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCRJdJmF9HNhnpk2XtW5w7yR50ehyVd7zptg5GtB9cd0gIgY/rNzYxkuF9Z83ZGzbsIUly+lFTVrGU+tbkjifme4A8="}]},"_npmUser":{"name":"ioangeorgeanton","email":"antonpictures@me.com"},"directories":{},"maintainers":[{"name":"ioangeorgeanton","email":"antonpictures@me.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agents_0.0.42_1780075219891_0.5927933639352845"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-29T17:20:19.757Z","0.0.42":"2026-05-29T17:20:20.184Z","modified":"2026-05-29T17:20:20.402Z"},"maintainers":[{"name":"ioangeorgeanton","email":"antonpictures@me.com"}],"description":"Browser-safe agent runtime for the next-generation Cline SDK","homepage":"https://github.com/antonpictures/ANTON-SIFTA#readme","keywords":["llm","agents","ai","tool-calling"],"repository":{"type":"git","url":"git+https://github.com/antonpictures/ANTON-SIFTA.git","directory":"Vendor/alice-cli/sdk/packages/agents"},"bugs":{"url":"https://github.com/antonpictures/ANTON-SIFTA/issues"},"license":"Apache-2.0","readme":"# [experimental] @cline/agents\n\n`@cline/agents` is the runtime-agnostic agent loop package in the Cline SDK.\nIt gives you the core primitives for building tool-using LLM agents without\nbringing in session storage, hub transport, or host-specific default tools.\n\n## What You Get\n\n- `Agent` / `AgentRuntime` — the same class under two names — for running and\n  continuing tool-using agent conversations\n- `createAgent` / `createAgentRuntime` — factory-function equivalents\n- `AgentRuntimeHooks` for lifecycle interception (`beforeRun`, `afterRun`,\n  `beforeModel`, `afterModel`, `beforeTool`, `afterTool`, `onEvent`)\n- Event streaming via `agent.subscribe(listener)` and the `hooks.onEvent`\n  callback\n- Plugin setup callbacks for contributing tools and hooks at boot\n\n## What This Package Does Not Include\n\n`@cline/agents` does not ship a full application runtime by itself.\n\n- Default host tools like filesystem access, shell execution, or web fetching live in `@cline/core`\n- Session persistence and stateful orchestration live in `@cline/core`\n- Shared hub runtime/session transport lives in `@cline/core` (see `@cline/core/hub`)\n- Sub-agent and team coordination primitives live in `@cline/core`\n\nThat split keeps this package usable in Node, browser, and custom host\nenvironments where you want to supply your own tools and runtime policy.\n\n## Installation\n\n```bash\nnpm install @cline/agents @cline/shared @cline/llms\n```\n\n## Quick Start\n\n```ts\nimport { Agent } from \"@cline/agents\";\nimport type { AgentTool } from \"@cline/shared\";\n\nconst getWeather: AgentTool<{ city: string }, { forecast: string }> = {\n\tname: \"get_weather\",\n\tdescription: \"Return the current weather for a city.\",\n\tinputSchema: {\n\t\ttype: \"object\",\n\t\tproperties: { city: { type: \"string\" } },\n\t\trequired: [\"city\"],\n\t},\n\tasync execute({ city }) {\n\t\treturn { forecast: `sunny in ${city}` };\n\t},\n};\n\nconst agent = new Agent({\n\tproviderId: \"anthropic\",\n\tmodelId: \"claude-sonnet-4-6\",\n\tapiKey: process.env.ANTHROPIC_API_KEY,\n\tsystemPrompt: \"You are a concise assistant.\",\n\ttools: [getWeather],\n});\n\nconst result = await agent.run(\"What's the weather in San Francisco?\");\nconsole.log(result.outputText);\n```\n\n## Two Ways to Configure\n\n`Agent` / `AgentRuntime` accepts two config shapes:\n\n**Provider form** — friendly entrypoint. The runtime builds an `AgentModel` for\nyou via `@cline/llms`:\n\n```ts\nnew Agent({\n\tproviderId: \"openai\",\n\tmodelId: \"gpt-5\",\n\tapiKey: process.env.OPENAI_API_KEY,\n\t// baseUrl, headers also supported\n\ttools: [/* ... */],\n});\n```\n\n**Model form** — advanced. Supply a pre-built `AgentModel` directly. Useful\nwhen the host already owns gateway construction (this is what `@cline/core`\nuses internally):\n\n```ts\nimport { createGateway } from \"@cline/llms\";\n\nconst gateway = createGateway({ providerConfigs: [/* ... */] });\nconst model = gateway.createAgentModel({ providerId, modelId });\n\nnew Agent({\n\tmodel,\n\ttools: [/* ... */],\n});\n```\n\n## Core Concepts\n\n### Tools\n\nTools conform to the `AgentTool<TInput, TOutput>` interface from\n`@cline/shared`. Each tool has a JSON Schema `inputSchema` and an\n`execute(input, context)` function that returns the tool output directly:\n\n```ts\nimport type { AgentTool } from \"@cline/shared\";\n\nconst summarize: AgentTool<{ text: string }, { summary: string }> = {\n\tname: \"summarize_text\",\n\tdescription: \"Summarize text into a short preview.\",\n\tinputSchema: {\n\t\ttype: \"object\",\n\t\tproperties: { text: { type: \"string\" } },\n\t\trequired: [\"text\"],\n\t},\n\tasync execute({ text }, context) {\n\t\t// context.signal — aborts when the run is cancelled\n\t\t// context.emitUpdate(...) — stream progress as `tool-updated` events\n\t\treturn { summary: text.slice(0, 120) };\n\t},\n};\n```\n\nThe runtime wraps successful tool outputs in an internal tool-result message.\nThrow from `execute(...)` to report a tool failure, or use an `afterTool` hook\nto transform the internal `AgentToolResult` envelope.\n\n### Events\n\nSubscribe to the `AgentRuntimeEvent` stream in one of two ways:\n\n```ts\n// 1. Attach a listener after construction. Returns an unsubscribe function.\nconst unsubscribe = agent.subscribe((event) => {\n\tif (event.type === \"assistant-text-delta\") {\n\t\tprocess.stdout.write(event.text);\n\t}\n});\n\n// 2. Register an `onEvent` hook at construction time.\nnew Agent({\n\tproviderId,\n\tmodelId,\n\tapiKey,\n\thooks: {\n\t\tonEvent(event) {\n\t\t\t// fires for every runtime event\n\t\t},\n\t},\n});\n```\n\n`AgentRuntimeEvent` covers run/turn boundaries, assistant text and reasoning\ndeltas, tool lifecycle, usage updates, and run completion/failure. See\n`AgentRuntimeEvent` in `@cline/shared` for the full union.\n\n### Conversation Control\n\n- `agent.run(input)` — start a run. `input` may be a string, an `AgentMessage`,\n  or an array of messages. Also accepts `undefined` to continue without adding\n  a new user turn.\n- `agent.continue(input?)` — convenience alias for `run(input?)`.\n- `agent.abort(reason?)` — cancel the active run. `.run()` resolves with\n  `status: \"aborted\"`.\n- `agent.snapshot()` — immutable view of the current\n  `AgentRuntimeStateSnapshot` (messages, usage, iteration, status, etc.).\n- `agent.restore(messages)` — replace the conversation with a persisted\n  message array. Resets run/turn state but preserves subscribers, tools,\n  hooks, plugins, and the model.\n- `initialMessages` in the constructor seeds the conversation on boot.\n\n### Hooks\n\nPass a `hooks` bag (`AgentRuntimeHooks`) to observe or influence the loop.\nAll hooks may be async; any that return `{ stop: true, reason }` will halt the\nrun with an `aborted` status.\n\n```ts\nnew Agent({\n\tproviderId,\n\tmodelId,\n\tapiKey,\n\ttools: [/* ... */],\n\thooks: {\n\t\tbeforeModel({ request }) {\n\t\t\t// mutate messages/tools/options before the model call\n\t\t\treturn { options: { temperature: 0.2 } };\n\t\t},\n\t\tbeforeTool({ tool, input }) {\n\t\t\t// block a tool call based on policy\n\t\t\tif (tool.name === \"get_weather\" && !(input as { city?: string }).city) {\n\t\t\t\treturn { skip: true, reason: \"city required\" };\n\t\t\t}\n\t\t\treturn undefined;\n\t\t},\n\t\tafterRun({ result }) {\n\t\t\tconsole.log(\"done\", result.usage);\n\t\t},\n\t},\n});\n```\n\nFor richer, host-side hook orchestration (15-stage `HookEngine`,\nsubprocess-backed hooks, MCP extensions), use `@cline/core`.\n\n### Plugins\n\nPlugins can contribute tools and hooks at setup time:\n\n```ts\nimport type { AgentRuntimePlugin } from \"@cline/shared\";\n\nconst loggingPlugin: AgentRuntimePlugin = {\n\tname: \"logging\",\n\tsetup({ agentId }) {\n\t\treturn {\n\t\t\thooks: {\n\t\t\t\tafterTool({ tool, result }) {\n\t\t\t\t\tconsole.log(agentId, tool.name, result.isError);\n\t\t\t\t\treturn undefined; // hook may return an AgentAfterToolResult\n\t\t\t\t},\n\t\t\t},\n\t\t};\n\t},\n};\n\nnew Agent({\n\tproviderId,\n\tmodelId,\n\tapiKey,\n\tplugins: [loggingPlugin],\n});\n```\n\n### Teams and Spawn\n\nFor multi-agent workflows, use `@cline/core`:\n\n```ts\nimport {\n\tcreateSpawnAgentTool,\n\tAgentTeamsRuntime,\n\tcreateAgentTeamsTools,\n\tbootstrapAgentTeams,\n} from \"@cline/core\";\n```\n\nThese helpers provide coordination primitives for delegated runs,\nmailboxes, task management, and outcome convergence.\n\n## Entry Point\n\n- `@cline/agents` — the single package entrypoint. The `package.json`\n  `exports` map automatically serves a browser-safe bundle when bundlers\n  resolve the `browser` condition.\n\n## Related Packages\n\n- `@cline/shared`: shared types (`AgentTool`, `AgentMessage`,\n  `AgentRuntimeEvent`, `AgentRuntimeHooks`, etc.)\n- `@cline/llms`: provider settings, model catalogs, and gateway/handler\n  creation\n- `@cline/core`: stateful runtime assembly, storage, default tools,\n  subprocess hooks, hub transport, and MCP integration\n\n## More Examples\n\n- Repo examples:\n  [examples/plugins](https://github.com/cline/sdk/tree/main/examples/plugins),\n  [examples/hooks](https://github.com/cline/sdk/tree/main/examples/hooks),\n  [examples/cron](https://github.com/cline/sdk/tree/main/examples/cron)\n- Workspace overview: [README.md](https://github.com/cline/sdk/blob/main/README.md)\n- API and architecture references:\n  [DOC.md](https://github.com/cline/sdk/blob/main/DOC.md),\n  [ARCHITECTURE.md](https://github.com/cline/sdk/blob/main/ARCHITECTURE.md)\n","readmeFilename":"README.md","_rev":"1-6f26b5401a84945fbfc2a79bf3134e0c"}