@archships/dim-agent-sdk 0.0.1 → 0.0.2

package/dist/dim-plugin-api/src/index.d.ts

@@ -0,0 +1,602 @@
+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;
+}
+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 NormalizedContent = ContentBlock[];
+export type MessageContentInput = string | ContentBlock | ContentBlock[];
+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 ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    command: string;
+    cwd: string | null;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: string | null;
+    timedOut?: boolean;
+}
+export interface GlobOptions {
+    cwd?: string;
+    limit?: number;
+}
+export interface GrepOptions extends GlobOptions {
+    pattern?: string;
+}
+export interface GrepMatch {
+    path: string;
+    lineNumber: number;
+    line: string;
+}
+export interface FileSystemGateway {
+    readText(path: string, options?: {
+        cwd?: string;
+    }): Promise<string>;
+    writeText(path: string, content: string, options?: {
+        cwd?: string;
+    }): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+    editText(path: string, options: {
+        oldText: string;
+        newText: string;
+        replaceAll?: boolean;
+        cwd?: string;
+    }): Promise<{
+        path: string;
+        replacements: number;
+    }>;
+    exists(path: string, options?: {
+        cwd?: string;
+    }): Promise<boolean>;
+    glob(pattern: string, options?: GlobOptions): Promise<string[]>;
+    grep(query: string, options?: GrepOptions): Promise<GrepMatch[]>;
+}
+export interface ExecGateway {
+    execute(command: string, options?: ExecOptions): Promise<ExecResult>;
+}
+export interface GitGateway {
+    status(options?: {
+        cwd?: string;
+    }): Promise<string | null>;
+    diff(options?: {
+        cwd?: string;
+    }): Promise<string | null>;
+}
+export interface NetworkGateway {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export interface ModelRef {
+    provider: string;
+    modelId: string;
+}
+export type ModelStopReason = 'final' | 'tool_call' | 'length' | 'error' | 'cancelled';
+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;
+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 ModelGateway {
+    stream(request: ModelRequest): AsyncIterable<ModelStreamEvent>;
+}
+export type CompactionTriggerReason = 'manual' | 'threshold';
+export interface CompactionCheckpoint {
+    id: string;
+    cursor: number;
+    systemSegments: string[];
+    summary?: string;
+    reason: CompactionTriggerReason;
+    createdAt: number;
+    metadata?: Record<string, unknown>;
+}
+export interface CompactionState {
+    cursor: number;
+    systemSegments: string[];
+    checkpoints: CompactionCheckpoint[];
+}
+export interface CompactionUpdate {
+    cursor: number;
+    systemSegments?: string[];
+    summary?: string;
+    reason?: CompactionTriggerReason;
+    metadata?: Record<string, unknown>;
+}
+export interface CompactionServiceUpdate extends CompactionUpdate {
+    sessionId: string;
+}
+export interface CompactionService {
+    getState(sessionId: string): Promise<CompactionState>;
+    apply(update: CompactionServiceUpdate): Promise<CompactionState>;
+    clear(sessionId: string): Promise<CompactionState>;
+}
+export interface PluginSessionStateEntry {
+    version: number;
+    data: JsonObject;
+    updatedAt: number;
+}
+export interface PluginStateService {
+    get(sessionId: string): Promise<PluginSessionStateEntry | null>;
+    replace(sessionId: string, entry: PluginSessionStateEntry): Promise<PluginSessionStateEntry>;
+    clear(sessionId: string): Promise<void>;
+}
+export interface PluginToolEvent {
+    pluginId?: string;
+    event: string;
+    data?: JsonObject;
+}
+export interface PluginServices {
+    fileSystem: FileSystemGateway;
+    exec: ExecGateway;
+    git: GitGateway;
+    network: NetworkGateway;
+    model: ModelGateway;
+    compaction: CompactionService;
+    pluginState: PluginStateService;
+}
+export interface ToolExecutionContext {
+    sessionId: string;
+    cwd?: string;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    services?: PluginServices;
+    emitEvent?(event: PluginToolEvent): Promise<void> | void;
+}
+export interface Tool {
+    readonly definition: ToolDefinition;
+    execute(args: Record<string, unknown>, context: ToolExecutionContext): Promise<CallToolResult>;
+}
+export interface SessionSnapshot {
+    schemaVersion: 1;
+    sessionId: string;
+    model?: ModelRef;
+    cwd?: string;
+    messages: Message[];
+    usage?: Usage;
+    compaction?: CompactionState;
+    pluginState?: Record<string, PluginSessionStateEntry>;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}
+export interface SessionStatus {
+    sessionId: string;
+    model: ModelRef;
+    cwd?: string;
+    usage: Usage;
+    compaction: CompactionState;
+    messageCount: number;
+    createdAt: number;
+    updatedAt: number;
+    metadata?: Record<string, unknown>;
+}
+export type FileSystemPermission = boolean | 'read' | 'write' | 'full';
+export interface PermissionSpec {
+    fs?: FileSystemPermission;
+    git?: boolean;
+    network?: boolean;
+    process?: boolean;
+    model?: boolean;
+    mcp?: boolean;
+}
+export interface ContextItem {
+    id: string;
+    type: 'cwd' | 'file' | 'git_status' | 'git_diff' | 'text';
+    title: string;
+    content: string;
+    priority: number;
+    source: string;
+}
+export interface PluginManifest {
+    id: string;
+    version: string;
+    apiVersion: 1;
+    permissions: PermissionSpec;
+    configSchema?: Record<string, unknown>;
+    priority?: number;
+    capabilities?: string[];
+}
+export interface PluginRuntimeContext {
+    agentId: string;
+    cwd?: string;
+    sessionId?: string;
+    requestId?: string;
+    iteration?: number;
+    services: PluginServices;
+    status?: SessionStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface NotificationPayload {
+    id?: string;
+    type: string;
+    source: string;
+    message: string;
+    level?: 'info' | 'warning' | 'error';
+    title?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ApprovalRequest {
+    id?: string;
+    kind: 'tool_execution';
+    toolCall: ToolCall;
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+export type ApprovalDecision = {
+    type: 'approved';
+} | {
+    type: 'denied';
+    reason?: string;
+};
+export interface RunStartPayload {
+    sessionId: string;
+    input: MessageContentInput;
+}
+export interface TurnStartPayload {
+    requestId: string;
+    iteration: number;
+    messages: Message[];
+}
+export interface ContextResolvePayload {
+    contextItems: ContextItem[];
+    input: MessageContentInput;
+    messages: Message[];
+}
+export interface PromptResolvePayload {
+    promptSegments: string[];
+    contextItems: ContextItem[];
+    messages: Message[];
+}
+export interface ToolsetResolvePayload {
+    tools: ToolDefinition[];
+}
+export interface ModelRequestPayload {
+    request: ModelRequest;
+}
+export interface ModelEventPayload {
+    event: ModelStreamEvent;
+}
+export interface AssistantMessagePayload {
+    message: AssistantMessage;
+}
+export interface ToolBeforeExecutePayload {
+    toolCall: ToolCall;
+}
+export interface ToolAfterExecutePayload {
+    toolCall: ToolCall;
+    result: CallToolResult;
+}
+export interface RunLoopDecision {
+    type: 'done' | 'continue';
+}
+export interface RunStopPayload {
+    assistantMessage: AssistantMessage;
+    toolCalls: ToolCall[];
+    stopReason: ModelStopReason;
+    decision: RunLoopDecision;
+    additionalContext?: string[];
+    finalMessage?: AssistantMessage;
+}
+export interface NotificationHookPayload {
+    notification: NotificationPayload;
+}
+export interface ContextCompactBeforePayload {
+    sessionId: string;
+    messages: Message[];
+    cursor: number;
+    systemSegments: string[];
+    contextItems?: ContextItem[];
+    estimatedInputTokens: number;
+    thresholdTokens: number;
+    maxInputTokens: number;
+    trigger: CompactionTriggerReason;
+}
+/**
+ * Experimental hook payload.
+ * The runtime does not emit this hook until subagent execution is implemented.
+ */
+export interface SubagentStopPayload {
+    subagentId: string;
+    input?: MessageContentInput;
+    result?: AssistantMessage;
+    metadata?: Record<string, unknown>;
+}
+export interface SnapshotEncodePayload {
+    snapshot: SessionSnapshot;
+}
+export interface RunEndPayload {
+    message: AssistantMessage;
+    usage?: Usage;
+}
+export interface SessionErrorHookPayload {
+    error: SessionErrorPayload;
+}
+export interface HookPayloadMap {
+    'run.start': RunStartPayload;
+    'turn.start': TurnStartPayload;
+    'context.resolve': ContextResolvePayload;
+    'prompt.resolve': PromptResolvePayload;
+    'toolset.resolve': ToolsetResolvePayload;
+    'model.request': ModelRequestPayload;
+    'model.event': ModelEventPayload;
+    'assistant.message': AssistantMessagePayload;
+    'tool.beforeExecute': ToolBeforeExecutePayload;
+    'tool.afterExecute': ToolAfterExecutePayload;
+    'notify.message': NotificationHookPayload;
+    'run.stop': RunStopPayload;
+    'context.compact.before': ContextCompactBeforePayload;
+    'subagent.stop': SubagentStopPayload;
+    'snapshot.encode': SnapshotEncodePayload;
+    'run.end': RunEndPayload;
+    'session.error': SessionErrorHookPayload;
+}
+/**
+ * Public hook names exposed to plugin authors.
+ * `subagent.stop` remains reserved until subagent execution is implemented.
+ */
+export type PublicHookName = 'run.start' | 'tool.beforeExecute' | 'tool.afterExecute' | 'notify.message' | 'run.stop' | 'run.end' | 'context.compact.before' | 'subagent.stop' | 'session.error';
+export type InternalHookName = 'turn.start' | 'context.resolve' | 'prompt.resolve' | 'toolset.resolve' | 'model.request' | 'model.event' | 'assistant.message' | 'snapshot.encode';
+export type HookName = keyof HookPayloadMap;
+export type HookMode = 'sync' | 'async';
+export interface HookMatcher {
+    toolName?: string | string[];
+    notificationType?: string | string[];
+    stopReason?: ModelStopReason | ModelStopReason[];
+    source?: string | string[];
+}
+export interface HookDescriptor<N extends HookName = HookName> {
+    name: N;
+    when?: HookMatcher;
+    mode?: HookMode;
+    timeoutMs?: number;
+    priority?: number;
+}
+export interface HookHandlerInput<T> {
+    payload: T;
+    context: PluginRuntimeContext;
+}
+export interface HookControlResult<T> {
+    type: 'continue' | 'replace' | 'stop';
+    payload: T;
+}
+export interface AskApprovalInput {
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+export type ToolBeforeExecuteControlResult = {
+    type: 'allow';
+} | {
+    type: 'deny';
+    reason?: string;
+    result?: CallToolResult;
+} | {
+    type: 'ask';
+    request?: AskApprovalInput;
+    toolCall?: ToolCall;
+} | {
+    type: 'replaceToolCall';
+    toolCall: ToolCall;
+} | {
+    type: 'provideResult';
+    result: CallToolResult;
+};
+export type NotificationControlResult = {
+    type: 'continue';
+} | {
+    type: 'replace';
+    notification: NotificationPayload;
+} | {
+    type: 'suppress';
+};
+export type RunStopControlResult = {
+    type: 'continue';
+} | {
+    type: 'finalize';
+    finalMessage?: AssistantMessage;
+    additionalContext?: string[];
+};
+export type HookSpecialControlResult<N extends HookName> = N extends 'tool.beforeExecute' ? ToolBeforeExecuteControlResult : N extends 'notify.message' ? NotificationControlResult : N extends 'run.stop' ? RunStopControlResult : never;
+export type HookMiddlewareResult<N extends HookName> = HookControlResult<HookPayloadMap[N]> | HookPayloadMap[N] | HookSpecialControlResult<N> | void;
+export type HookMiddleware<N extends HookName> = (input: HookHandlerInput<HookPayloadMap[N]>) => HookMiddlewareResult<N> | Promise<HookMiddlewareResult<N>>;
+export type HookObserver<N extends HookName> = (input: HookHandlerInput<HookPayloadMap[N]>) => void | Promise<void>;
+export type HookHandler<N extends HookName = HookName> = HookMiddleware<N> | HookObserver<N>;
+export interface HookRegistrationEntry<N extends HookName = HookName> {
+    descriptor: HookDescriptor<N>;
+    middleware?: HookMiddleware<N>[];
+    observers?: HookObserver<N>[];
+}
+export type AnyHookRegistrationEntry = {
+    [N in HookName]: HookRegistrationEntry<N>;
+}[HookName];
+export type HookRegistration = AnyHookRegistrationEntry[];
+export interface PluginContext {
+    cwd?: string;
+    manifest: PluginManifest;
+    services: PluginServices;
+}
+export interface PluginSessionControllerContext {
+    sessionId: string;
+    metadata?: Record<string, unknown>;
+    getStatus(): SessionStatus;
+    pluginState: PluginStateService;
+    save(): Promise<void>;
+    isRunning(): boolean;
+}
+export type PluginSessionControllerFactory = (context: PluginSessionControllerContext) => unknown;
+export interface ContextContributorInput {
+    sessionId: string;
+    input: MessageContentInput;
+    messages: Message[];
+    cwd?: string;
+}
+export type ContextContributor = (input: ContextContributorInput) => ContextItem[] | Promise<ContextItem[]>;
+export interface PromptContributorInput {
+    sessionId: string;
+    input: MessageContentInput;
+    messages: Message[];
+    contextItems: ContextItem[];
+    cwd?: string;
+}
+export type PromptContributor = (input: PromptContributorInput) => string | string[] | undefined | Promise<string | string[] | undefined>;
+export interface AgentMode {
+    name: string;
+    description?: string;
+}
+export interface PluginSetupResult {
+    hooks?: HookRegistration;
+    tools?: Tool[];
+    contextContributors?: ContextContributor[];
+    promptContributors?: PromptContributor[];
+    modes?: AgentMode[];
+    createSessionController?: PluginSessionControllerFactory;
+}
+export interface DimPlugin {
+    manifest: PluginManifest;
+    setup?(context: PluginContext): PluginSetupResult;
+}
+export declare function continueHook<T>(payload: T): HookControlResult<T>;
+export declare function replaceHook<T>(payload: T): HookControlResult<T>;
+export declare function stopHook<T>(payload: T): HookControlResult<T>;
+export declare function allowToolCall(): ToolBeforeExecuteControlResult;
+export declare function denyToolCall(reason?: string, result?: CallToolResult): ToolBeforeExecuteControlResult;
+export declare function askToolCall(request?: AskApprovalInput, toolCall?: ToolCall): ToolBeforeExecuteControlResult;
+export declare function replaceToolCall(toolCall: ToolCall): ToolBeforeExecuteControlResult;
+export declare function provideToolResult(result: CallToolResult): ToolBeforeExecuteControlResult;
+export declare function continueNotification(): NotificationControlResult;
+export declare function replaceNotification(notification: NotificationPayload): NotificationControlResult;
+export declare function suppressNotification(): NotificationControlResult;
+export declare function continueRun(): RunStopControlResult;
+export declare function finalizeRun(finalMessage?: AssistantMessage, additionalContext?: string[]): RunStopControlResult;