@archships/dim-agent-sdk 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# @archships/dim-agent-sdk
+
+An agent-first TypeScript SDK with canonical multi-provider contracts, session/tool loop, hook-based plugins, runtime gateways, and builtin local coding tools.
+
+## Install
+
+Recommended runtime: Node.js `>=18`.
+
+```bash
+npm install @archships/dim-agent-sdk
+```
+
+## Quick start
+
+```ts
+import {
+  createAgent,
+  createModel,
+  createOpenAIAdapter,
+} from '@archships/dim-agent-sdk'
+
+const model = createModel(createOpenAIAdapter({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseUrl: 'https://api.openai.com/v1',
+  defaultModel: 'gpt-4o-mini',
+}))
+
+const agent = createAgent({
+  model,
+  cwd: process.cwd(),
+})
+
+const session = await agent.createSession({
+  systemPrompt: 'You are a coding agent. Use tools when needed.',
+})
+
+const message = await session.send('Create hello.txt in the current directory and write hello world into it.')
+console.log(message.content)
+```
+
+## Manual
+
+- Developer manual: [docs/manual/README.md](../../docs/manual/README.md)
+- Chinese guide: [docs/manual/zh/README.md](../../docs/manual/zh/README.md)
+- English guide: [docs/manual/en/README.md](../../docs/manual/en/README.md)
+
+## Included core capabilities
+
+- Canonical content / message / tool / model / state contracts
+- `createAgent()` -> `Agent` -> `Session`
+- Session stream events: `text_delta`, optional `thinking_delta`, `tool_call`, `tool_result`, `done`
+- Provider adapters: `openai-compatible`, `openai-responses`, `anthropic`, `gemini`
+- Builtin tools: `read`, `write`, `edit`, `exec`
+- Hook-first plugin integration
+- Runtime gateways: file system, git, exec, network, model
+- In-memory and file-based persistence
+
+## Provider notes
+
+- `createOpenAIAdapter()`: OpenAI-compatible Chat Completions style; no official reasoning channel mapping
+- `createOpenAIResponsesAdapter()`: official OpenAI Responses API; maps reasoning summaries into `thinking_delta`
+- `createAnthropicAdapter()`: maps Claude thinking blocks into `thinking_delta`
+- `createGeminiAdapter()`: maps Gemini thought parts into `thinking_delta`
+
+## Demo
+
+A repository demo is available at `packages/dim-agent-sdk/demo/openai-tools.ts`.
+It uses `createOpenAIAdapter()` against the OpenAI-compatible Chat API and exercises the builtin tools through one session.
+It is intended for local repository development rather than package consumers.

package/dist/agent-core/Agent.d.ts

@@ -0,0 +1,29 @@
+import type { SessionSnapshot } from '../contracts';
+import type { StateStore } from '../persistence/store';
+import { PluginHost } from '../plugin-host/PluginHost';
+import type { DimPlugin } from '@archships/dim-plugin-api';
+import type { AgentServices, PermissionSpec } from '../services';
+import { ToolRegistry } from '../tools';
+import { Session } from './Session';
+import type { AgentOptions, CreateSessionOptions } from './agent-types';
+export declare class Agent {
+    readonly id: string;
+    readonly pluginHost: PluginHost;
+    readonly services: AgentServices;
+    readonly tools: ToolRegistry;
+    readonly permissions?: PermissionSpec;
+    private readonly options;
+    private readonly messageFactory;
+    private readonly contextManager;
+    private readonly tracker;
+    private readonly permissionGateway;
+    constructor(options: AgentOptions);
+    createSession(options?: CreateSessionOptions): Promise<Session>;
+    restoreSession(sessionId: string): Promise<Session | null>;
+    sessionFromSnapshot(snapshot: SessionSnapshot): Session;
+}
+export interface CreateAgentOptions extends AgentOptions {
+    plugins?: DimPlugin[];
+    stateStore?: StateStore;
+}
+export declare function createAgent(options: CreateAgentOptions): Agent;

package/dist/agent-core/LoopRunner.d.ts

@@ -0,0 +1,30 @@
+import type { AssistantMessage, MessageContentInput, SessionStreamEvent } from '../contracts';
+import type { ContextManager } from '../context';
+import type { PluginHost } from '../plugin-host/PluginHost';
+import type { MessageFactory } from './MessageFactory';
+import type { ModelTurnCollector } from './ModelTurnCollector';
+import type { RuntimeSessionState } from './session-state';
+import type { TerminationPolicy } from './TerminationPolicy';
+import type { ToolExecutor } from './ToolExecutor';
+export interface LoopRunnerDependencies {
+    messageFactory: MessageFactory;
+    turnCollector: ModelTurnCollector;
+    toolExecutor: ToolExecutor;
+    terminationPolicy: TerminationPolicy;
+    contextManager: ContextManager;
+    pluginHost?: PluginHost;
+}
+export interface LoopRunnerRunOptions {
+    signal?: AbortSignal;
+    onDone?: (message: AssistantMessage) => Promise<void> | void;
+}
+export declare class LoopRunner {
+    private readonly messageFactory;
+    private readonly turnCollector;
+    private readonly toolExecutor;
+    private readonly terminationPolicy;
+    private readonly contextManager;
+    private readonly pluginHost?;
+    constructor(dependencies: LoopRunnerDependencies);
+    run(state: RuntimeSessionState, input: MessageContentInput, options?: LoopRunnerRunOptions): AsyncGenerator<SessionStreamEvent, AssistantMessage, void>;
+}

package/dist/agent-core/MessageFactory.d.ts

@@ -0,0 +1,20 @@
+import type { AssistantMessage, CallToolResult, MessageContentInput, ModelStopReason, SystemMessage, ToolCall, ToolMessage, UserMessage } from '../contracts';
+export interface CreateAssistantMessageInput {
+    text: string;
+    thinking?: string;
+    toolCalls: ToolCall[];
+    stopReason: ModelStopReason;
+    metadata?: Record<string, unknown>;
+}
+export interface MessageFactory {
+    createSystemMessage(input: MessageContentInput): SystemMessage;
+    createUserMessage(input: MessageContentInput): UserMessage;
+    createAssistantMessage(input: CreateAssistantMessageInput): AssistantMessage;
+    createToolMessage(toolCall: ToolCall, result: CallToolResult): ToolMessage;
+}
+export declare class DefaultMessageFactory implements MessageFactory {
+    createSystemMessage(input: MessageContentInput): SystemMessage;
+    createUserMessage(input: MessageContentInput): UserMessage;
+    createAssistantMessage(input: CreateAssistantMessageInput): AssistantMessage;
+    createToolMessage(toolCall: ToolCall, result: CallToolResult): ToolMessage;
+}

package/dist/agent-core/ModelTurnCollector.d.ts

@@ -0,0 +1,22 @@
+import type { ModelStopReason, ModelStreamEvent, SessionStreamEvent, ToolCall, Usage } from '../contracts';
+export interface CollectModelTurnOptions {
+    sessionId: string;
+    requestId: string;
+    events: AsyncIterable<ModelStreamEvent>;
+    onEvent?: (event: ModelStreamEvent) => Promise<void> | void;
+}
+export interface ModelTurnResult {
+    requestId: string;
+    text: string;
+    thinking?: string;
+    toolCalls: ToolCall[];
+    stopReason: ModelStopReason;
+    usage?: Usage;
+    assistantMetadata?: Record<string, unknown>;
+}
+export interface ModelTurnCollector {
+    collect(options: CollectModelTurnOptions): AsyncGenerator<SessionStreamEvent, ModelTurnResult, void>;
+}
+export declare class DefaultModelTurnCollector implements ModelTurnCollector {
+    collect(options: CollectModelTurnOptions): AsyncGenerator<SessionStreamEvent, ModelTurnResult, void>;
+}

package/dist/agent-core/Session.d.ts

@@ -0,0 +1,48 @@
+import type { AssistantMessage, Message, MessageContentInput, ModelClient, ModelRef, SessionSnapshot, SessionStreamEvent, Usage } from '../contracts';
+import type { ContextManager } from '../context';
+import type { StateStore } from '../persistence/store';
+import type { PluginHost } from '../plugin-host/PluginHost';
+import type { AgentServices } from '../services';
+import type { ToolRegistry } from '../tools/ToolRegistry';
+export interface SessionOptions {
+    id?: string;
+    model: ModelClient;
+    modelRef?: ModelRef;
+    tools?: ToolRegistry;
+    stateStore?: StateStore;
+    maxIterations?: number;
+    cwd?: string;
+    metadata?: Record<string, unknown>;
+    reasoning?: Record<string, unknown>;
+    messages?: Message[];
+    usage?: Usage;
+    createdAt?: number;
+    updatedAt?: number;
+    pluginHost?: PluginHost;
+    contextManager: ContextManager;
+    services: AgentServices;
+}
+export declare class Session {
+    readonly id: string;
+    readonly createdAt: number;
+    private readonly stateStore?;
+    private readonly state;
+    private readonly pluginHost?;
+    private readonly contextManager;
+    private readonly services;
+    constructor(options: SessionOptions);
+    get messages(): Message[];
+    get usage(): Usage;
+    get updatedAt(): number;
+    getCwd(): string | undefined;
+    setCwd(cwd: string): void;
+    save(): Promise<void>;
+    toSnapshot(): SessionSnapshot;
+    send(input: MessageContentInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<AssistantMessage>;
+    stream(input: MessageContentInput, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<SessionStreamEvent, AssistantMessage, void>;
+    private createLoopRunner;
+}

package/dist/agent-core/TerminationPolicy.d.ts

@@ -0,0 +1,14 @@
+import type { SessionErrorPayload, ToolCall } from '../contracts';
+export type TerminationDecision = {
+    type: 'done';
+} | {
+    type: 'continue';
+};
+export interface TerminationPolicy {
+    afterAssistantTurn(toolCalls: ToolCall[]): TerminationDecision;
+    onMaxIterationsExceeded(maxIterations: number, requestId?: string): SessionErrorPayload;
+}
+export declare class DefaultTerminationPolicy implements TerminationPolicy {
+    afterAssistantTurn(toolCalls: ToolCall[]): TerminationDecision;
+    onMaxIterationsExceeded(maxIterations: number, requestId?: string): SessionErrorPayload;
+}

package/dist/agent-core/ToolExecutor.d.ts

@@ -0,0 +1,27 @@
+import type { CallToolResult, ToolCall } from '../contracts';
+import type { PluginHost } from '../plugin-host/PluginHost';
+import type { AgentServices } from '../services';
+import type { ToolRegistry } from '../tools/ToolRegistry';
+export interface ToolExecutorExecuteOptions {
+    signal?: AbortSignal;
+    cwd?: string;
+}
+export interface ToolExecutor {
+    execute(toolCall: ToolCall, options?: ToolExecutorExecuteOptions): Promise<CallToolResult>;
+}
+export interface ToolExecutorOptions {
+    sessionId: string;
+    tools?: ToolRegistry;
+    metadata?: Record<string, unknown>;
+    services: AgentServices;
+    pluginHost?: PluginHost;
+}
+export declare class DefaultToolExecutor implements ToolExecutor {
+    private readonly sessionId;
+    private readonly tools?;
+    private readonly metadata?;
+    private readonly services;
+    private readonly pluginHost?;
+    constructor(options: ToolExecutorOptions);
+    execute(toolCall: ToolCall, options?: ToolExecutorExecuteOptions): Promise<CallToolResult>;
+}

package/dist/agent-core/agent-types.d.ts

@@ -0,0 +1,26 @@
+import type { Message, MessageContentInput, ModelClient, Tool } from '../contracts';
+import type { ContextManager } from '../context';
+import type { StateStore } from '../persistence/store';
+import type { DimPlugin } from '@archships/dim-plugin-api';
+import type { PermissionSpec } from '../services';
+import type { ToolRegistry } from '../tools/ToolRegistry';
+export interface AgentOptions {
+    model: ModelClient;
+    tools?: ToolRegistry | Tool[];
+    plugins?: DimPlugin[];
+    stateStore?: StateStore;
+    maxIterations?: number;
+    cwd?: string;
+    metadata?: Record<string, unknown>;
+    permissions?: PermissionSpec;
+    contextManager?: ContextManager;
+    includeBuiltinTools?: boolean;
+    reasoning?: Record<string, unknown>;
+}
+export interface CreateSessionOptions {
+    sessionId?: string;
+    cwd?: string;
+    metadata?: Record<string, unknown>;
+    messages?: Message[];
+    systemPrompt?: MessageContentInput;
+}

package/dist/agent-core/createModel.d.ts

@@ -0,0 +1,2 @@
+import type { ConfiguredModelAdapter, ModelClient } from '../contracts/model';
+export declare function createModel(adapter: ConfiguredModelAdapter): ModelClient;

package/dist/agent-core/errors.d.ts

@@ -0,0 +1,5 @@
+import type { SessionErrorPayload } from '../contracts/common';
+export declare class SessionExecutionError extends Error {
+    readonly payload: SessionErrorPayload;
+    constructor(payload: SessionErrorPayload);
+}

package/dist/agent-core/index.d.ts

@@ -0,0 +1,13 @@
+export { Agent, createAgent } from './Agent';
+export { createModel } from './createModel';
+export { Session } from './Session';
+export { SessionExecutionError } from './errors';
+export type { AgentOptions, CreateSessionOptions } from './agent-types';
+export type { CreateAgentOptions } from './Agent';
+export type { LoopRunnerDependencies, LoopRunnerRunOptions } from './LoopRunner';
+export type { CreateAssistantMessageInput, MessageFactory } from './MessageFactory';
+export type { CollectModelTurnOptions, ModelTurnCollector, ModelTurnResult } from './ModelTurnCollector';
+export type { RuntimeSessionState } from './session-state';
+export type { SessionOptions } from './Session';
+export type { TerminationDecision, TerminationPolicy } from './TerminationPolicy';
+export type { ToolExecutor, ToolExecutorExecuteOptions, ToolExecutorOptions } from './ToolExecutor';

package/dist/agent-core/session-state.d.ts

@@ -0,0 +1,17 @@
+import type { Message, ModelClient, ModelRef, Usage } from '../contracts';
+import type { ToolRegistry } from '../tools/ToolRegistry';
+export interface RuntimeSessionState {
+    id: string;
+    model: ModelClient;
+    modelRef: ModelRef;
+    tools?: ToolRegistry;
+    maxIterations: number;
+    cwd?: string;
+    metadata?: Record<string, unknown>;
+    reasoning?: Record<string, unknown>;
+    messages: Message[];
+    usage: Usage;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare function touchRuntimeSessionState(state: RuntimeSessionState): void;

package/dist/agent-core/tool-call.d.ts

@@ -0,0 +1,9 @@
+import type { ToolCall } from '../contracts/tool';
+export interface ToolCallDraft {
+    callId: string;
+    toolName: string;
+    argsText: string;
+}
+export declare function startToolCall(callId: string, toolName: string): ToolCallDraft;
+export declare function appendToolCallArgsDelta(draft: ToolCallDraft, delta: string): ToolCallDraft;
+export declare function finalizeToolCall(draft: ToolCallDraft): ToolCall;

package/dist/context/AutoContextManager.d.ts

@@ -0,0 +1,21 @@
+import type { PluginHost } from '../plugin-host/PluginHost';
+import type { AgentServices } from '../services';
+import type { ContextItem, ContextManager, ContextResolveOptions } from './types';
+export interface AutoContextManagerOptions {
+    services: AgentServices;
+    pluginHost?: PluginHost;
+    maxItems?: number;
+    maxChars?: number;
+}
+export declare class AutoContextManager implements ContextManager {
+    private readonly services;
+    private readonly pluginHost?;
+    private readonly maxItems;
+    private readonly maxChars;
+    constructor(options: AutoContextManagerOptions);
+    resolve(options: ContextResolveOptions): Promise<ContextItem[]>;
+    format(items: ContextItem[]): string[];
+    private resolveExplicitFiles;
+    private resolveRecentFiles;
+    private resolveGitState;
+}

package/dist/context/index.d.ts

@@ -0,0 +1,3 @@
+export { AutoContextManager } from './AutoContextManager';
+export type { AutoContextManagerOptions } from './AutoContextManager';
+export type { ContextItem, ContextManager, ContextResolveOptions } from './types';

package/dist/context/types.d.ts

@@ -0,0 +1,19 @@
+import type { Message, MessageContentInput } from '../contracts';
+export interface ContextItem {
+    id: string;
+    type: 'cwd' | 'file' | 'git_status' | 'git_diff' | 'text';
+    title: string;
+    content: string;
+    priority: number;
+    source: string;
+}
+export interface ContextResolveOptions {
+    sessionId: string;
+    input: MessageContentInput;
+    messages: Message[];
+    cwd?: string;
+}
+export interface ContextManager {
+    resolve(options: ContextResolveOptions): Promise<ContextItem[]>;
+    format(items: ContextItem[]): string[];
+}

package/dist/contracts/common.d.ts

@@ -0,0 +1,19 @@
+export interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface ModelErrorPayload {
+    code: string;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+    details?: Record<string, unknown>;
+}
+export interface SessionErrorPayload extends ModelErrorPayload {
+    requestId?: string;
+}
+export type JsonValue = string | number | boolean | null | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}

package/dist/contracts/content-normalize.d.ts

@@ -0,0 +1,6 @@
+import type { ContentBlock, ImageContent, MessageContentInput, NormalizedContent, TextContent } from './content';
+export declare function isTextContent(value: unknown): value is TextContent;
+export declare function isImageContent(value: unknown): value is ImageContent;
+export declare function isContentBlock(value: unknown): value is ContentBlock;
+export declare function normalizeContent(input: MessageContentInput): NormalizedContent;
+export declare function contentToText(content: NormalizedContent): string;

package/dist/contracts/content.d.ts

@@ -0,0 +1,16 @@
+export interface TextContent {
+    type: 'text';
+    text: string;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export interface ImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+    annotations?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+export type ContentBlock = TextContent | ImageContent;
+export type MessageContentInput = string | ContentBlock | ContentBlock[];
+export type NormalizedContent = ContentBlock[];

package/dist/contracts/event.d.ts

@@ -0,0 +1,30 @@
+import type { SessionErrorPayload, Usage } from './common';
+import type { AssistantMessage } from './message';
+import type { CallToolResult, ToolCall } from './tool';
+export type SessionStreamEvent = {
+    type: 'text_delta';
+    sessionId: string;
+    delta: string;
+} | {
+    type: 'thinking_delta';
+    sessionId: string;
+    delta: string;
+} | {
+    type: 'tool_call';
+    sessionId: string;
+    toolCall: ToolCall;
+} | {
+    type: 'tool_result';
+    sessionId: string;
+    toolCallId: string;
+    result: CallToolResult;
+} | {
+    type: 'done';
+    sessionId: string;
+    message: AssistantMessage;
+    usage?: Usage;
+} | {
+    type: 'error';
+    sessionId: string;
+    error: SessionErrorPayload;
+};

package/dist/contracts/index.d.ts

@@ -0,0 +1,9 @@
+export * from './common';
+export * from './content';
+export * from './content-normalize';
+export * from './event';
+export * from './message';
+export * from './model';
+export * from './state';
+export * from './tool';
+export * from './tool-normalize';

package/dist/contracts/message.d.ts

@@ -0,0 +1,32 @@
+import type { NormalizedContent } from './content';
+import type { ModelStopReason } from './model';
+import type { ToolCall } from './tool';
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface BaseMessage {
+    id: string;
+    role: MessageRole;
+    content: NormalizedContent;
+    createdAt: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SystemMessage extends BaseMessage {
+    role: 'system';
+}
+export interface UserMessage extends BaseMessage {
+    role: 'user';
+    name?: string;
+}
+export interface AssistantMessage extends BaseMessage {
+    role: 'assistant';
+    thinking?: string;
+    toolCalls?: ToolCall[];
+    stopReason?: ModelStopReason;
+}
+export interface ToolMessage extends BaseMessage {
+    role: 'tool';
+    toolCallId: string;
+    toolName: string;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;

package/dist/contracts/model.d.ts

@@ -0,0 +1,73 @@
+import type { ModelErrorPayload, Usage } from './common';
+import type { Message } from './message';
+import type { ToolDefinition } from './tool';
+export interface ModelRef {
+    provider: string;
+    modelId: string;
+}
+export type ModelStopReason = 'final' | 'tool_call' | 'length' | 'error' | 'cancelled';
+export interface ModelRequest {
+    requestId?: string;
+    model: ModelRef;
+    messages: Message[];
+    tools?: ToolDefinition[];
+    maxOutputTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stop?: string[];
+    reasoning?: Record<string, unknown>;
+    metadata?: Record<string, string | number | boolean | null>;
+    signal?: AbortSignal;
+}
+export type ModelStreamEvent = {
+    type: 'response_start';
+    requestId: string;
+    model: ModelRef;
+} | {
+    type: 'text_delta';
+    requestId: string;
+    delta: string;
+} | {
+    type: 'thinking_delta';
+    requestId: string;
+    delta: string;
+} | {
+    type: 'tool_call_start';
+    requestId: string;
+    callId: string;
+    toolName: string;
+} | {
+    type: 'tool_call_args_delta';
+    requestId: string;
+    callId: string;
+    delta: string;
+} | {
+    type: 'tool_call_end';
+    requestId: string;
+    callId: string;
+} | {
+    type: 'response_end';
+    requestId: string;
+    stopReason: ModelStopReason;
+    usage?: Usage;
+    assistantMetadata?: Record<string, unknown>;
+} | {
+    type: 'error';
+    requestId: string;
+    error: ModelErrorPayload;
+    terminal?: boolean;
+};
+export interface ModelAdapter {
+    readonly provider: string;
+    stream(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
+}
+export interface ConfiguredModelAdapter extends ModelAdapter {
+    readonly defaultModel: ModelRef;
+}
+export interface ModelClient {
+    readonly adapter: ModelAdapter;
+    readonly model: ModelRef;
+    stream(request: Omit<ModelRequest, 'model'> & {
+        model?: ModelRef;
+    }): AsyncIterable<ModelStreamEvent>;
+}

package/dist/contracts/state.d.ts

@@ -0,0 +1,14 @@
+import type { Usage } from './common';
+import type { Message } from './message';
+import type { ModelRef } from './model';
+export interface SessionSnapshot {
+    schemaVersion: 1;
+    sessionId: string;
+    model?: ModelRef;
+    cwd?: string;
+    messages: Message[];
+    usage?: Usage;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}

package/dist/contracts/tool-normalize.d.ts

@@ -0,0 +1,3 @@
+import type { CallToolResult, ToolInputSchema } from './tool';
+export declare function normalizeToolSchema(schema: ToolInputSchema): ToolInputSchema;
+export declare function normalizeToolResult(result: CallToolResult): CallToolResult;

package/dist/contracts/tool.d.ts

@@ -0,0 +1,40 @@
+import type { JsonObject } from './common';
+import type { NormalizedContent } from './content';
+import type { AgentServices } from '../services/types';
+export type JsonSchema = Record<string, unknown>;
+export interface ToolInputSchema extends JsonSchema {
+    type: 'object';
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    rawArgumentsText?: string;
+}
+export interface CallToolResult {
+    content: NormalizedContent;
+    structuredContent?: JsonObject;
+    isError?: boolean;
+}
+export interface ToolExecutionContext {
+    sessionId: string;
+    cwd?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    services?: AgentServices;
+}
+export interface Tool {
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<CallToolResult>;
+}