@robota-sdk/agent-core 3.0.0-beta.1 → 3.0.0-beta.100

package/README.md

@@ -1,230 +1,341 @@
 # @robota-sdk/agent-core
 
-The comprehensive AI agent framework with type-safe architecture and advanced plugin system.
-
-## Overview
-
-The `@robota-sdk/agent-core` package is the unified core of the Robota SDK, providing a complete AI agent system with advanced capabilities for conversation management, tool execution, and extensible plugin architecture.
+The foundation of the Robota SDK. It provides the `ConversationAgent` class (a conversation loop with
+tool calling), the provider, tool and plugin contracts with their abstract base classes, the
+permission evaluator, the hook runner, event services, typed errors, model metadata, and structured
+output. It has no `@robota-sdk/*` dependencies; every other agent runtime package builds on it.
 
 ## Installation
 
 ```bash
 npm install @robota-sdk/agent-core
-# or
-pnpm add @robota-sdk/agent-core
 ```
 
+Requires Node.js 22.12 or later. A provider package supplies the model connection, for example
+`@robota-sdk/agent-provider-anthropic`.
+
 ## Quick Start
 
 ```typescript
-import { Robota } from '@robota-sdk/agent-core';
-import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
+import { ConversationAgent } from '@robota-sdk/agent-core';
+import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 
-const openaiProvider = new OpenAIProvider({ apiKey: 'sk-...' });
+const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });
 
-const agent = new Robota({
+const agent = new ConversationAgent({
   name: 'MyAgent',
-  aiProviders: [openaiProvider],
+  aiProviders: [provider],
   defaultModel: {
-    provider: 'openai',
-    model: 'gpt-4',
-    systemMessage: 'You are a helpful assistant.',
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-6',
   },
+  systemMessage: 'You are a helpful assistant.',
 });
 
 const response = await agent.run('Hello, world!');
 console.log(response);
 ```
 
-### Browser Quick Start
+`defaultModel.provider` names one of the `aiProviders` by its `name` (`'anthropic'` here).
+
+## What it provides
+
+- **`ConversationAgent`** — an agent with conversation history, automatic tool execution, plugins, streaming
+  (`runStream`) and structured output. By default history accumulates across runs; set
+  `retainHistory: false` to start every run from the system prompt.
+- **Messages** — every message (`TUniversalMessage`) has a unique `id` and a `state`
+  (`'complete'` or `'interrupted'`). `ConversationStore` is the append-only history with a streaming
+  buffer.
+- **Multiple providers** — register several providers and switch with `setModel()`. Providers extend
+  `AbstractAIProvider` and report capabilities (`getProviderCapabilities`), including whether they
+  offer hosted web search/fetch.
+- **Tools** — `FunctionTool` and `ToolRegistry` live here, next to the `AbstractTool` base class and
+  the tool schema contract. Ready-made tools are in `@robota-sdk/agent-tools`.
+- **Permissions** — `evaluatePermission` decides a tool call from the permission mode and
+  allow/deny/ask rules; it is the one evaluator every agent runtime caller uses.
+- **Hooks** — `runHooks` runs the lifecycle hooks configured for an event. See the
+  [hook event catalog](./docs/HOOK-CATALOG.md).
+- **Plugins** — `AbstractPlugin` with lifecycle hooks (`beforeRun`, `afterRun`, `onError`, …).
+  Ready-made plugins are in `@robota-sdk/agent-plugin`.
+- **Events** — event services with owner-path tracking and `EventEmitterPlugin`.
+- **Errors** — typed errors extending `AgentRuntimeError`, such as `ProviderError`, `RateLimitError`,
+  `ToolExecutionError` and `StructuredOutputError`.
+- **Model metadata** — providers register their own models with `registerModelMetadata()`; core
+  owns the registry and the lookups (`getModelContextWindow()`, `getModelMaxOutput()`, …), not any
+  vendor's catalogue.
+- **Cancellation** — an `AbortSignal` passed in run options reaches the provider call.
+
+## agent runtime API
 
 ```typescript
-import { Robota, LoggingPlugin, UsagePlugin } from '@robota-sdk/agent-core';
-import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
+import { ConversationAgent } from '@robota-sdk/agent-core';
+import type { IAgentConfig } from '@robota-sdk/agent-core';
 
-const openaiProvider = new OpenAIProvider({
-  apiKey: process.env.NEXT_PUBLIC_OPENAI_API_KEY, // or proxy endpoint
-});
+declare const config: IAgentConfig;
+const agent = new ConversationAgent(config);
 
-// Browser-optimized configuration
-const agent = new Robota({
-  name: 'BrowserAgent',
-  aiProviders: [openaiProvider],
-  defaultModel: {
-    provider: 'openai',
-    model: 'gpt-3.5-turbo',
-  },
-  plugins: [
-    new LoggingPlugin({ strategy: 'console' }), // Console logging
-    new UsagePlugin({ strategy: 'memory' }), // Memory storage
-  ],
-});
+// Send a message (tool calls are executed automatically)
+const response = await agent.run('Hello');
 
-const response = await agent.run('Hello from browser!');
-console.log(response);
-```
+// Conversation history
+const history = agent.getHistory(); // TUniversalMessage[]
+agent.clearHistory();
 
-## Key Features
+// Switch provider/model mid-conversation (the provider must be registered in aiProviders)
+agent.setModel({ provider: 'openai', model: 'gpt-4o' });
 
-### 🌐 Cross-Platform Compatibility
+// Release the agent's resources when you are done
+await agent.destroy();
+```
 
-- **Universal Runtime Support**: Works seamlessly in Node.js, browsers, and WebWorkers
-- **Zero Breaking Changes**: Existing Node.js code runs unchanged in browsers
-- **Pure JavaScript Implementation**: No Node.js-specific dependencies in core functionality
-- **Browser-Optimized Storage**: Memory-based alternatives for file system operations
-- **Secure API Patterns**: Proxy server support for secure browser deployments
+### Structured output
 
-### 🤖 Agent System
+`run(input, { output })` returns a schema-validated object instead of a string. A Zod schema gives a
+typed result. The schema is sent to the provider's native structured-output support where one
+exists, and the response is always validated by core with a bounded retry on violation
+(`outputRetries`, default 2). When the retries are used up, `run` throws `StructuredOutputError`.
 
-- **Type-Safe Architecture**: Full TypeScript support with generic type parameters
-- **Robota Class**: Complete AI agent implementation with conversation + tool system + plugin integration
-- **Stateless Service Layer**: ConversationService, ToolExecutionService, ExecutionService for business logic
-- **Manager Layer**: AIProviders, Tools, AgentFactory, Plugins, ConversationHistory for resource management
-- **Parallel Tool Execution**: Concurrent multi-tool calling support
+```typescript
+import { z } from 'zod';
+import { ConversationAgent } from '@robota-sdk/agent-core';
+import type { IAgentConfig } from '@robota-sdk/agent-core';
 
-### 🌊 Streaming Response System
+declare const config: IAgentConfig;
+const agent = new ConversationAgent(config);
 
-- **Real-time Streaming**: Full streaming support across all AI providers
-- **Modular Architecture**: Separate streaming/parsing logic for each provider
-- **Provider Support**: OpenAI, Anthropic, Google with dedicated stream handlers
+const reportSchema = z.object({
+  title: z.string(),
+  score: z.number(),
+  summary: z.string(),
+});
 
-### 🔧 Tool System
+// Typed result: { title: string; score: number; summary: string }
+const report = await agent.run('Summarize the meeting as a report.', {
+  output: reportSchema,
+});
 
-- **Type-Safe Tools**: `BaseTool<TParameters, TResult>` with compile-time type checking
-- **ToolRegistry**: Schema storage and validation system
-- **Function Tools**: Zod schema-based function tool implementation
-- **OpenAPI/MCP Support**: Basic structure for extensibility
+// Streaming variant: text deltas stream as usual; the validated object is the
+// generator's return value (the final { done: true, value } iterator result).
+const stream = agent.runStream('Summarize again.', { output: reportSchema });
+const iterator = stream[Symbol.asyncIterator]();
+let next = await iterator.next();
+while (!next.done) {
+  process.stdout.write(next.value);
+  next = await iterator.next();
+}
+const streamedReport = next.value;
+console.log(report.title, streamedReport.title);
+```
 
-## Recent Updates
+A raw JSON-schema wrapper is also accepted:
+`{ output: { jsonSchema: { type: 'object', properties: { answer: { type: 'string' } }, required: ['answer'] } } }`.
 
-- Tool execution results preserve `executionId` mappings for both success and failure to keep deterministic ordering.
+### Model options per run
 
-### 🔌 Plugin System
+`run` and `runStream` accept run-scoped model options that win over `defaultModel.*`: `maxTokens`,
+`temperature` and `toolChoice`. `toolChoice` controls tool calls: `'auto'` (the model decides),
+`'none'` (no tool calls), `'required'` (must call some tool), or `{ tool: name }` (must call that
+tool). Naming a tool that is not in the run's tool list throws immediately. A forcing directive
+applies to the run's first model call only; later rounds revert to `'auto'` so the model can use the
+tool results and finish.
 
-Eight core plugins with type-safe configuration and BasePluginOptions integration:
+```typescript
+import { ConversationAgent } from '@robota-sdk/agent-core';
+import type { IAgentConfig } from '@robota-sdk/agent-core';
 
-- **ConversationHistoryPlugin**: Comprehensive conversation storage with support for memory, file, and database backends. Features auto-save, batch processing, and configurable limits.
-- **UsagePlugin**: Advanced usage analytics including token counting, cost calculation, aggregated statistics, and multiple storage strategies (memory/file/remote).
-- **LoggingPlugin**: Multi-level logging system with console, file, and remote endpoints. Supports custom formatters, batch processing, and structured logging.
-- **PerformancePlugin**: Real-time performance monitoring including execution time tracking, memory usage, CPU metrics, and customizable performance thresholds.
-- **ErrorHandlingPlugin**: Robust error management with multiple strategies (simple, exponential-backoff, circuit-breaker, silent) and custom error handlers.
-- **LimitsPlugin**: Advanced rate limiting with token bucket, sliding window, and fixed window strategies. Supports cost tracking and custom calculators.
-- **EventEmitterPlugin**: Comprehensive event system with async/sync event handling, filtering, buffering, and lifecycle event tracking.
-- **WebhookPlugin**: HTTP webhook notifications with batch processing, retry logic, custom transformers, and concurrent request management.
+declare const config: IAgentConfig;
+const agent = new ConversationAgent(config);
 
-#### Plugin Features
+// Force the model to answer through a router tool (decision-agent pattern)
+const decision = await agent.run('Route this request.', {
+  toolChoice: { tool: 'route-request' },
+  allowToolOnlyCompletion: true,
+});
 
-- **Type Safety**: All plugins extend BasePluginOptions for consistent configuration
-- **Lifecycle Integration**: Automatic integration with agent lifecycle events
-- **Resource Management**: Built-in cleanup and resource optimization
-- **Performance Monitoring**: All plugins include built-in statistics and monitoring
-- **Error Resilience**: Graceful error handling across all plugin operations
+// Suppress tools for a plain-text turn, capped at 100 output tokens
+const summary = await agent.run('Summarize the discussion.', {
+  toolChoice: 'none',
+  maxTokens: 100,
+});
+console.log(decision, summary);
+```
 
-#### Plugin Control and Configuration
+The same directive can be set for every run with `defaultModel.toolChoice`.
 
-- **Clear Disable Options**: Every plugin provides multiple ways to disable functionality
-- **No Arbitrary Decisions**: Plugins avoid making policy decisions without explicit configuration
-- **Explicit Configuration**: All automatic behaviors can be controlled through configuration
-- **Silent Modes**: Most plugins support 'silent' strategies for performance-critical scenarios
+### Model effort
 
-```typescript
-// Complete plugin disable
-const agent = new Robota({
-  plugins: [], // No plugins
-});
+`defaultModel.effort` and the per-call `IChatOptions.effort` accept `auto`, `none`, `minimal`,
+`low`, `medium`, `high`, `xhigh` or `max`. `auto` is passed through to the provider adapter, which
+applies the model's documented default. The adapter reports what it actually sent through
+`onModelEffortOutcome`; core does not guess vendor field names or defaults.
 
-// Selective plugin disable
-const agent = new Robota({
-  plugins: [
-    new LoggingPlugin({ strategy: 'silent', enabled: false }),
-    new LimitsPlugin({ strategy: 'none' }),
-    new UsagePlugin({ strategy: 'silent' }),
-  ],
-});
-```
+### Execution events and usage
 
-#### Plugin Documentation
+`run()` accepts an `onExecutionEvent` callback in its options. The execution loop reports
+provider-neutral events that a higher layer can persist as an append-only record of the run,
+including `provider_request`, `provider_native_raw_payload`, `provider_stream_raw_delta`,
+`provider_response_raw`, `provider_response_normalized`, `assistant_message_committed`,
+`tool_batch_started`, `tool_execution_request`, `tool_execution_result`, `tool_message_committed`
+and `history_mutation`. `@robota-sdk/agent-session` writes these events to its session log.
 
-- **[Plugin Guide](./docs/PLUGINS.md)**: Unified plugin behavior and configuration guide
+Capturing a vendor SDK's exact payloads stays in the provider package: a provider calls
+`IChatOptions.onProviderNativeRawPayload`, and `ConversationAgent` forwards it as a
+`provider_native_raw_payload` event without importing vendor SDK types.
 
-### 🔒 Type Safety Features
+Each provider call gets a `usageObservationId`. Streaming fragments of one call share it, and a
+separately billed call gets a new one, so stored analytics can deduplicate usage by identity.
 
-- **Generic Type Parameters**: `BaseAgent<TConfig, TContext, TMessage>`
-- **Provider Agnostic**: Dynamic provider registration with type safety
-- **Extended RunContext**: Provider-specific options with type preservation
-- **Plugin Type Parameters**: `BasePlugin<TOptions, TStats>` for specialized configurations
+`sumMessagesUsage(messages)` sums the usage providers reported on assistant messages. The usage of
+one run, tool rounds included, is the sum over the messages that run appended:
 
-## Architecture
+```typescript
+import { ConversationAgent, sumMessagesUsage } from '@robota-sdk/agent-core';
+import type { IAgentConfig } from '@robota-sdk/agent-core';
 
-### Core Abstraction Layers
+declare const config: IAgentConfig;
+const agent = new ConversationAgent(config);
 
-```
-BaseAgent<TConfig, TContext, TMessage> (Abstract Class)
-└── Robota (Implementation - AI conversation + tool system + plugins)
-
-BaseAIProvider<TConfig, TMessage, TResponse>
-├── OpenAIProvider (via @robota-sdk/agent-provider-openai)
-├── AnthropicProvider (via @robota-sdk/agent-provider-anthropic)
-└── GoogleProvider (via @robota-sdk/agent-provider-google)
-
-BaseTool<TParameters, TResult>
-├── FunctionTool (Zod schema-based)
-├── OpenAPITool (API specification-based)
-└── MCPTool (Model Context Protocol)
-
-BasePlugin<TOptions, TStats>
-├── Core Plugins (8 essential plugins)
-└── Custom Plugins (User-defined extensions)
+const before = agent.getHistory().length;
+await agent.run('Summarize the open issues.');
+const usage = sumMessagesUsage(agent.getHistory().slice(before));
 ```
 
-### Module Structure
+`cacheReadTokens`, the part of `promptTokens` the provider served from its prompt cache, is present
+only when a provider reports it (the OpenAI and OpenAI-compatible providers do).
+
+## IAgentConfig
+
+The main fields:
+
+| Field                   | Type                       | Description                                                |
+| ----------------------- | -------------------------- | ---------------------------------------------------------- |
+| `name`                  | `string`                   | Agent name                                                 |
+| `aiProviders`           | `IAIProvider[]`            | One or more provider instances                             |
+| `defaultModel.provider` | `string`                   | Name of the provider to use                                |
+| `defaultModel.model`    | `string`                   | Model identifier                                           |
+| `systemMessage`         | `string?`                  | System prompt                                              |
+| `tools`                 | `IToolWithEventService[]?` | Tools the agent can call                                   |
+| `plugins`               | `IPluginContract[]?`       | Plugins that receive lifecycle hooks                       |
+| `retainHistory`         | `boolean?`                 | Keep history across runs (default `true`)                  |
+| `maxExecutionRounds`    | `number?`                  | Cap on model-call rounds per run (`0` means no cap)        |
+| `isToolVisible`         | `(name) => boolean`        | Hide a registered tool from the model, checked every round |
+
+`toolExecutionPolicy(calls)` is a trusted host callback evaluated for each model tool round.
+It receives a copy of that round's calls and returns a policy keyed by call ID. `dependsOn`
+requires successful predecessor results before dispatch; failed predecessors produce skipped
+receipts. Resource claims use a host-chosen asset identity shared across plugins: readers may
+share a resource, while a writer excludes readers and other writers. Omitted claims mean unknown
+shared state and serialize conservatively; `resources: []` explicitly permits independent work.
+`maxConcurrency` bounds active calls, and `continueOnError: false` skips queued calls after a
+failure while retaining already started outcomes. `mode: 'sequential'` limits dispatch to one call.
+
+Claims are copied and validated before dispatch. Unknown IDs, cycles, and invalid resource claims
+refuse the batch with paired skipped results. The policy grants no permissions and does not retry
+mutations. Coordination is within one batch; hosts sharing assets across sessions must provide
+coordination at their effect boundary. Callers of the lower-level batch service opt into resource
+scheduling by supplying `scheduling`; its existing unplanned strategies retain their behavior.
+
+## Entry points
+
+| Import path                      | What it contains                                                                                                                                                                                           |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@robota-sdk/agent-core`         | The main API, listed under Main exports. It also has a browser build: nothing in its static import graph uses Node built-ins.                                                                              |
+| `@robota-sdk/agent-core/node`    | Node-only pieces: the `CommandExecutor` and `HttpExecutor` hook executors, path containment (`canonicalizePath`, `isPathInside`), owner-only file writes, and the egress policy (`fetchWithEgressPolicy`). |
+| `@robota-sdk/agent-core/testing` | Test fixtures: `createScriptedProvider`, `createRecordingProvider`, `createReplayProvider`.                                                                                                                |
+
+When you pass no executors, `runHooks` loads `CommandExecutor` and `HttpExecutor` on demand (this
+needs Node). Import them from `@robota-sdk/agent-core/node` only to pass them explicitly.
+
+## Main exports
+
+| Area                   | Exports                                                                                                                                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Agent**              | `ConversationAgent`, `ConversationStore`, `ConversationHistory`, `AbstractAgent`, `AgentFactory`, `AgentTemplates`                                                                                                       |
+| **Providers**          | `AbstractAIProvider`, `IAIProvider`, `IChatOptions`, `IProviderCapabilities`, `getProviderCapabilities`, `assertProviderNativeWebToolsAvailable`, `IProviderDefinition`, `createProviderFromConfig`                      |
+| **Media providers**    | `IImageGenerationProvider`, `IVideoGenerationProvider`, `isImageGenerationProvider`, `isVideoGenerationProvider`, `createImageProviderFromDefinition`, `createVideoProviderFromDefinition`, `resolveMediaProviderConfig` |
+| **Tools**              | `FunctionTool`, `ToolRegistry`, `AbstractTool`, `IToolSchema`, `IToolResult`, `zodToJsonSchema`                                                                                                                          |
+| **Execution**          | `AbstractExecutor`, `LocalExecutor`, `IExecutor`                                                                                                                                                                         |
+| **Permissions**        | `evaluatePermission`, `projectPermissionPolicy`, `RISK_CLASS_POLICY`, `UNCLASSIFIED_TOOL_FALLBACK`, `TRUST_TO_MODE`, `TPermissionMode`, `TTrustLevel`, `TPermissionDecision`, `TToolArgs`, `IPermissionLists`            |
+| **Hooks**              | `runHooks`, `GuardrailExecutor`, `decodeHookVerdict`, `isEnforcing`, `THookEvent`, `THooksConfig`, `IHookGroup`, `THookDefinition`, `IHookInput`, `THookOutcome`, `IHookTypeExecutor`                                    |
+| **Plugins and events** | `AbstractPlugin`, `EventEmitterPlugin`, `IEventService`, `IOwnerPathSegment`                                                                                                                                             |
+| **Orchestration**      | Contracts for multi-agent orchestration (`ISequentialOrchestrationSpec`, `IParallelOrchestrationSpec`, …, `ORCHESTRATION_EVENTS`); the runners are in `@robota-sdk/agent-framework`                                      |
+| **Models**             | `registerModelMetadata`, `getModelContextWindow`, `getModelMaxOutput`, `getModelName`, `formatTokenCount`, `DEFAULT_CONTEXT_WINDOW`, `DEFAULT_MAX_OUTPUT`, `IModelDefinition`                                            |
+| **Context and usage**  | `estimateContextTokensFromMessages`, `estimateSerializedContextTokens`, `readTokenUsageFromMessage`, `sumMessagesUsage`, `IContextWindowState`, `IContextTokenUsage`                                                     |
+| **Messages**           | `TUniversalMessage`, `IBaseMessage`, `TMessageState`, `createUserMessage`, `createAssistantMessage`, `isAssistantMessage`, …                                                                                             |
+| **Errors**             | `AgentRuntimeError`, `ProviderError`, `RateLimitError`, `AuthenticationError`, `ToolExecutionError`, `StructuredOutputError`, `classifyProviderFailure`, `toProviderError`                                               |
+
+## Where it sits
 
 ```
-packages/agents/src/
-├── abstracts/           # Abstract base classes with type parameters
-├── interfaces/          # Type-safe interface definitions
-├── agents/             # Main agent system
-│   ├── managers/       # Resource managers
-│   ├── services/       # Stateless business logic
-│   └── tools/          # Tool system
-├── plugins/            # Plugin system with Facade pattern
-└── utils/              # Core utilities
+agent-core            ← this package (no workspace dependencies)
+  ↑
+agent-tools, agent-session, agent-plugin, agent-mcp, agent-provider-* (one package per vendor)
+  ↑
+agent-framework       ← assembles sessions, commands, permissions and hooks
+  ↑
+agent-cli             ← the reference host
 ```
 
-## Development
+- Built-in tools (Shell, Read, Edit, …): `@robota-sdk/agent-tools`
+- Ready-made plugins (logging, usage, limits, …): `@robota-sdk/agent-plugin`
+- MCP servers and tools: `@robota-sdk/agent-mcp`
+- Sessions with permissions, hooks and compaction: `@robota-sdk/agent-session`
 
-See [Development Guide](./docs/DEVELOPMENT.md) for development guidelines.
+## Repository examples
 
-## API Reference
+From `packages/agent-core` in a built checkout of the repository, these scripts exercise hooks
+without a live model: `node examples/hook-block-demo.mjs`, `node examples/hook-json-response-demo.mjs`,
+`node examples/hook-permission-mode-demo.mjs` and `node examples/hook-timeout-demo.mjs`.
 
-See [api.md](api.md) for complete API documentation.
+The default outbound HTTP transport uses the installed Undici entry so Bun's built-in replacement
+cannot discard its connection pinning. After `pnpm --filter @robota-sdk/agent-core build`, run the
+same disposable HTTP fixture from the repository root in each runtime:
 
-## Architecture Guide
-
-See [Architecture](./docs/ARCHITECTURE.md) for detailed architecture information.
+```sh
+node packages/agent-core/src/utils/fixtures/egress-runtime-smoke.mjs
+bun packages/agent-core/src/utils/fixtures/egress-runtime-smoke.mjs
+egress_fixture_dir=$(mktemp -d)
+bun build --compile --minify packages/agent-core/src/utils/fixtures/egress-runtime-smoke.mjs --outfile "$egress_fixture_dir/egress-smoke"
+"$egress_fixture_dir/egress-smoke"
+rm -rf "$egress_fixture_dir"
+```
 
-## Examples
+The fixture explicitly permits its local server and connects an otherwise unresolvable hostname
+to an injected address. It checks the built helper and Bun compilation, not a full CLI session,
+provider isolation or physical worker egress. The socket and TLS test suites cover destination
+refusal, redirects, cleanup and certificate identity separately. A trusted injected `fetch` owns
+its own connection policy; it does not inherit the default transport's pinning guarantee.
 
-- [Basic Usage](../../../docs/examples/basic-usage.md)
-- [Browser Usage](../../../docs/examples/browser-usage.md) 🌐
-- [Tool Integration](../../../docs/examples/tool-integration.md)
-- [Plugin Development](../../../docs/examples/plugin-development.md)
-- [Streaming Responses](../../../docs/examples/streaming.md)
+## Documentation
 
-## Package Compatibility
+- [docs/SPEC.md](./docs/SPEC.md) — package contract and design decisions
+- [docs/HOOK-CATALOG.md](./docs/HOOK-CATALOG.md) — hook events, input fields and blocking semantics
+- [Building agents](../../content/guide/building-agents.md) — a walkthrough of `ConversationAgent`, tools and
+  structured output
+- [Permissions and hooks](../../content/guide/permissions-and-hooks.md)
 
-### Integrated Packages
+## License
 
-- **@robota-sdk/agent-provider-openai**: Complete agents standard migration
-- **@robota-sdk/agent-provider-anthropic**: Complete agents standard migration
-- **@robota-sdk/agent-provider-google**: Complete agents standard migration
-- **@robota-sdk/agent-team**: assignTask MCP tool collection (team creation removed)
+This package is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).
 
-### Deprecated Packages
+## Provider lifetime
 
-- **@robota-sdk/core**: Deprecated - functionality moved to agents
-- **@robota-sdk/agent-tools**: Deprecated - functionality moved to agents
+Agents close their providers on destruction by default. A host that owns a longer-lived client
+can borrow it explicitly while keeping its existing provider array:
 
-## License
+```typescript
+const agent = new ConversationAgent({
+  name: 'borrower',
+  aiProviders: [provider],
+  providerOwnership: { [provider.name]: 'borrowed' },
+  defaultModel: { provider: provider.name, model: 'your-model' },
+});
+await agent.destroy(); // The host's provider remains open.
+// After every borrower finishes:
+await provider.close?.();
+```
 
-MIT
+`swapDefaultProvider(provider, model, { ownership: 'borrowed' })` makes the same explicit choice
+for a replacement; omitting the option keeps the owned default. Borrowing changes who closes the
+client and does not promise concurrent-use safety. A `Session` accepts the singular
+`providerOwnership: 'borrowed'` option, including through the Roundtable session adapter.

package/dist/browser/bounded-output-BdWv9SX3.js

@@ -0,0 +1,2 @@
+var e=class extends Error{context;constructor(e,t){super(e),this.context=t,this.name=this.constructor.name,Object.setPrototypeOf(this,new.target.prototype)}},t=class extends e{code=`CONFIGURATION_ERROR`;category=`user`;recoverable=!1;constructor(e,t){super(`Configuration Error: ${e}`,t)}},n=class extends e{field;code=`VALIDATION_ERROR`;category=`user`;recoverable=!1;constructor(e,t,n){super(`Validation Error: ${e}`,n),this.field=t}},r=class extends e{issues;attempts;code=`STRUCTURED_OUTPUT_ERROR`;category=`provider`;recoverable=!0;constructor(e,t,n,r){super(`Structured Output Error: ${e}`,r),this.issues=t,this.attempts=n}},i=class extends e{provider;originalError;code=`PROVIDER_ERROR`;category=`provider`;recoverable=!0;status;type;constructor(e,t,n,r,i){super(`Provider Error (${t}): ${e}`,r),this.provider=t,this.originalError=n,i?.status!==void 0&&(this.status=i.status),i?.type!==void 0&&(this.type=i.type)}},a=class extends e{provider;code=`AUTHENTICATION_ERROR`;category=`user`;recoverable=!1;constructor(e,t,n){super(`Authentication Error: ${e}`,n),this.provider=t}},o=class extends e{retryAfter;provider;code=`RATE_LIMIT_ERROR`;category=`provider`;recoverable=!0;constructor(e,t,n,r){super(`Rate Limit Error: ${e}`,r),this.retryAfter=t,this.provider=n}},s=class extends e{originalError;provider;code=`NETWORK_ERROR`;category=`system`;recoverable=!0;constructor(e,t,n,r){super(`Network Error: ${e}`,n),this.originalError=t,this.provider=r}},c=class extends e{toolName;originalError;code=`TOOL_EXECUTION_ERROR`;category=`system`;recoverable=!1;constructor(e,t,n,r){super(`Tool Execution Error (${t}): ${e}`,r),this.toolName=t,this.originalError=n}},l=class extends e{toolName;callCount;maxSameToolInputs;code=`SAME_TOOL_INPUT_LOOP`;category=`system`;recoverable=!0;constructor(e,t,n,r){super(`Tool "${e}" was called with identical input ${t} times, past the maxSameToolInputs limit of ${n} — stopping the turn to break the loop`,r),this.toolName=e,this.callCount=t,this.maxSameToolInputs=n}},u=class extends e{round;code=`EMPTY_COMPLETION`;category=`provider`;recoverable=!0;constructor(e,t){super(`Round ${e} ended with no tool call and no text response, and allowToolOnlyCompletion prevented the follow-up call that would otherwise recover it`,t),this.round=e}},d=class extends e{model;provider;availableModels;code=`MODEL_NOT_AVAILABLE`;category=`user`;recoverable=!1;constructor(e,t,n,r){let i=e===void 0?`No model available for provider "${t}"`:`Model "${e}" is not available for provider "${t}"`,a=r?.originalMessage;super(typeof a==`string`&&a.length>0?`${i}: ${a}`:i,r),this.model=e,this.provider=t,this.availableModels=n}},f=class extends e{code=`CIRCUIT_BREAKER_OPEN`;category=`system`;recoverable=!0;constructor(e=`Circuit breaker is open`,t){super(e,t)}},p=class extends e{pluginName;code=`PLUGIN_ERROR`;category=`system`;recoverable=!1;constructor(e,t,n){super(`Plugin Error (${t}): ${e}`,n),this.pluginName=t}},m=class extends e{code=`STORAGE_ERROR`;category=`system`;recoverable=!0;constructor(e,t){super(`Storage Error: ${e}`,t)}},h=class extends e{code=`CACHE_INTEGRITY_ERROR`;category=`system`;recoverable=!1;constructor(e,t){super(`Cache Integrity Error: ${e}`,t)}},g=class extends e{executable;code=`UNSUPPORTED_SHELL`;category=`user`;recoverable=!1;constructor(e){super(`Unsupported shell executable: ${e}`,{executable:e}),this.executable=e}};function _(e){return e===`darwin`?'Host OS: macOS (POSIX, BSD userland). Use BSD-flavored utilities: `sed -i ""` needs an empty backup arg, `date`/`grep`/`stat` flags differ from GNU. Prefer portable POSIX flags; avoid Linux/GNU-only options.':e===`linux`?"Host OS: Linux (POSIX, usually GNU coreutils, but distro/user setup varies). Prefer portable POSIX flags; do not assume a specific distro, and probe with `command -v` before relying on a non-standard tool.":`Host OS: ${e}; active shell family: POSIX sh/bash. Write portable POSIX syntax and avoid host-specific flags.`}function v(e,t){let n=x(e)===`bash`?`bash`:`sh`;return{command:e,kind:n,platform:t,commandArgs:e=>[`-c`,e],interactiveArgs:[],label:`${n} on ${t}`,syntaxHint:_(t)}}function y(e,t){return{command:e,kind:`powershell`,platform:t,commandArgs:e=>[`-NoProfile`,`-Command`,e],interactiveArgs:[`-NoProfile`],label:`PowerShell on ${t}`,syntaxHint:`Host OS: ${t}; active shell family: PowerShell. Write PowerShell syntax (not bash): e.g. \`Get-ChildItem\` not \`ls -la\`, \`\$env:VAR\` not \`\$VAR\`.`}}function b(e,t){return{command:e,kind:`cmd`,platform:t,commandArgs:e=>[`/d`,`/s`,`/c`,e],interactiveArgs:[],label:`cmd.exe on ${t}`,syntaxHint:`Host OS: ${t}; active shell family: Windows cmd.exe. Write cmd.exe syntax.`}}function x(e){return(e.split(/[\\/]/).at(-1)?.toLowerCase()??``).replace(/\.exe$/i,``)}function S(e,t){switch(x(e)){case`sh`:case`bash`:return v(e,t);case`powershell`:case`pwsh`:return y(e,t);case`cmd`:return b(e,t);default:throw new g(e)}}function C(e){let t=e?.trim();return t===void 0||t.length===0?void 0:t}function w(e={}){let t=e.env??process.env,n=e.platform??process.platform,r=C(e.executable);return r===void 0?n===`win32`?y(`powershell.exe`,n):v(C(t.SHELL)??`/bin/sh`,n):S(r,n)}const T=/^(?!0{32}$)[0-9a-f]{32}$/,E=/^(?!0{16}$)[0-9a-f]{16}$/;function D(e){return e.replaceAll(`-`,``).slice(0,16)}const O=D;function k(e){return E.test(e)}function A(e,t){if(!(!T.test(e)||!E.test(t)))return`00-${e}-${t}-01`}function j(e,t){if(e.allowedOrigins.length===0)return;let n=A(e.traceId,D(t));if(n!==void 0)return{traceparent:n,allowedOrigins:[...e.allowedOrigins]}}function M(e,t){return j(e,t)}function N(e,t,n){if(t?.subprocessClasses?.includes(e)!==!0)return;let r=A(t.traceId,n);return r===void 0?void 0:{TRACEPARENT:r}}function P(e,t,n={}){if(t===void 0||n.TRACEPARENT!==void 0)return{...e,...n};let{TRACESTATE:r,...i}=e;return{...i,...t,...n}}function F(e,t){if(e===void 0||t===void 0)return{};let n;try{n=new URL(e).origin}catch{return{}}return n===`null`||!t.allowedOrigins.includes(n)?{}:{traceparent:t.traceparent}}const I=e=>`\n…[output truncated: ${e} byte(s) dropped]`;function L(e){let t=e.retain??`head`,n=e.truncationMarker??I,r=Math.max(0,Math.floor(e.maxBytes)),i=new TextEncoder,a=[],o=0,s=0,c=e=>{let t=r-o;if(t<=0)return;let n=e.byteLength<=t?e:e.subarray(0,t);a.push(n),o+=n.byteLength},l=e=>{let t=e.byteLength<=r?e:e.subarray(e.byteLength-r);for(a.push(t),o+=t.byteLength;o>r&&a.length>0;){let e=a[0],t=o-r;e.byteLength<=t?(a.shift(),o-=e.byteLength):(a[0]=e.subarray(t),o-=t)}};return{append(e){let n=typeof e==`string`?i.encode(e):e;s+=n.byteLength,t===`head`?c(n):l(n)},get retainedBytes(){return o},get totalBytes(){return s},get droppedBytes(){return s-o},get truncated(){return s>o},toString(){let e=new Uint8Array(o),r=0;for(let t of a)e.set(t,r),r+=t.byteLength;a=a.length>1?[e]:a;let i=new TextDecoder().decode(e);if(s<=o)return i;let c=n(s-o);return t===`head`?`${i}${c}`:`${c.replace(/^\n/,``)}\n${i}`}}}export{o as C,c as D,r as E,n as O,i as S,m as T,t as _,O as a,s as b,M as c,g as d,w as f,f as g,h,j as i,N as l,a as m,A as n,D as o,e as p,k as r,P as s,L as t,F as u,u as v,l as w,p as x,d as y};
+//# sourceMappingURL=bounded-output-BdWv9SX3.js.map

package/dist/browser/bounded-output-BdWv9SX3.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-output-BdWv9SX3.js","names":[],"sources":["../../src/utils/errors.ts","../../src/utils/platform-shell.ts","../../src/utils/trace-context.ts","../../src/utils/bounded-output.ts"],"sourcesContent":["/**\n * Reusable type definitions for error utilities\n */\n\n/**\n * Error context data type\n * Used for storing contextual information in error instances\n */\nexport type TErrorContextData = Record<\n  string,\n  string | number | boolean | Date | Error | string[] | undefined\n>;\n\n/**\n * Error external input type\n * Used for handling external errors from unknown sources\n */\nexport type TErrorExternalInput =\n  Error | string | Record<string, string | number | boolean> | null | undefined;\n\n/**\n * Base error class for all ConversationAgent errors\n */\nexport abstract class AgentRuntimeError extends Error {\n  abstract readonly code: string;\n  abstract readonly category: 'user' | 'system' | 'provider';\n  abstract readonly recoverable: boolean;\n\n  constructor(\n    message: string,\n    public readonly context?: TErrorContextData,\n  ) {\n    super(message);\n    this.name = this.constructor.name;\n\n    // Ensure proper prototype chain for instanceof checks\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/**\n * Configuration related errors\n */\nexport class ConfigurationError extends AgentRuntimeError {\n  readonly code = 'CONFIGURATION_ERROR';\n  readonly category = 'user' as const;\n  readonly recoverable = false;\n\n  constructor(message: string, context?: TErrorContextData) {\n    super(`Configuration Error: ${message}`, context);\n  }\n}\n\n/**\n * Input validation errors\n */\nexport class ValidationError extends AgentRuntimeError {\n  readonly code = 'VALIDATION_ERROR';\n  readonly category = 'user' as const;\n  readonly recoverable = false;\n\n  constructor(\n    message: string,\n    public readonly field?: string,\n    context?: TErrorContextData,\n  ) {\n    super(`Validation Error: ${message}`, context);\n  }\n}\n\n/**\n * Structured output validation exhausted its retry budget (CORE-015).\n *\n * Thrown by `run(input, { output })` when the model's final response still fails\n * schema validation after the configured number of retries. `issues` holds the\n * validation messages from the last attempt; `attempts` is the total number of\n * provider turns spent (initial + retries).\n */\nexport class StructuredOutputError extends AgentRuntimeError {\n  readonly code = 'STRUCTURED_OUTPUT_ERROR';\n  readonly category = 'provider' as const;\n  readonly recoverable = true;\n\n  constructor(\n    message: string,\n    public readonly issues: string[],\n    public readonly attempts: number,\n    context?: TErrorContextData,\n  ) {\n    super(`Structured Output Error: ${message}`, context);\n  }\n}\n\n/** What the vendor said about a failed call, as far as it said anything. */\nexport interface IProviderFailureDetails {\n  /** The HTTP status of the failed response; absent for a failure with no response (e.g. an SSE error event). */\n  status?: number;\n  /** The vendor's own error type, e.g. Anthropic's `overloaded_error`. */\n  type?: string;\n}\n\n/**\n * Provider related errors\n */\nexport class ProviderError extends AgentRuntimeError {\n  readonly code = 'PROVIDER_ERROR';\n  readonly category = 'provider' as const;\n  readonly recoverable = true;\n  readonly status?: number;\n  readonly type?: string;\n\n  constructor(\n    message: string,\n    public readonly provider: string,\n    public readonly originalError?: Error,\n    context?: TErrorContextData,\n    details?: IProviderFailureDetails,\n  ) {\n    super(`Provider Error (${provider}): ${message}`, context);\n    if (details?.status !== undefined) this.status = details.status;\n    if (details?.type !== undefined) this.type = details.type;\n  }\n}\n\n/**\n * Authentication errors\n */\nexport class AuthenticationError extends AgentRuntimeError {\n  readonly code = 'AUTHENTICATION_ERROR';\n  readonly category = 'user' as const;\n  readonly recoverable = false;\n\n  constructor(\n    message: string,\n    public readonly provider?: string,\n    context?: TErrorContextData,\n  ) {\n    super(`Authentication Error: ${message}`, context);\n  }\n}\n\n/**\n * Rate limit errors\n */\nexport class RateLimitError extends AgentRuntimeError {\n  readonly code = 'RATE_LIMIT_ERROR';\n  readonly category = 'provider' as const;\n  readonly recoverable = true;\n\n  constructor(\n    message: string,\n    public readonly retryAfter?: number,\n    public readonly provider?: string,\n    context?: TErrorContextData,\n  ) {\n    super(`Rate Limit Error: ${message}`, context);\n  }\n}\n\n/**\n * Network/connectivity errors\n */\nexport class NetworkError extends AgentRuntimeError {\n  readonly code = 'NETWORK_ERROR';\n  readonly category = 'system' as const;\n  readonly recoverable = true;\n\n  constructor(\n    message: string,\n    public readonly originalError?: Error,\n    context?: TErrorContextData,\n    /** `undefined` for a network failure with no provider context (e.g. a generic timeout). */\n    public readonly provider?: string,\n  ) {\n    super(`Network Error: ${message}`, context);\n  }\n}\n\n/**\n * Tool execution errors\n */\nexport class ToolExecutionError extends AgentRuntimeError {\n  readonly code = 'TOOL_EXECUTION_ERROR';\n  readonly category = 'system' as const;\n  readonly recoverable = false;\n\n  constructor(\n    message: string,\n    public readonly toolName: string,\n    public readonly originalError?: Error,\n    context?: TErrorContextData,\n  ) {\n    super(`Tool Execution Error (${toolName}): ${message}`, context);\n  }\n}\n\n/**\n * The same-tool-input loop guard tripped — CORE-035.\n *\n * A tool was invoked with byte-identical serialized inputs more times than `maxSameToolInputs`\n * allows, so the turn stopped rather than looping. This is the AGENT giving up, not the user\n * cancelling: the SPEC used to promise an `AbortError` here, which `isAbortFailure` resolves as\n * `success: true, interrupted: true` — reporting a run that produced no answer as a success.\n *\n * Named rather than a bare `Error` for the reason the SPEC was reaching for by naming a type at all:\n * a caller must be able to tell \"the agent looped\" from \"the network died\". `AgentRuntimeError` carries\n * `code`/`category`/`recoverable` out through CORE-027's failure path intact.\n *\n * `recoverable` is TRUE: the loop is a property of this turn's prompt and tool set, not of the\n * system, and a caller that varies either can reasonably try again.\n */\nexport class SameToolInputLoopError extends AgentRuntimeError {\n  readonly code = 'SAME_TOOL_INPUT_LOOP';\n  readonly category = 'system' as const;\n  readonly recoverable = true;\n\n  constructor(\n    public readonly toolName: string,\n    public readonly callCount: number,\n    public readonly maxSameToolInputs: number,\n    context?: TErrorContextData,\n  ) {\n    super(\n      `Tool \"${toolName}\" was called with identical input ${callCount} times, past the ` +\n        `maxSameToolInputs limit of ${maxSameToolInputs} — stopping the turn to break the loop`,\n      context,\n    );\n  }\n}\n\n/**\n * A turn ended with neither a tool result nor a final text response while `allowToolOnlyCompletion`\n * was set.\n *\n * `allowToolOnlyCompletion` only WIDENS what counts as a valid finish (a tool call alone, with no\n * final text after it); it never narrows the ordinary case. Without the flag, a round that produces\n * neither is recovered by one more provider call asking for a summary (`forceSummaryCall`). Setting\n * the flag is what turns that rescue off — a decision agent wants exactly one provider call, never a\n * follow-up — so a round that produces neither has nothing left to recover it. That is a genuinely\n * unanswered turn, not the internal `[STRICT-POLICY]` result-shape violation an actually malformed\n * execution result trips; a caller must be able to catch this by type instead of parsing that message.\n *\n * `recoverable` is TRUE: like `SameToolInputLoopError`, this is a property of this turn's prompt and\n * model response, not of the system, and a caller that varies either can reasonably try again.\n */\nexport class EmptyCompletionError extends AgentRuntimeError {\n  readonly code = 'EMPTY_COMPLETION';\n  readonly category = 'provider' as const;\n  readonly recoverable = true;\n\n  constructor(\n    public readonly round: number,\n    context?: TErrorContextData,\n  ) {\n    super(\n      `Round ${round} ended with no tool call and no text response, and allowToolOnlyCompletion ` +\n        'prevented the follow-up call that would otherwise recover it',\n      context,\n    );\n  }\n}\n\n/**\n * Model not available errors\n */\nexport class ModelNotAvailableError extends AgentRuntimeError {\n  readonly code = 'MODEL_NOT_AVAILABLE';\n  readonly category = 'user' as const;\n  readonly recoverable = false;\n\n  constructor(\n    /** `undefined` when the failure names no model — a provider adapter classifying a raw HTTP\n     *  response by status alone does not always know which model the vendor meant. */\n    public readonly model: string | undefined,\n    public readonly provider: string,\n    public readonly availableModels?: string[],\n    /**\n     * `context.originalMessage`, when given, is the vendor's own text (already scrubbed of any\n     * credential by the caller) — folded into `message` so a \"Details\" disclosure built from\n     * `message` alone still shows the real cause instead of just this class's fixed sentence.\n     */\n    context?: TErrorContextData,\n  ) {\n    const base =\n      model !== undefined\n        ? `Model \"${model}\" is not available for provider \"${provider}\"`\n        : `No model available for provider \"${provider}\"`;\n    const detail = context?.['originalMessage'];\n    super(typeof detail === 'string' && detail.length > 0 ? `${base}: ${detail}` : base, context);\n  }\n}\n\n/**\n * Circuit breaker open error\n */\nexport class CircuitBreakerOpenError extends AgentRuntimeError {\n  readonly code = 'CIRCUIT_BREAKER_OPEN';\n  readonly category = 'system' as const;\n  readonly recoverable = true;\n\n  constructor(message: string = 'Circuit breaker is open', context?: TErrorContextData) {\n    super(message, context);\n  }\n}\n\n/**\n * Plugin errors\n */\nexport class PluginError extends AgentRuntimeError {\n  readonly code = 'PLUGIN_ERROR';\n  readonly category = 'system' as const;\n  readonly recoverable = false;\n\n  constructor(\n    message: string,\n    public readonly pluginName: string,\n    context?: TErrorContextData,\n  ) {\n    super(`Plugin Error (${pluginName}): ${message}`, context);\n  }\n}\n\n/**\n * Storage related errors\n */\nexport class StorageError extends AgentRuntimeError {\n  readonly code = 'STORAGE_ERROR';\n  readonly category = 'system' as const;\n  readonly recoverable = true;\n\n  constructor(message: string, context?: TErrorContextData) {\n    super(`Storage Error: ${message}`, context);\n  }\n}\n\n/**\n * Cache integrity validation errors\n */\nexport class CacheIntegrityError extends AgentRuntimeError {\n  readonly code = 'CACHE_INTEGRITY_ERROR';\n  readonly category = 'system' as const;\n  readonly recoverable = false;\n\n  constructor(message: string, context?: TErrorContextData) {\n    super(`Cache Integrity Error: ${message}`, context);\n  }\n}\n","/**\n * TERM-008: cross-platform shell resolution (SSOT).\n *\n * Single source of truth for \"which shell do we spawn, and how\", shared by every shell-running site.\n * Resolution is a pure function of one request so every branch is testable without the host shell.\n */\n\nimport { AgentRuntimeError } from './errors.js';\n\n/** Shell family — drives non-interactive arg shape, quoting, and LLM syntax guidance. */\nexport type TShellKind = 'bash' | 'sh' | 'powershell' | 'cmd';\n\n/** The active shell resolved for a platform, plus the metadata callers need to drive and describe it. */\nexport interface IPlatformShell {\n  /** Executable to spawn (e.g. `/bin/sh`, `powershell.exe`, or `$SHELL`). */\n  readonly command: string;\n  /** Shell family. */\n  readonly kind: TShellKind;\n  /** Node platform this was resolved for (`process.platform`). */\n  readonly platform: NodeJS.Platform;\n  /** Args to run a single command string non-interactively. */\n  commandArgs(command: string): string[];\n  /** Args for an interactive shell session (drop-to-shell). */\n  readonly interactiveArgs: string[];\n  /** Human label for the active shell, for tool/UI descriptions (e.g. `PowerShell (Windows)`). */\n  readonly label: string;\n  /** One-line syntax guidance for an LLM authoring commands. */\n  readonly syntaxHint: string;\n}\n\n/** Pure inputs for resolving one executable together with its command argument family. */\nexport interface IPlatformShellResolutionRequest {\n  /** Request-local executable. A non-blank value has the highest precedence. */\n  readonly executable?: string;\n  /** Environment used for SHELL resolution. */\n  readonly env?: NodeJS.ProcessEnv;\n  /** Actual host platform retained in the resolved metadata. */\n  readonly platform?: NodeJS.Platform;\n}\n\n/** An explicit executable whose basename has no supported command argument family. */\nexport class UnsupportedShellError extends AgentRuntimeError {\n  readonly code = 'UNSUPPORTED_SHELL';\n  readonly category = 'user' as const;\n  readonly recoverable = false;\n\n  constructor(public readonly executable: string) {\n    super(`Unsupported shell executable: ${executable}`, { executable });\n  }\n}\n\n/**\n * OS-family syntax guidance for the LLM. macOS and Linux are both POSIX but ship different userlands\n * (macOS = BSD coreutils, most Linux = GNU coreutils), so flags like `sed -i`, `date`, and `grep`\n * differ — naming the OS lets the model avoid Linux-only invocations on macOS and vice versa.\n */\nfunction posixSyntaxHint(platform: NodeJS.Platform): string {\n  if (platform === 'darwin') {\n    return 'Host OS: macOS (POSIX, BSD userland). Use BSD-flavored utilities: `sed -i \"\"` needs an empty backup arg, `date`/`grep`/`stat` flags differ from GNU. Prefer portable POSIX flags; avoid Linux/GNU-only options.';\n  }\n  if (platform === 'linux') {\n    return 'Host OS: Linux (POSIX, usually GNU coreutils, but distro/user setup varies). Prefer portable POSIX flags; do not assume a specific distro, and probe with `command -v` before relying on a non-standard tool.';\n  }\n  return `Host OS: ${platform}; active shell family: POSIX sh/bash. Write portable POSIX syntax and avoid host-specific flags.`;\n}\n\nfunction posixShell(command: string, platform: NodeJS.Platform): IPlatformShell {\n  const isBash = shellBasename(command) === 'bash';\n  const kind: TShellKind = isBash ? 'bash' : 'sh';\n  return {\n    command,\n    kind,\n    platform,\n    commandArgs: (cmd: string): string[] => ['-c', cmd],\n    interactiveArgs: [],\n    label: `${kind} on ${platform}`,\n    syntaxHint: posixSyntaxHint(platform),\n  };\n}\n\nfunction powerShell(command: string, platform: NodeJS.Platform): IPlatformShell {\n  return {\n    command,\n    kind: 'powershell',\n    platform,\n    commandArgs: (cmd: string): string[] => ['-NoProfile', '-Command', cmd],\n    interactiveArgs: ['-NoProfile'],\n    label: `PowerShell on ${platform}`,\n    syntaxHint:\n      `Host OS: ${platform}; active shell family: PowerShell. Write PowerShell syntax (not bash): e.g. ` +\n      '`Get-ChildItem` not `ls -la`, `$env:VAR` not `$VAR`.',\n  };\n}\n\nfunction cmdShell(command: string, platform: NodeJS.Platform): IPlatformShell {\n  return {\n    command,\n    kind: 'cmd',\n    platform,\n    commandArgs: (cmd: string): string[] => ['/d', '/s', '/c', cmd],\n    interactiveArgs: [],\n    label: `cmd.exe on ${platform}`,\n    syntaxHint: `Host OS: ${platform}; active shell family: Windows cmd.exe. Write cmd.exe syntax.`,\n  };\n}\n\nfunction shellBasename(command: string): string {\n  const basename = command.split(/[\\\\/]/).at(-1)?.toLowerCase() ?? '';\n  return basename.replace(/\\.exe$/i, '');\n}\n\nfunction explicitShell(command: string, platform: NodeJS.Platform): IPlatformShell {\n  switch (shellBasename(command)) {\n    case 'sh':\n    case 'bash':\n      return posixShell(command, platform);\n    case 'powershell':\n    case 'pwsh':\n      return powerShell(command, platform);\n    case 'cmd':\n      return cmdShell(command, platform);\n    default:\n      throw new UnsupportedShellError(command);\n  }\n}\n\nfunction nonBlank(value: string | undefined): string | undefined {\n  const trimmed = value?.trim();\n  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;\n}\n\n/**\n * Resolve the shell to spawn for the current (or a given) platform.\n *\n * - request `executable` wins when non-blank.\n * - **win32:** PowerShell.\n * - **posix:** `$SHELL` if set, else `/bin/sh`.\n */\nexport function resolvePlatformShell(\n  request: IPlatformShellResolutionRequest = {},\n): IPlatformShell {\n  const env = request.env ?? process.env;\n  const platform = request.platform ?? process.platform;\n  const requestedExecutable = nonBlank(request.executable);\n  if (requestedExecutable !== undefined) return explicitShell(requestedExecutable, platform);\n\n  if (platform === 'win32') return powerShell('powershell.exe', platform);\n\n  return posixShell(nonBlank(env['SHELL']) ?? '/bin/sh', platform);\n}\n","/**\n * Pure helpers for trusted W3C trace context. Strings and the WHATWG `URL` only, so they are the\n * same in the browser build and in every adapter that attaches the header.\n */\nimport type {\n  IOutboundTraceContext,\n  IRunTraceContext,\n  ISubprocessTraceEnv,\n  TSubprocessTraceClass,\n} from '../interfaces/trace-context';\n\nconst TRACE_ID = /^(?!0{32}$)[0-9a-f]{32}$/;\nconst SPAN_ID = /^(?!0{16}$)[0-9a-f]{16}$/;\n\n/**\n * The span ID an operation is exported under, derived from the ID core mints before it runs (a\n * provider call's call ID, a tool body's body ID). One derivation for both the exporter and the\n * outgoing header, so the span a recipient sees as its parent is the span the trace contains.\n */\nexport function spanIdFromMintedId(mintedId: string): string {\n  return mintedId.replaceAll('-', '').slice(0, 16);\n}\n\n/** The provider-call name for {@link spanIdFromMintedId}, kept so existing callers keep working. */\nexport const providerCallSpanId: (callId: string) => string = spanIdFromMintedId;\n\n/** Whether `spanId` is a well-formed minted span ID: 16 lowercase hex characters, not all zero. */\nexport function isMintedSpanId(spanId: string): boolean {\n  return SPAN_ID.test(spanId);\n}\n\n/** A sampled version-00 `traceparent`, or undefined when either identifier is invalid. */\nexport function buildTraceparent(traceId: string, spanId: string): string | undefined {\n  if (!TRACE_ID.test(traceId) || !SPAN_ID.test(spanId)) return undefined;\n  return `00-${traceId}-${spanId}-01`;\n}\n\n/** The outbound context for one invoked call, or undefined when there is nothing valid to send. */\nexport function outboundTraceContextFor(\n  traceContext: IRunTraceContext,\n  callId: string,\n): IOutboundTraceContext | undefined {\n  if (traceContext.allowedOrigins.length === 0) return undefined;\n  const traceparent = buildTraceparent(traceContext.traceId, spanIdFromMintedId(callId));\n  if (traceparent === undefined) return undefined;\n  return { traceparent, allowedOrigins: [...traceContext.allowedOrigins] };\n}\n\n/**\n * The outbound context for one tool body, keyed by the body ID core minted for it — never the\n * vendor's tool call ID, which is neither unique nor hex.\n */\nexport function toolTraceContextFor(\n  traceContext: IRunTraceContext,\n  toolBodyId: string,\n): IOutboundTraceContext | undefined {\n  return outboundTraceContextFor(traceContext, toolBodyId);\n}\n\n/**\n * The environment one child process of `subprocessClass` receives, naming `spanId` as its parent,\n * or undefined when the host did not enable that class. Independent of the origin allowlist.\n */\nexport function traceEnvFor(\n  subprocessClass: TSubprocessTraceClass,\n  traceContext: IRunTraceContext | undefined,\n  spanId: string,\n): ISubprocessTraceEnv | undefined {\n  if (traceContext?.subprocessClasses?.includes(subprocessClass) !== true) return undefined;\n  const traceparent = buildTraceparent(traceContext.traceId, spanId);\n  return traceparent === undefined ? undefined : { TRACEPARENT: traceparent };\n}\n\n/**\n * A fresh child environment: `base`, then ConversationAgent's trace, then `overrides`. When ConversationAgent's value\n * applies, the ambient `TRACESTATE` is dropped because it belongs to a different parent. When\n * `overrides` sets its own `TRACEPARENT`, ConversationAgent's value does not apply and `base` passes unchanged.\n * `base` itself is never modified.\n */\nexport function subprocessTraceEnvironment(\n  base: Readonly<Record<string, string | undefined>>,\n  traceEnv: ISubprocessTraceEnv | undefined,\n  overrides: Readonly<Record<string, string>> = {},\n): Record<string, string | undefined> {\n  if (traceEnv === undefined || overrides['TRACEPARENT'] !== undefined) return { ...base, ...overrides };\n  const { TRACESTATE: _ambientState, ...rest } = base;\n  return { ...rest, ...traceEnv, ...overrides };\n}\n\n/**\n * The headers to add to a request whose effective base URL is `baseUrl`: `traceparent` when its\n * origin exactly equals a listed origin, nothing otherwise. Scheme, host and port must all match;\n * a subdomain or a different port is a different origin.\n */\nexport function traceHeadersFor(\n  baseUrl: string | undefined,\n  traceContext: IOutboundTraceContext | undefined,\n): Readonly<Record<string, string>> {\n  if (baseUrl === undefined || traceContext === undefined) return {};\n  let origin: string;\n  try {\n    origin = new URL(baseUrl).origin;\n  } catch {\n    return {};\n  }\n  if (origin === 'null' || !traceContext.allowedOrigins.includes(origin)) return {};\n  return { traceparent: traceContext.traceparent };\n}\n","/**\n * ARCH-056 (#2161): the bounded output-retention contract for child-process execution.\n *\n * Every path that reads a child's stdout/stderr must bound memory WHILE the output is being read —\n * not cap a summary afterwards while retaining the whole log. Before this existed, `shell-tool`\n * could buffer for ten minutes, the hook `CommandExecutor` repeated the pattern, and a subagent\n * runner had rediscovered a 4 KiB tail on its own. This module names the policy once:\n *\n * - **Budget.** `maxBytes` is the most that is ever RETAINED; bytes beyond it are dropped as they\n *   arrive, so memory is bounded by the budget, not by the child's lifetime.\n * - **Retention.** `head` keeps the first `maxBytes` (a tool result: what the command said first);\n *   `tail` keeps the last `maxBytes` (a diagnostic: how it ended).\n * - **Truncation is visible.** `truncated`, `droppedBytes` and a marker in `toString()` say that\n *   output was dropped and how much — never a silently shorter string.\n * - **No spill.** This contract never writes to disk; a caller that needs the whole stream owns a\n *   log file (background tasks do), and this buffer is what stays in memory beside it.\n * - **Termination is not here.** Exceeding the budget drops bytes; whether the child is killed is\n *   the caller's policy (CORE-023 owns process-tree termination).\n *\n * Chunks are `Uint8Array` (a Node `Buffer` is one), and decoding happens once at `toString()`, so a\n * multi-byte character split across a chunk boundary is never decoded twice.\n */\n\nexport type TOutputRetention = 'head' | 'tail';\n\nexport interface IBoundedOutputOptions {\n  /** Most bytes ever retained. */\n  readonly maxBytes: number;\n  /** Which end to keep once over budget. Default `head`. */\n  readonly retain?: TOutputRetention;\n  /** Marker appended (head) or prepended (tail) to `toString()` when bytes were dropped. */\n  readonly truncationMarker?: (droppedBytes: number) => string;\n}\n\nexport interface IBoundedOutput {\n  append(chunk: Uint8Array | string): void;\n  /** Bytes currently retained (≤ `maxBytes`). */\n  readonly retainedBytes: number;\n  /** Bytes the child produced in total, retained or not. */\n  readonly totalBytes: number;\n  readonly droppedBytes: number;\n  readonly truncated: boolean;\n  /** The retained output, decoded as UTF-8, with the truncation marker when bytes were dropped. */\n  toString(): string;\n}\n\nconst DEFAULT_MARKER = (dropped: number): string =>\n  `\\n…[output truncated: ${dropped} byte(s) dropped]`;\n\nexport function createBoundedOutput(options: IBoundedOutputOptions): IBoundedOutput {\n  const retain = options.retain ?? 'head';\n  const marker = options.truncationMarker ?? DEFAULT_MARKER;\n  const maxBytes = Math.max(0, Math.floor(options.maxBytes));\n  const encoder = new TextEncoder();\n  let chunks: Uint8Array[] = [];\n  let retained = 0;\n  let total = 0;\n\n  const appendHead = (bytes: Uint8Array): void => {\n    const room = maxBytes - retained;\n    if (room <= 0) return;\n    const kept = bytes.byteLength <= room ? bytes : bytes.subarray(0, room);\n    chunks.push(kept);\n    retained += kept.byteLength;\n  };\n\n  const appendTail = (bytes: Uint8Array): void => {\n    const kept = bytes.byteLength <= maxBytes ? bytes : bytes.subarray(bytes.byteLength - maxBytes);\n    chunks.push(kept);\n    retained += kept.byteLength;\n    // Drop whole leading chunks first, then trim the oldest survivor — O(chunks), no re-copying.\n    while (retained > maxBytes && chunks.length > 0) {\n      const oldest = chunks[0] as Uint8Array;\n      const excess = retained - maxBytes;\n      if (oldest.byteLength <= excess) {\n        chunks.shift();\n        retained -= oldest.byteLength;\n      } else {\n        chunks[0] = oldest.subarray(excess);\n        retained -= excess;\n      }\n    }\n  };\n\n  return {\n    append(chunk) {\n      const bytes = typeof chunk === 'string' ? encoder.encode(chunk) : chunk;\n      total += bytes.byteLength;\n      if (retain === 'head') appendHead(bytes);\n      else appendTail(bytes);\n    },\n    get retainedBytes() {\n      return retained;\n    },\n    get totalBytes() {\n      return total;\n    },\n    get droppedBytes() {\n      return total - retained;\n    },\n    get truncated() {\n      return total > retained;\n    },\n    toString() {\n      const joined = new Uint8Array(retained);\n      let offset = 0;\n      for (const chunk of chunks) {\n        joined.set(chunk, offset);\n        offset += chunk.byteLength;\n      }\n      chunks = chunks.length > 1 ? [joined] : chunks;\n      const text = new TextDecoder().decode(joined);\n      if (total <= retained) return text;\n      const note = marker(total - retained);\n      return retain === 'head' ? `${text}${note}` : `${note.replace(/^\\n/, '')}\\n${text}`;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/browser/command-executor-DIXaSMrr.js

@@ -0,0 +1,2 @@
+import{f as e,s as t,t as n}from"./bounded-output-BdWv9SX3.js";import{spawn as r}from"node:child_process";const i=1e6;function a(e,t){let r=n({maxBytes:i}),a=n({maxBytes:i,retain:`tail`});return e.stdout?.on(`data`,e=>r.append(e)),e.stderr?.on(`data`,e=>a.append(e)),e.stdin?.on(`error`,()=>{}),e.stdin?.write(t),e.stdin?.end(),{stdoutOutput:r,stderrOutput:a}}function o(e,t,n,r){if(e===0)return{outcome:`allow`,source:`command`,stdout:n};if(e===2)return{outcome:`deny`,source:`command`,reason:r.trim()||`Blocked by hook`};let i=r.trim()?`: ${r.trim()}`:``;return{outcome:`error`,source:`command`,kind:`nonzero-exit`,reason:e===null?`Hook terminated by signal ${t??`unknown`}${i}`:`Hook exited ${e}${i}`}}var s=class{shellExecutable;type=`command`;constructor(e){this.shellExecutable=e}execute(n,i,s){let c=n.timeout??600,l=c*1e3,u=JSON.stringify(i);return new Promise(d=>{let f=!1,p=e({executable:this.shellExecutable}),m=r(p.command,p.commandArgs(n.command),{cwd:i.cwd,env:t(process.env,s,i.env)}),{stdoutOutput:h,stderrOutput:g}=a(m,u),_=setTimeout(()=>{f||(f=!0,m.kill(`SIGTERM`),d({outcome:`error`,source:`command`,kind:`timeout`,reason:`Hook timed out after ${c}s`}))},l);m.on(`close`,(e,t)=>{f||(f=!0,clearTimeout(_),d(o(e,t,h.toString(),g.toString())))}),m.on(`error`,e=>{f||(f=!0,clearTimeout(_),d({outcome:`error`,source:`command`,kind:`spawn-failure`,reason:e.message}))})})}};export{s as CommandExecutor};
+//# sourceMappingURL=command-executor-DIXaSMrr.js.map