@archships/dim-agent-sdk 0.0.1 → 0.0.2

package/README.md

@@ -48,13 +48,63 @@ console.log(message.content)
 
 - Canonical content / message / tool / model / state contracts
 - `createAgent()` -> `Agent` -> `Session`
-- Session stream events: `text_delta`, optional `thinking_delta`, `tool_call`, `tool_result`, `done`
+- Session stream events: `text_delta`, optional `thinking_delta`, `tool_call`, `plugin_event`, `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
+- Namespaced plugin session state with snapshot restore support
 - In-memory and file-based persistence
 
+## Hook support
+
+Supported public hooks in the current runtime:
+
+- `run.start`
+- `tool.beforeExecute`
+- `tool.afterExecute`
+- `context.compact.before`
+- `notify.message`
+- `run.stop`
+- `run.end`
+- `session.error`
+
+Reserved / experimental hook names that are typed but not wired into the runtime yet:
+
+- `subagent.stop`
+
+Current failure policy:
+
+- Sync middleware is blocking and fail-fast
+- Observers are best-effort
+- `mode: 'async'` is observer-only
+- `timeoutMs` applies per hook handler
+
+## Official plugin packages
+
+| Package | Support level | Notes |
+| --- | --- | --- |
+| `@archships/dim-plugin-auto-compact` | supported | Official auto compaction plugin; requires `compaction.ownerPluginId: 'auto-compact'` |
+| `@archships/dim-plugin-grep-glob` | supported | Registers `grep` and `glob` filesystem tools |
+| `@archships/dim-plugin-mcp-client` | supported | Bridge-style MCP injection plugin for tools, context, and prompt segments |
+| `@archships/dim-plugin-skills` | supported | Prompt contributor wrapper for reusable instructions |
+| `@archships/dim-plugin-plan-mode` | supported | Controller-driven planning guardrail with reminder injection, read-only tool filtering, and `plan_exit` UI events |
+| `@archships/dim-plugin-memory` | stub | Placeholder package; not part of the current supported surface |
+| `@archships/dim-plugin-web` | stub | Placeholder package; not part of the current supported surface |
+| `@archships/dim-plugin-scheduler` | stub | Placeholder package; not part of the current supported surface |
+| `@archships/dim-plugin-deep-research` | stub | Placeholder package; not part of the current supported surface |
+
+## Compaction and state model
+
+- `session.messages` always keeps the full original history for UI and restore
+- Canonical request projection is controlled by SDK compaction state: `cursor`, `systemSegments`, `checkpoints`
+- `Session.getStatus()` returns the canonical read-only session status snapshot used by hook runtime context
+- `Session.getPlugin(pluginId)` returns a session-scoped plugin controller when the plugin exposes one
+- Plugins can persist their own namespaced session state through `pluginState`
+- If `compaction.ownerPluginId` is configured, only that plugin can write canonical compaction through plugin services
+- `Session.compact()` remains available as an app-level override
+- Hook handlers receive the same canonical status through `context.status`, without exposing full message history or other plugins' state
+
 ## Provider notes
 
 - `createOpenAIAdapter()`: OpenAI-compatible Chat Completions style; no official reasoning channel mapping
@@ -64,6 +114,67 @@ console.log(message.content)
 
 ## 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.
+- `packages/dim-agent-sdk/demo/compaction-scripted.ts`: scripted compaction runtime demo
+- `packages/dim-agent-sdk/demo/auto-compact-plugin.ts`: scripted official auto compact plugin demo
+- `packages/dim-agent-sdk/demo/plan-mode-plugin.ts`: scripted official plan mode plugin demo
+- `packages/dim-agent-sdk/demo/openai-tools.ts`: builtin tools smoke demo
+- `packages/dim-agent-sdk/demo/openai-hooks.ts`: provider-backed Hook v2 scenario runner
+
+`compaction-scripted.ts` does not require external model credentials and demonstrates manual compact required, request projection, restore, and the official auto compact plugin inside the lower-level compaction flow.
+
+`openai-tools.ts` and `openai-hooks.ts` use `createOpenAIAdapter()` against the OpenAI-compatible Chat API and are intended for local repository development rather than package consumers.
+
+Hook demo scenarios:
+
+- `lifecycle`
+- `approval-deny`
+- `synthetic-result`
+- `notification-control`
+- `stop-finalize`
+
+Run with the same environment variables used by the tools demo:
+
+```bash
+bun run demo:hooks
+```
+
+Run the scripted compaction demo locally:
+
+```bash
+bun run demo:compaction
+```
+
+Run the scripted auto compact plugin demo locally:
+
+```bash
+bun run demo:auto-compact
+```
+
+Run the scripted plan mode plugin demo locally:
+
+```bash
+bun run demo:plan-mode
+```
+
+Plan mode v2 notes:
+
+- `plan_exit` emits `plugin_event` instead of directly disabling plan mode
+- host applications can drive plan mode through `session.getPlugin('plan-mode')`
+- enable / disable / exit resolution changes affect the next run, not the current in-flight run
+
+## Testing
+
+Local repository verification is split into three layers:
+
+- `bun run test`: full local regression, including deterministic `test/e2e/*.e2e.test.ts`
+- `bun run test:e2e`: deterministic end-to-end workflows for `plan-mode`, code-agent tool loops, auto-compact restore, and approval / permission boundaries
+- `bun run test:plugins`: focused plugin contract and integration tests
+- `bun run test:smoke`: env-gated provider smoke in `test/smoke/*.smoke.ts`
+
+The provider smoke layer reuses:
+
+- `DIM_TEST_API_KEY`
+- `DIM_TEST_BASE_URL`
+- `DIM_TEST_MODEL_ID` (optional)
+
+Smoke tests assert stable invariants such as tool calls, `plugin_event`, notifications, and on-disk side effects. They intentionally avoid exact natural-language output matching.

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/Agent.d.ts

@@ -1,9 +1,10 @@
+import type { DimPlugin } from '@archships/dim-plugin-api';
 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 type { ApprovalHandler } from './approvals';
 import { Session } from './Session';
 import type { AgentOptions, CreateSessionOptions } from './agent-types';
 export declare class Agent {
@@ -17,6 +18,10 @@ export declare class Agent {
     private readonly contextManager;
     private readonly tracker;
     private readonly permissionGateway;
+    private readonly approvalManager;
+    private readonly notificationBus;
+    private readonly compactionService;
+    private readonly pluginStateService;
     constructor(options: AgentOptions);
     createSession(options?: CreateSessionOptions): Promise<Session>;
     restoreSession(sessionId: string): Promise<Session | null>;
@@ -25,5 +30,6 @@ export declare class Agent {
 export interface CreateAgentOptions extends AgentOptions {
     plugins?: DimPlugin[];
     stateStore?: StateStore;
+    approvalHandler?: ApprovalHandler;
 }
 export declare function createAgent(options: CreateAgentOptions): Agent;

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/LoopRunner.d.ts

@@ -3,6 +3,7 @@ import type { ContextManager } from '../context';
 import type { PluginHost } from '../plugin-host/PluginHost';
 import type { MessageFactory } from './MessageFactory';
 import type { ModelTurnCollector } from './ModelTurnCollector';
+import type { NotificationBus } from './notifications';
 import type { RuntimeSessionState } from './session-state';
 import type { TerminationPolicy } from './TerminationPolicy';
 import type { ToolExecutor } from './ToolExecutor';
@@ -13,6 +14,7 @@ export interface LoopRunnerDependencies {
     terminationPolicy: TerminationPolicy;
     contextManager: ContextManager;
     pluginHost?: PluginHost;
+    notificationBus: NotificationBus;
 }
 export interface LoopRunnerRunOptions {
     signal?: AbortSignal;
@@ -25,6 +27,10 @@ export declare class LoopRunner {
     private readonly terminationPolicy;
     private readonly contextManager;
     private readonly pluginHost?;
+    private readonly notificationBus;
     constructor(dependencies: LoopRunnerDependencies);
     run(state: RuntimeSessionState, input: MessageContentInput, options?: LoopRunnerRunOptions): AsyncGenerator<SessionStreamEvent, AssistantMessage, void>;
+    private resolveRequestMessages;
+    private buildProjectedRequestMessages;
+    private createHookContext;
 }

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/Session.d.ts

@@ -1,9 +1,13 @@
-import type { AssistantMessage, Message, MessageContentInput, ModelClient, ModelRef, SessionSnapshot, SessionStreamEvent, Usage } from '../contracts';
+import type { AssistantMessage, CompactionOptions, CompactionState, CompactionUpdate, Message, MessageContentInput, ModelClient, ModelRef, PluginSessionStateEntry, SessionStatus, 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';
+import type { ApprovalManager } from './approvals';
+import { DefaultCompactionService } from './compaction';
+import { DefaultPluginStateService } from './plugin-state';
+import type { NotificationBus } from './notifications';
 export interface SessionOptions {
     id?: string;
     model: ModelClient;
@@ -16,11 +20,18 @@ export interface SessionOptions {
     reasoning?: Record<string, unknown>;
     messages?: Message[];
     usage?: Usage;
+    compaction?: CompactionState;
+    pluginState?: Record<string, PluginSessionStateEntry>;
+    compactionOptions?: CompactionOptions;
     createdAt?: number;
     updatedAt?: number;
     pluginHost?: PluginHost;
     contextManager: ContextManager;
     services: AgentServices;
+    approvalManager: ApprovalManager;
+    notificationBus: NotificationBus;
+    compactionService: DefaultCompactionService;
+    pluginStateService: DefaultPluginStateService;
 }
 export declare class Session {
     readonly id: string;
@@ -30,12 +41,24 @@ export declare class Session {
     private readonly pluginHost?;
     private readonly contextManager;
     private readonly services;
+    private readonly approvalManager;
+    private readonly notificationBus;
+    private readonly compactionService;
+    private readonly pluginStateService;
+    private readonly pluginControllers;
+    private activeRunCount;
     constructor(options: SessionOptions);
     get messages(): Message[];
     get usage(): Usage;
+    getStatus(): SessionStatus;
+    getCompactionState(): CompactionState;
+    getPluginState(pluginId: string): PluginSessionStateEntry | null;
+    listPluginStates(): Record<string, PluginSessionStateEntry>;
+    getPlugin<T = unknown>(pluginId: string): T | null;
     get updatedAt(): number;
     getCwd(): string | undefined;
     setCwd(cwd: string): void;
+    compact(update: CompactionUpdate): Promise<void>;
     save(): Promise<void>;
     toSnapshot(): SessionSnapshot;
     send(input: MessageContentInput, options?: {
@@ -45,4 +68,6 @@ export declare class Session {
         signal?: AbortSignal;
     }): AsyncGenerator<SessionStreamEvent, AssistantMessage, void>;
     private createLoopRunner;
+    private readEstimatedInputTokens;
+    private createHookContext;
 }

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/ToolExecutor.d.ts

@@ -1,10 +1,16 @@
-import type { CallToolResult, ToolCall } from '../contracts';
+import type { CallToolResult, SessionPluginEvent, SessionStatus, ToolCall } from '../contracts';
 import type { PluginHost } from '../plugin-host/PluginHost';
 import type { AgentServices } from '../services';
 import type { ToolRegistry } from '../tools/ToolRegistry';
+import type { ApprovalManager } from './approvals';
+import type { NotificationBus } from './notifications';
 export interface ToolExecutorExecuteOptions {
     signal?: AbortSignal;
     cwd?: string;
+    requestId?: string;
+    iteration?: number;
+    status?: SessionStatus;
+    onEvent?: (event: SessionPluginEvent) => Promise<void> | void;
 }
 export interface ToolExecutor {
     execute(toolCall: ToolCall, options?: ToolExecutorExecuteOptions): Promise<CallToolResult>;
@@ -15,6 +21,8 @@ export interface ToolExecutorOptions {
     metadata?: Record<string, unknown>;
     services: AgentServices;
     pluginHost?: PluginHost;
+    approvalManager: ApprovalManager;
+    notificationBus: NotificationBus;
 }
 export declare class DefaultToolExecutor implements ToolExecutor {
     private readonly sessionId;
@@ -22,6 +30,8 @@ export declare class DefaultToolExecutor implements ToolExecutor {
     private readonly metadata?;
     private readonly services;
     private readonly pluginHost?;
+    private readonly approvalManager;
+    private readonly notificationBus;
     constructor(options: ToolExecutorOptions);
     execute(toolCall: ToolCall, options?: ToolExecutorExecuteOptions): Promise<CallToolResult>;
 }

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/agent-types.d.ts

@@ -1,9 +1,10 @@
-import type { Message, MessageContentInput, ModelClient, Tool } from '../contracts';
+import type { DimPlugin } from '@archships/dim-plugin-api';
+import type { CompactionOptions, 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';
+import type { ApprovalHandler } from './approvals';
 export interface AgentOptions {
     model: ModelClient;
     tools?: ToolRegistry | Tool[];
@@ -16,6 +17,8 @@ export interface AgentOptions {
     contextManager?: ContextManager;
     includeBuiltinTools?: boolean;
     reasoning?: Record<string, unknown>;
+    approvalHandler?: ApprovalHandler;
+    compaction?: CompactionOptions;
 }
 export interface CreateSessionOptions {
     sessionId?: string;

package/dist/dim-agent-sdk/src/agent-core/approvals.d.ts

@@ -0,0 +1,25 @@
+import type { ApprovalDecision, ApprovalRequest } from '@archships/dim-plugin-api';
+import type { SessionStatus } from '../contracts';
+import type { NotificationBus } from './notifications';
+export type ApprovalHandler = (request: ApprovalRequest) => ApprovalDecision | Promise<ApprovalDecision>;
+export interface ApprovalContext {
+    sessionId: string;
+    requestId?: string;
+    iteration?: number;
+    cwd?: string;
+    status?: SessionStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface ApprovalManager {
+    requestApproval(request: ApprovalRequest, context: ApprovalContext): Promise<ApprovalDecision>;
+}
+export interface DefaultApprovalManagerOptions {
+    handler?: ApprovalHandler;
+    notifications?: NotificationBus;
+}
+export declare class DefaultApprovalManager implements ApprovalManager {
+    private readonly handler?;
+    private readonly notifications?;
+    constructor(options?: DefaultApprovalManagerOptions);
+    requestApproval(request: ApprovalRequest, context: ApprovalContext): Promise<ApprovalDecision>;
+}

package/dist/dim-agent-sdk/src/agent-core/compaction.d.ts

@@ -0,0 +1,22 @@
+import type { CompactionBudgetInfo, CompactionEstimatorInput, CompactionOptions, CompactionService, CompactionServiceUpdate, CompactionState, CompactionUpdate, Message } from '../contracts';
+import type { RuntimeSessionState } from './session-state';
+export declare function createEmptyCompactionState(): CompactionState;
+export declare function cloneCompactionState(state: CompactionState | undefined): CompactionState;
+export declare function normalizeCompactionState(state: CompactionState | undefined, messages: Message[]): CompactionState;
+export declare function applyCompactionUpdate(state: RuntimeSessionState, update: CompactionUpdate): CompactionState;
+export declare function clearCompactionState(state: RuntimeSessionState): CompactionState;
+export declare function projectMessagesForRequest(messages: Message[], compaction: CompactionState): Message[];
+export declare function buildCompactionPromptSegments(compaction: CompactionState): string[];
+export declare function calculateThresholdTokens(options: CompactionOptions): number;
+export declare function estimateCompactionBudget(options: CompactionOptions, input: CompactionEstimatorInput): Promise<CompactionBudgetInfo>;
+export declare function isCompactionRequired(options: CompactionOptions | undefined, budget: CompactionBudgetInfo | undefined): boolean;
+export declare function didCompactionStateChange(before: CompactionState, after: CompactionState): boolean;
+export declare class DefaultCompactionService implements CompactionService {
+    private readonly sessions;
+    registerSession(state: RuntimeSessionState): void;
+    unregisterSession(sessionId: string): void;
+    getState(sessionId: string): Promise<CompactionState>;
+    apply(update: CompactionServiceUpdate): Promise<CompactionState>;
+    clear(sessionId: string): Promise<CompactionState>;
+    private requireSession;
+}

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/errors.d.ts

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

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/index.d.ts

@@ -1,5 +1,10 @@
 export { Agent, createAgent } from './Agent';
+export type { ApprovalContext, ApprovalHandler, ApprovalManager } from './approvals';
+export { DefaultCompactionService, applyCompactionUpdate, buildCompactionPromptSegments, calculateThresholdTokens, clearCompactionState, cloneCompactionState, createEmptyCompactionState, didCompactionStateChange, estimateCompactionBudget, isCompactionRequired, normalizeCompactionState, projectMessagesForRequest, } from './compaction';
+export { DefaultPluginStateService, clonePluginSessionStateEntry, clonePluginStateMap, normalizePluginStateMap, } from './plugin-state';
 export { createModel } from './createModel';
+export { DefaultApprovalManager } from './approvals';
+export { DefaultNotificationBus } from './notifications';
 export { Session } from './Session';
 export { SessionExecutionError } from './errors';
 export type { AgentOptions, CreateSessionOptions } from './agent-types';
@@ -7,7 +12,9 @@ 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 { NotificationBus, NotificationContext } from './notifications';
 export type { RuntimeSessionState } from './session-state';
 export type { SessionOptions } from './Session';
+export type { SubagentInvocation, SubagentResult, SubagentRuntime } from './subagent';
 export type { TerminationDecision, TerminationPolicy } from './TerminationPolicy';
 export type { ToolExecutor, ToolExecutorExecuteOptions, ToolExecutorOptions } from './ToolExecutor';

package/dist/dim-agent-sdk/src/agent-core/notifications.d.ts

@@ -0,0 +1,25 @@
+import type { SessionStatus } from '../contracts';
+import type { NotificationPayload } from '@archships/dim-plugin-api';
+import type { PluginHost } from '../plugin-host/PluginHost';
+import type { AgentServices } from '../services';
+export interface NotificationContext {
+    sessionId?: string;
+    requestId?: string;
+    iteration?: number;
+    cwd?: string;
+    status?: SessionStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface NotificationBus {
+    emit(notification: NotificationPayload, context?: NotificationContext): Promise<NotificationPayload | undefined>;
+}
+export interface DefaultNotificationBusOptions {
+    pluginHost?: PluginHost;
+    services: AgentServices;
+}
+export declare class DefaultNotificationBus implements NotificationBus {
+    private readonly pluginHost?;
+    private readonly services;
+    constructor(options: DefaultNotificationBusOptions);
+    emit(notification: NotificationPayload, context?: NotificationContext): Promise<NotificationPayload | undefined>;
+}

package/dist/dim-agent-sdk/src/agent-core/plugin-state.d.ts

@@ -0,0 +1,24 @@
+import type { PluginSessionStateEntry, PluginStateService } from '../contracts';
+import type { RuntimeSessionState } from './session-state';
+export interface PluginStateManager extends PluginStateService {
+    getForPlugin(sessionId: string, pluginId: string): Promise<PluginSessionStateEntry | null>;
+    replaceForPlugin(sessionId: string, pluginId: string, entry: PluginSessionStateEntry): Promise<PluginSessionStateEntry>;
+    clearForPlugin(sessionId: string, pluginId: string): Promise<void>;
+    list(sessionId: string): Promise<Record<string, PluginSessionStateEntry>>;
+}
+export declare function clonePluginSessionStateEntry(entry: PluginSessionStateEntry | null | undefined): PluginSessionStateEntry | null;
+export declare function clonePluginStateMap(state: Record<string, PluginSessionStateEntry> | undefined): Record<string, PluginSessionStateEntry>;
+export declare function normalizePluginStateMap(state: Record<string, PluginSessionStateEntry> | undefined): Record<string, PluginSessionStateEntry>;
+export declare class DefaultPluginStateService implements PluginStateManager {
+    private readonly sessions;
+    registerSession(state: RuntimeSessionState): void;
+    unregisterSession(sessionId: string): void;
+    get(sessionId: string): Promise<PluginSessionStateEntry | null>;
+    replace(sessionId: string, entry: PluginSessionStateEntry): Promise<PluginSessionStateEntry>;
+    clear(sessionId: string): Promise<void>;
+    getForPlugin(sessionId: string, pluginId: string): Promise<PluginSessionStateEntry | null>;
+    replaceForPlugin(sessionId: string, pluginId: string, entry: PluginSessionStateEntry): Promise<PluginSessionStateEntry>;
+    clearForPlugin(sessionId: string, pluginId: string): Promise<void>;
+    list(sessionId: string): Promise<Record<string, PluginSessionStateEntry>>;
+    private requireSession;
+}

package/dist/{agent-core → dim-agent-sdk/src/agent-core}/session-state.d.ts

@@ -1,4 +1,4 @@
-import type { Message, ModelClient, ModelRef, Usage } from '../contracts';
+import type { CompactionOptions, CompactionState, Message, ModelClient, ModelRef, PluginSessionStateEntry, Usage } from '../contracts';
 import type { ToolRegistry } from '../tools/ToolRegistry';
 export interface RuntimeSessionState {
     id: string;
@@ -11,6 +11,9 @@ export interface RuntimeSessionState {
     reasoning?: Record<string, unknown>;
     messages: Message[];
     usage: Usage;
+    compaction: CompactionState;
+    pluginState: Record<string, PluginSessionStateEntry>;
+    compactionOptions?: CompactionOptions;
     createdAt: number;
     updatedAt: number;
 }

package/dist/dim-agent-sdk/src/agent-core/session-status.d.ts

@@ -0,0 +1,4 @@
+import type { SessionStatus } from '../contracts';
+import type { RuntimeSessionState } from './session-state';
+export declare function createSessionStatus(state: RuntimeSessionState): SessionStatus;
+export declare function cloneSessionStatus(status: SessionStatus | undefined): SessionStatus | undefined;

package/dist/dim-agent-sdk/src/agent-core/subagent.d.ts

@@ -0,0 +1,14 @@
+import type { AssistantMessage, MessageContentInput } from '../contracts';
+export interface SubagentInvocation {
+    id: string;
+    name: string;
+    input: MessageContentInput;
+    metadata?: Record<string, unknown>;
+}
+export interface SubagentResult {
+    message: AssistantMessage;
+    metadata?: Record<string, unknown>;
+}
+export interface SubagentRuntime {
+    run(invocation: SubagentInvocation): Promise<SubagentResult>;
+}

package/dist/dim-agent-sdk/src/context/compaction.d.ts

@@ -0,0 +1 @@
+export type { CompactionBudgetInfo, CompactionCheckpoint, CompactionEstimator, CompactionEstimatorInput, CompactionOptions, CompactionService, CompactionState, CompactionTriggerReason, CompactionUpdate, } from '../contracts/compaction';

package/dist/dim-agent-sdk/src/context/index.d.ts

@@ -0,0 +1,4 @@
+export { AutoContextManager } from './AutoContextManager';
+export type { AutoContextManagerOptions } from './AutoContextManager';
+export type { CompactionBudgetInfo, CompactionCheckpoint, CompactionEstimator, CompactionEstimatorInput, CompactionOptions, CompactionService, CompactionState, CompactionTriggerReason, CompactionUpdate, } from './compaction';
+export type { ContextItem, ContextManager, ContextResolveOptions } from './types';

package/dist/dim-agent-sdk/src/contracts/compaction.d.ts

@@ -0,0 +1,52 @@
+import type { Message } from './message';
+import type { ModelRef } from './model';
+import type { ToolDefinition } from './tool';
+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 CompactionBudgetInfo {
+    estimatedInputTokens: number;
+    thresholdTokens: number;
+    maxInputTokens: number;
+}
+export interface CompactionEstimatorInput {
+    model: ModelRef;
+    messages: Message[];
+    tools?: ToolDefinition[];
+}
+export type CompactionEstimator = (input: CompactionEstimatorInput) => number | Promise<number>;
+export interface CompactionOptions {
+    enabled?: boolean;
+    maxInputTokens: number;
+    triggerTokens?: number;
+    triggerRatio?: number;
+    estimator?: CompactionEstimator;
+    ownerPluginId?: string;
+}
+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>;
+}

package/dist/{contracts → dim-agent-sdk/src/contracts}/event.d.ts

@@ -1,6 +1,13 @@
 import type { SessionErrorPayload, Usage } from './common';
 import type { AssistantMessage } from './message';
 import type { CallToolResult, ToolCall } from './tool';
+export interface SessionPluginEvent {
+    type: 'plugin_event';
+    sessionId: string;
+    pluginId: string;
+    event: string;
+    data?: Record<string, unknown>;
+}
 export type SessionStreamEvent = {
     type: 'text_delta';
     sessionId: string;
@@ -18,7 +25,7 @@ export type SessionStreamEvent = {
     sessionId: string;
     toolCallId: string;
     result: CallToolResult;
-} | {
+} | SessionPluginEvent | {
     type: 'done';
     sessionId: string;
     message: AssistantMessage;

package/dist/{contracts → dim-agent-sdk/src/contracts}/index.d.ts

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

package/dist/dim-agent-sdk/src/contracts/plugin-state.d.ts

@@ -0,0 +1,11 @@
+import type { JsonObject } from './common';
+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>;
+}

package/dist/dim-agent-sdk/src/contracts/state.d.ts

@@ -0,0 +1,29 @@
+import type { CompactionState } from './compaction';
+import type { PluginSessionStateEntry } from './plugin-state';
+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;
+    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>;
+}

package/dist/{contracts → dim-agent-sdk/src/contracts}/tool.d.ts

@@ -27,12 +27,18 @@ export interface CallToolResult {
     structuredContent?: JsonObject;
     isError?: boolean;
 }
+export interface ToolExecutionPluginEvent {
+    pluginId?: string;
+    event: string;
+    data?: JsonObject;
+}
 export interface ToolExecutionContext {
     sessionId: string;
     cwd?: string;
     signal?: AbortSignal;
     metadata?: Record<string, unknown>;
     services?: AgentServices;
+    emitEvent?(event: ToolExecutionPluginEvent): Promise<void> | void;
 }
 export interface Tool {
     readonly definition: ToolDefinition;