@myagentroam/agent 0.11.33 → 0.11.35

package/dist/extensions/agents.d.ts

@@ -0,0 +1,100 @@
+import type { AgentReasoningEffort } from '../model/configuration.js';
+import type { SubagentTaskSnapshot, SubagentManyOutput, SubagentHandledResult } from '../subagent/contracts.js';
+import type { ExtensionOperationContext } from './operation.js';
+import type { ExtensionResourceScope } from './resources.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionCapabilitySnapshot } from './capabilities.js';
+export type ExtensionAgentSnapshot = Readonly<SubagentTaskSnapshot>;
+export type ExtensionAgentManySnapshot = Readonly<SubagentManyOutput>;
+export type ExtensionAgentWaitResult = ExtensionAgentSnapshot | ExtensionAgentManySnapshot;
+export type ExtensionAgentHandledResult = SubagentHandledResult;
+export type ExtensionAgentSpawnResult = ExtensionAgentSnapshot | ExtensionAgentHandledResult;
+export declare function isHandledAgentResult(value: ExtensionAgentSpawnResult | ExtensionAgentManySnapshot): value is ExtensionAgentHandledResult;
+export interface ExtensionAgentSpawnInput {
+    readonly turnSignal?: AbortSignal;
+    readonly waitFor?: 'start' | 'completion';
+    readonly background?: boolean;
+    readonly prompt: string;
+    readonly description?: string;
+    readonly modelId?: string;
+    readonly reasoningEffort?: AgentReasoningEffort;
+    readonly role?: 'general-purpose' | 'explore';
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionAgentTarget {
+    readonly agentId: string;
+    readonly signal?: AbortSignal;
+}
+export interface ExtensionAgentWaitInput {
+    readonly untilSettled?: true;
+    readonly agentId?: string;
+    readonly agentIds?: readonly string[];
+    readonly mode?: 'any' | 'all';
+    readonly signal?: AbortSignal;
+    readonly waitMs?: number;
+    readonly waitFor?: 'completion' | 'message';
+}
+export interface ExtensionAgentMessageInput extends ExtensionAgentTarget {
+    readonly message: string;
+    readonly delivery?: 'append' | 'replace';
+}
+export interface ExtensionAgentsBackend {
+    own(ownerInstanceId: string): () => Promise<void>;
+    spawn(input: ExtensionAgentSpawnInput, call: ExtensionOperationContext): Promise<ExtensionAgentSnapshot>;
+    list(call: ExtensionOperationContext): Promise<readonly ExtensionAgentSnapshot[]>;
+    inspect(input: ExtensionAgentTarget, call: ExtensionOperationContext): Promise<ExtensionAgentSnapshot>;
+    wait(input: ExtensionAgentWaitInput, call: ExtensionOperationContext): Promise<ExtensionAgentWaitResult>;
+    message(input: ExtensionAgentMessageInput, call: ExtensionOperationContext): Promise<ExtensionAgentSnapshot>;
+    cancel(input: ExtensionAgentTarget, call: ExtensionOperationContext): Promise<ExtensionAgentSnapshot>;
+}
+export interface ExtensionAgentsApi {
+    spawn(input: ExtensionAgentSpawnInput): Promise<ExtensionAgentSpawnResult>;
+    list(input?: {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly ExtensionAgentSnapshot[]>;
+    inspect(input: ExtensionAgentTarget): Promise<ExtensionAgentSnapshot>;
+    wait(input: ExtensionAgentWaitInput & {
+        readonly agentIds: readonly string[];
+    }): Promise<ExtensionAgentManySnapshot>;
+    wait(input: ExtensionAgentWaitInput & {
+        readonly agentIds?: undefined;
+    }): Promise<ExtensionAgentSnapshot>;
+    wait(input: ExtensionAgentWaitInput): Promise<ExtensionAgentWaitResult>;
+    message(input: ExtensionAgentMessageInput): Promise<ExtensionAgentSnapshot>;
+    cancel(input: ExtensionAgentTarget): Promise<ExtensionAgentSnapshot>;
+}
+export interface ExtensionAgentCompletion {
+    readonly operation: 'spawn' | 'wait' | 'message' | 'cancel';
+    readonly agentId: string;
+    readonly status: SubagentTaskSnapshot['status'];
+    readonly deliveryStatus?: SubagentTaskSnapshot['deliveryStatus'];
+}
+type AgentOperation = 'agent.spawn' | 'agent.wait' | 'agent.message' | 'agent.cancel';
+export type ExtensionAgentAction = <Key extends AgentOperation>(key: Key, input: DomainAgentOperations[Key]['input'], leaf: (input: DomainAgentOperations[Key]['input'], call: ExtensionOperationContext) => Promise<DomainAgentOperations[Key]['output']>) => Promise<DomainAgentOperations[Key]['output']>;
+/** All callers share one interception and authoritative leaf-completion boundary. */
+export declare function invokeCoreAgentOperation<Key extends AgentOperation>(hooks: Pick<ExtensionHooks<DomainAgentOperations, DomainAgentFacts>, 'invoke' | 'emit'>, key: Key, input: DomainAgentOperations[Key]['input'], call: ExtensionOperationContext, leaf: (input: DomainAgentOperations[Key]['input'], call: ExtensionOperationContext) => Promise<DomainAgentOperations[Key]['output']>): Promise<DomainAgentOperations[Key]['output']>;
+export declare function resolveAgentSpawn(input: ExtensionAgentSpawnInput): ExtensionAgentSpawnInput;
+export declare function agentCapabilities(capabilities: ExtensionCapabilitySnapshot, available: boolean): ExtensionCapabilitySnapshot;
+export declare function bindCoreAgents(backend: ExtensionAgentsBackend, scope: ExtensionResourceScope, run: <Value>(operation: (call: ExtensionOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, hooks: Pick<ExtensionHooks<DomainAgentOperations, DomainAgentFacts>, 'invoke' | 'emit'>): ExtensionAgentsApi;
+export interface DomainAgentOperations {
+    'agent.spawn': {
+        input: ExtensionAgentSpawnInput;
+        output: ExtensionAgentSpawnResult;
+    };
+    'agent.wait': {
+        input: ExtensionAgentWaitInput;
+        output: ExtensionAgentWaitResult;
+    };
+    'agent.message': {
+        input: ExtensionAgentMessageInput;
+        output: ExtensionAgentSnapshot;
+    };
+    'agent.cancel': {
+        input: ExtensionAgentTarget;
+        output: ExtensionAgentSnapshot;
+    };
+}
+export interface DomainAgentFacts {
+    'agent.completed': ExtensionAgentCompletion;
+}
+export {};

package/dist/extensions/agents.js

@@ -0,0 +1,121 @@
+import { AgentError } from '../error.js';
+import { parseAgentWaitTargets } from '../subagent/wait-targets.js';
+export function isHandledAgentResult(value) {
+    return 'outcome' in value && value.outcome === 'handled' && !Object.hasOwn(value, 'agentId');
+}
+/** All callers share one interception and authoritative leaf-completion boundary. */
+export function invokeCoreAgentOperation(hooks, key, input, call, leaf) {
+    return hooks.invoke(key, input, call, async (input, effective) => {
+        const result = structuredClone(await leaf(input, effective));
+        if (isHandledAgentResult(result))
+            return result;
+        const agents = Array.isArray(result.agents)
+            ? result.agents
+            : [result];
+        for (const agent of agents)
+            await hooks.emit('agent.completed', {
+                operation: key.slice('agent.'.length),
+                agentId: agent.agentId,
+                status: agent.status,
+                ...(agent.deliveryStatus === undefined ? {} : { deliveryStatus: agent.deliveryStatus })
+            }, effective);
+        return result;
+    });
+}
+export function resolveAgentSpawn(input) {
+    if (!input ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        typeof input.prompt !== 'string' ||
+        !input.prompt.trim() ||
+        (input.turnSignal !== undefined && !(input.turnSignal instanceof AbortSignal)) ||
+        (input.description !== undefined &&
+            (typeof input.description !== 'string' || !input.description.trim())) ||
+        (input.modelId !== undefined && (typeof input.modelId !== 'string' || !input.modelId)) ||
+        (input.role !== undefined && input.role !== 'general-purpose' && input.role !== 'explore') ||
+        (input.background !== undefined && typeof input.background !== 'boolean') ||
+        (input.waitFor !== undefined && input.waitFor !== 'start' && input.waitFor !== 'completion') ||
+        (input.reasoningEffort !== undefined &&
+            !['low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(input.reasoningEffort)))
+        throw invalid('Agent spawn input is invalid.');
+    return {
+        prompt: input.prompt,
+        ...(input.turnSignal === undefined ? {} : { turnSignal: input.turnSignal }),
+        ...(input.waitFor === undefined ? {} : { waitFor: input.waitFor }),
+        ...(input.background === undefined ? {} : { background: input.background }),
+        description: input.description ?? 'Extension agent',
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+        ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
+        ...(input.reasoningEffort === undefined ? {} : { reasoningEffort: input.reasoningEffort }),
+        role: input.role ?? 'general-purpose'
+    };
+}
+export function agentCapabilities(capabilities, available) {
+    const values = Object.freeze(capabilities.list().filter((id) => id !== 'agents' || available));
+    return Object.freeze({ has: (id) => values.includes(id), list: () => values });
+}
+export function bindCoreAgents(backend, scope, run, hooks) {
+    scope.effect(() => backend.own(scope.instanceId));
+    const invoke = (key, input) => run((call) => invokeCoreAgentOperation(hooks, key, input, call, async (effectiveInput, effective) => {
+        let result;
+        switch (key) {
+            case 'agent.spawn':
+                result = await backend.spawn({
+                    ...resolveAgentSpawn(effectiveInput),
+                    ...(effectiveInput.turnSignal === undefined
+                        ? {}
+                        : {
+                            turnSignal: AbortSignal.any([
+                                scope.signal,
+                                effectiveInput.turnSignal
+                            ])
+                        })
+                }, effective);
+                break;
+            case 'agent.wait':
+                result = await backend.wait(effectiveInput, effective);
+                break;
+            case 'agent.message':
+                result = await backend.message(effectiveInput, effective);
+                break;
+            case 'agent.cancel':
+                result = await backend.cancel(effectiveInput, effective);
+                break;
+        }
+        return result;
+    }), input.signal);
+    const target = (input) => {
+        if (!input ||
+            typeof input !== 'object' ||
+            Array.isArray(input) ||
+            typeof input.agentId !== 'string' ||
+            !input.agentId)
+            throw invalid('Agent target is invalid.');
+        return { ...input };
+    };
+    return {
+        spawn: (input) => invoke('agent.spawn', { ...input }),
+        list: async (input = {}) => {
+            if (!input || typeof input !== 'object' || Array.isArray(input))
+                throw invalid('Agent list input is invalid.');
+            return run(async (call) => structuredClone(await backend.list(call)), input.signal);
+        },
+        inspect: async (input) => {
+            const copied = target(input);
+            return run(async (call) => structuredClone(await backend.inspect(copied, call)), copied.signal);
+        },
+        wait: (async (input) => {
+            if (!input || typeof input !== 'object' || Array.isArray(input))
+                throw invalid('Agent wait input is invalid.');
+            const selection = parseAgentWaitTargets(input);
+            return invoke('agent.wait', input.agentId === undefined
+                ? { ...input, ...selection }
+                : target(input));
+        }),
+        message: async (input) => invoke('agent.message', target(input)),
+        cancel: async (input) => invoke('agent.cancel', target(input))
+    };
+}
+function invalid(message) {
+    return new AgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', message);
+}

package/dist/extensions/capabilities.d.ts

@@ -0,0 +1,4 @@
+export interface ExtensionCapabilitySnapshot {
+    has(id: string): boolean;
+    list(): readonly string[];
+}

package/dist/extensions/commands.d.ts

@@ -0,0 +1,23 @@
+import type { ExtensionCallbackRunner, ExtensionOperationContext, ExtensionOperationRunner } from './operation.js';
+import type { ExtensionResourceRegistration, ExtensionResourceScope } from './resources.js';
+export interface ExtensionCommandSpec {
+    readonly name: string;
+    readonly description?: string;
+    readonly override?: 'replace';
+    handler(args: unknown, call: ExtensionOperationContext): unknown | Promise<unknown>;
+}
+export interface ExtensionCommandsApi {
+    register(spec: ExtensionCommandSpec): ExtensionResourceRegistration;
+    list(): readonly Pick<ExtensionCommandSpec, 'name' | 'description'>[];
+    run(input: {
+        readonly name: string;
+        readonly args?: unknown;
+    }): Promise<unknown>;
+}
+/** Session command definitions follow the contributing Extension scope. */
+export declare class ExtensionCommands {
+    #private;
+    private readonly callback;
+    constructor(callback: ExtensionCallbackRunner);
+    bind(scope: ExtensionResourceScope, run: ExtensionOperationRunner): ExtensionCommandsApi;
+}

package/dist/extensions/commands.js

@@ -0,0 +1,45 @@
+import { AgentError } from '../error.js';
+/** Session command definitions follow the contributing Extension scope. */
+export class ExtensionCommands {
+    callback;
+    #entries = [];
+    constructor(callback) {
+        this.callback = callback;
+    }
+    bind(scope, run) {
+        return {
+            register: (spec) => {
+                if (typeof spec.name !== 'string' ||
+                    !spec.name.trim() ||
+                    typeof spec.handler !== 'function' ||
+                    (spec.override !== undefined && spec.override !== 'replace'))
+                    throw new AgentError('MAR_AGENT_EXTENSION_COMMAND_INVALID', 'Command definition is invalid.');
+                if (spec.override !== 'replace' &&
+                    this.#entries.some((entry) => entry.value.name === spec.name))
+                    throw new AgentError('MAR_AGENT_EXTENSION_COMMAND_CONFLICT', 'Command name conflicts.');
+                const entry = { value: Object.freeze({ ...spec }), scope };
+                const registration = scope.effect(() => () => {
+                    const index = this.#entries.indexOf(entry);
+                    if (index !== -1)
+                        this.#entries.splice(index, 1);
+                });
+                this.#entries.push(entry);
+                return registration;
+            },
+            list: () => [
+                ...new Map(this.#entries
+                    .filter((entry) => entry.scope.state === 'ACTIVE')
+                    .map((entry) => [entry.value.name, entry])).values()
+            ].map(({ value }) => ({
+                name: value.name,
+                ...(value.description ? { description: value.description } : {})
+            })),
+            run: (input) => run(async (context) => {
+                const entry = this.#entries.findLast((entry) => entry.scope.state === 'ACTIVE' && entry.value.name === input.name);
+                if (!entry)
+                    throw new AgentError('MAR_AGENT_EXTENSION_COMMAND_UNAVAILABLE', 'Command is unavailable.');
+                return entry.scope.run((signal) => this.callback(Object.freeze({ ...context, signal, ownerInstanceId: entry.scope.instanceId }), (call) => entry.value.handler(input.args, call)), context.signal);
+            })
+        };
+    }
+}

package/dist/extensions/compaction.d.ts

@@ -0,0 +1,36 @@
+import type { ExtensionCompactDiagnostic, ExtensionCompactResult } from '../runtime/compaction/contracts.js';
+export type { ExtensionCompactDiagnostic, ExtensionCompactResult } from '../runtime/compaction/contracts.js';
+import type { SessionModelMessage as ModelMessage } from '../session/model-request.js';
+export interface ExtensionCompactMessage {
+    readonly role: 'user' | 'assistant' | 'tool' | 'tool_call';
+    readonly content: string;
+    readonly callId?: string;
+    readonly name?: string;
+    readonly arguments?: unknown;
+}
+export interface ExtensionCompactContext {
+    readonly reportModelUsage?: ((usage: import('../model/usage-observer.js').ModelRequestUsage) => Promise<void> | void) | undefined;
+    readonly operationId: string;
+    readonly reason: 'manual' | 'automatic';
+    readonly messages: readonly ExtensionCompactMessage[];
+    readonly focus?: string;
+    readonly summaryTokenBudget: number;
+    /** Return the Core's default structured handoff contract, independent of model configuration. */
+    readonly getPrompt: () => string;
+    /** Private, bounded telemetry only; reporting never changes the generation result. */
+    readonly reportDiagnostic?: (diagnostic: ExtensionCompactDiagnostic) => Promise<void>;
+}
+/** Copy only neutral evidence; a hook never receives provider payloads or history ownership. */
+export declare function compactExtensionMessages(messages: readonly ModelMessage[]): readonly ExtensionCompactMessage[];
+/** Whitelist scalar facts; never copy arbitrary plugin payloads into the session log. */
+export declare function compactExtensionDiagnostic(value: unknown): ExtensionCompactDiagnostic | undefined;
+/** Invalid plugin results decline generation rather than altering the checkpoint contract. */
+export declare function compactExtensionResult(value: unknown, budget: number): ExtensionCompactResult | undefined;
+export interface DomainCompactOperations {
+    'compact.generate': {
+        input: ExtensionCompactContext;
+        output: ExtensionCompactResult | undefined;
+    };
+}
+export interface DomainCompactFacts {
+}

package/dist/extensions/contracts.d.ts

@@ -0,0 +1,147 @@
+import type { ExtensionCommandSpec } from './commands.js';
+import type { ExtensionPromptSection } from './prompt-composition.js';
+import type { ExtensionCapabilitySnapshot } from './capabilities.js';
+import type { ExtensionPromptComposition } from './prompt-composition.js';
+import type { ExtensionModelsApi } from './models.js';
+import type { ExtensionAgentsApi } from './agents.js';
+import type { ExtensionDataApi } from './data.js';
+import type { ExtensionMcpApi } from './mcp.js';
+import type { ExtensionFilesApi } from './files.js';
+import type { ExtensionEnvironmentApi } from './environment.js';
+import type { ExtensionSettingsApi } from './settings.js';
+import type { ExtensionProcessesApi } from './processes.js';
+import type { ExtensionNetworkApi } from './network.js';
+import type { ExtensionSessionApi } from './session-input.js';
+import type { ToolExecutionResult } from '../tools/contracts.js';
+import type { ExtensionHookOptions, ExtensionInterceptor } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+import type { ExtensionDisposer, ExtensionResourceRegistration, ExtensionResourceScope } from './resources.js';
+import type { ExtensionServiceRegistry } from './services.js';
+import type { ExtensionToolRef, ExtensionToolInvocation, ExtensionToolCheck, ExtensionToolSpec } from './tools.js';
+import type { DomainAgentOperations, DomainAgentFacts } from './agents.js';
+import type { DomainCompactOperations, DomainCompactFacts } from './compaction.js';
+import type { DomainEnvironmentOperations, DomainEnvironmentFacts } from './environment.js';
+import type { DomainFileOperations, DomainFileFacts } from './files.js';
+import type { DomainMcpOperations, DomainMcpFacts } from './mcp.js';
+import type { DomainModelRequestOperations, DomainModelRequestFacts } from './model-request.js';
+import type { DomainModelStreamOperations, DomainModelStreamFacts } from './model-stream.js';
+import type { DomainNetworkOperations, DomainNetworkFacts } from './network.js';
+import type { DomainProcessOperations, DomainProcessFacts } from './processes.js';
+import type { DomainPromptCompositionOperations, DomainPromptCompositionFacts } from './prompt-composition.js';
+import type { DomainPromptInputOperations, DomainPromptInputFacts } from './prompt-input.js';
+import type { DomainSessionOperations, DomainSessionFacts } from './session-input.js';
+import type { DomainSettingsOperations, DomainSettingsFacts } from './settings.js';
+import type { DomainToolOperations, DomainToolFacts } from './tools.js';
+export interface ExtensionDomainOperations extends DomainAgentOperations, DomainCompactOperations, DomainEnvironmentOperations, DomainFileOperations, DomainMcpOperations, DomainModelRequestOperations, DomainModelStreamOperations, DomainNetworkOperations, DomainProcessOperations, DomainPromptCompositionOperations, DomainPromptInputOperations, DomainSessionOperations, DomainSettingsOperations, DomainToolOperations {
+}
+export interface ExtensionDomainFacts extends DomainAgentFacts, DomainCompactFacts, DomainEnvironmentFacts, DomainFileFacts, DomainMcpFacts, DomainModelRequestFacts, DomainModelStreamFacts, DomainNetworkFacts, DomainProcessFacts, DomainPromptCompositionFacts, DomainPromptInputFacts, DomainSessionFacts, DomainSettingsFacts, DomainToolFacts {
+}
+export interface ExtensionHookRegistrar {
+    intercept<Key extends keyof ExtensionDomainOperations>(key: Key, handler: ExtensionInterceptor<ExtensionDomainOperations[Key]['input'], ExtensionDomainOperations[Key]['output']>, options?: ExtensionHookOptions): ExtensionResourceRegistration;
+    observe<Key extends keyof ExtensionDomainFacts>(key: Key, handler: (fact: ExtensionDomainFacts[Key], call: ExtensionOperationContext) => void | Promise<void>, options?: ExtensionHookOptions): ExtensionResourceRegistration;
+}
+export type { ExtensionCapabilitySnapshot } from './capabilities.js';
+export type { ExtensionCommandSpec } from './commands.js';
+export type { ExtensionPromptSection } from './prompt-composition.js';
+export interface AgentExtensionContext {
+    readonly data?: Pick<ExtensionDataApi, 'store'>;
+    readonly resources: ExtensionResourceScope;
+    readonly services: ExtensionServiceRegistry;
+    readonly capabilities: ExtensionCapabilitySnapshot;
+    readonly bindings: Readonly<Record<string, unknown>>;
+    readonly observability: {
+        log(message: string): void;
+    };
+}
+export interface SessionExtensionContext extends AgentExtensionContext {
+    readonly mcp?: ExtensionMcpApi;
+    readonly agents?: ExtensionAgentsApi;
+    readonly environment?: ExtensionEnvironmentApi;
+    readonly settings?: ExtensionSettingsApi;
+    readonly processes?: ExtensionProcessesApi;
+    readonly network?: ExtensionNetworkApi;
+    readonly files?: ExtensionFilesApi;
+    readonly sessionId: string;
+    readonly models?: ExtensionModelsApi;
+    readonly data: ExtensionDataApi;
+    readonly session?: ExtensionSessionApi;
+    readonly hooks: ExtensionHookRegistrar;
+    readonly tools: {
+        register(spec: ExtensionToolSpec): ExtensionResourceRegistration;
+        catalog(): readonly ExtensionToolRef[];
+        check(call: ExtensionToolInvocation): Promise<ExtensionToolCheck>;
+        invoke(call: ExtensionToolInvocation): Promise<ToolExecutionResult>;
+    };
+    readonly commands: {
+        register(spec: ExtensionCommandSpec): ExtensionResourceRegistration;
+        list(): readonly Pick<ExtensionCommandSpec, 'name' | 'description'>[];
+        run(input: {
+            readonly name: string;
+            readonly args?: unknown;
+        }): Promise<unknown>;
+    };
+    readonly prompts: {
+        register(section: ExtensionPromptSection): ExtensionResourceRegistration;
+        sections(): readonly ExtensionPromptSection[];
+        compose(system: string): Promise<string>;
+        composeSections(input: ExtensionPromptComposition): Promise<ExtensionPromptComposition>;
+        composeDefault(facts?: import('./prompt-composition.js').ExtensionPromptFacts): Promise<ExtensionPromptComposition>;
+    };
+    readonly clock: {
+        now(): number;
+        sleep(input: {
+            readonly durationMs: number;
+            readonly signal?: AbortSignal;
+        }): Promise<void>;
+        after(durationMs: number, callback: (call: ExtensionOperationContext) => void | Promise<void>): ExtensionResourceRegistration;
+        every(durationMs: number, callback: (call: ExtensionOperationContext) => void | Promise<void>): ExtensionResourceRegistration;
+    };
+}
+export interface ExtensionServiceDeclaration {
+    readonly key: {
+        readonly id: string;
+        readonly scope: 'agent' | 'session';
+    };
+    readonly intent?: 'provide' | 'replace' | 'wrap';
+}
+export interface ExtensionServiceDependency {
+    readonly key: {
+        readonly id: string;
+        readonly scope: 'agent' | 'session';
+    };
+    readonly optional?: boolean;
+}
+export interface AgentExtension {
+    readonly dataDirectory?: string;
+    readonly id: string;
+    readonly apiVersion: '1.0';
+    readonly bindings?: Readonly<Record<string, unknown>>;
+    readonly requires?: readonly {
+        readonly id: string;
+    }[];
+    readonly optional?: readonly {
+        readonly id: string;
+    }[];
+    readonly provides?: readonly ExtensionServiceDeclaration[];
+    readonly serviceDependencies?: readonly ExtensionServiceDependency[];
+    readonly failurePolicy?: 'disable-extension' | 'fail-composition';
+    setup?(context: AgentExtensionContext): void | ExtensionDisposer | Promise<void | ExtensionDisposer>;
+    attachSession?(context: SessionExtensionContext): void | ExtensionDisposer | Promise<void | ExtensionDisposer>;
+}
+export interface ExtensionSnapshot {
+    readonly revision: string;
+    readonly extensions: readonly AgentExtension[];
+}
+export interface ExtensionSource {
+    resolve(input: {
+        readonly signal: AbortSignal;
+    }): Promise<ExtensionSnapshot>;
+}
+export interface ExtensionDiagnostic {
+    readonly code: string;
+    readonly extensionId?: string;
+    readonly sessionId?: string;
+    readonly revision?: string;
+    readonly operationId?: string;
+    readonly message?: string;
+}

package/dist/extensions/data.d.ts

@@ -0,0 +1,81 @@
+import { type ExtensionCheckpoint, type ExtensionJsonValue } from '../session/extension-checkpoint.js';
+export { cloneCoreJson, type ExtensionCheckpoint, type ExtensionJsonValue } from '../session/extension-checkpoint.js';
+import type { ExtensionCallbackRunner, ExtensionOperationContext, ExtensionOperationRunner } from './operation.js';
+import type { ExtensionResourceRegistration } from './resources.js';
+import { ExtensionResourceScope } from './resources.js';
+/** Storage is installed by the application; lifecycle remains scoped by the extension. */
+export type ExtensionStoreBackend = (directory: string, run: <T>(operation: (signal: AbortSignal) => Promise<T>) => Promise<T>) => ExtensionStoreApi;
+export interface ExtensionCheckpointApi {
+    get(input: {
+        readonly key: string;
+    }): Promise<ExtensionCheckpoint>;
+    set(input: {
+        readonly key: string;
+        readonly value: ExtensionJsonValue;
+        readonly expectedRevision?: number;
+    }): Promise<ExtensionCheckpoint>;
+    delete(input: {
+        readonly key: string;
+        readonly expectedRevision?: number;
+    }): Promise<ExtensionCheckpoint>;
+}
+export interface ExtensionCheckpointBackend {
+    read(extensionId: string, key: string, call: ExtensionOperationContext): Promise<ExtensionCheckpoint>;
+    write(extensionId: string, key: string, value: ExtensionJsonValue | undefined, expectedRevision: number | undefined, call: ExtensionOperationContext): Promise<ExtensionCheckpoint>;
+}
+export interface ExtensionStateChange {
+    readonly key: string;
+    readonly revision: number;
+    readonly value?: ExtensionJsonValue;
+}
+export interface ExtensionStateApi {
+    read(key: string): Promise<ExtensionJsonValue | undefined>;
+    write(key: string, value: ExtensionJsonValue): Promise<number>;
+    delete(key: string): Promise<number>;
+    watch(handler: (change: ExtensionStateChange, call: ExtensionOperationContext) => void | Promise<void>): ExtensionResourceRegistration;
+}
+export interface ExtensionDataApi {
+    readonly store?: ExtensionStoreApi;
+    readonly state: ExtensionStateApi;
+    readonly checkpoint?: ExtensionCheckpointApi;
+}
+export declare function bindCoreData(state: ExtensionState, store: ExtensionStoreBackend | undefined, directory: string | undefined, checkpoint: ExtensionCheckpointBackend | undefined, extensionId: string, run: ExtensionOperationRunner): ExtensionDataApi;
+export interface ExtensionStoreCommit {
+    readonly expectedRevision?: number;
+    readonly writes: readonly {
+        readonly key: string;
+        readonly value?: ExtensionJsonValue;
+    }[];
+}
+export interface ExtensionStoreApi {
+    get(input: {
+        readonly key: string;
+    }): Promise<ExtensionCheckpoint>;
+    keys(): Promise<{
+        readonly revision: number;
+        readonly keys: readonly string[];
+    }>;
+    set(input: {
+        readonly key: string;
+        readonly value: ExtensionJsonValue;
+        readonly expectedRevision?: number;
+    }): Promise<ExtensionCheckpoint>;
+    delete(input: {
+        readonly key: string;
+        readonly expectedRevision?: number;
+    }): Promise<ExtensionCheckpoint>;
+    commit(input: ExtensionStoreCommit): Promise<{
+        readonly revision: number;
+    }>;
+}
+/** Explicit reactive state, not a proxy over the Session or a second persistence mechanism. */
+export declare class ExtensionState {
+    #private;
+    readonly scope: ExtensionResourceScope;
+    readonly diagnose: () => void;
+    readonly callback: ExtensionCallbackRunner;
+    constructor(scope: ExtensionResourceScope, diagnose: () => void, callback?: ExtensionCallbackRunner);
+    read(key: string): ExtensionJsonValue | undefined;
+    write(key: string, value: ExtensionJsonValue | undefined, call: ExtensionOperationContext): Promise<number>;
+    watch(handler: (change: ExtensionStateChange, call: ExtensionOperationContext) => void | Promise<void>): ExtensionResourceRegistration;
+}

package/dist/extensions/data.js

@@ -0,0 +1,78 @@
+import { cloneCoreJson } from '../session/extension-checkpoint.js';
+export { cloneCoreJson } from '../session/extension-checkpoint.js';
+import { AgentError } from '../error.js';
+export function bindCoreData(state, store, directory, checkpoint, extensionId, run) {
+    return {
+        ...(directory === undefined
+            ? {}
+            : { store: store(directory, (operation) => run((call) => operation(call.signal))) }),
+        state: {
+            read: (key) => run(async () => state.read(key)),
+            write: (key, value) => run((call) => state.write(key, value, call)),
+            delete: (key) => run((call) => state.write(key, undefined, call)),
+            watch: (handler) => state.watch(handler)
+        },
+        ...(checkpoint
+            ? {
+                checkpoint: {
+                    get: (input) => run((call) => checkpoint.read(extensionId, input.key, call)),
+                    set: (input) => run((call) => checkpoint.write(extensionId, input.key, input.value, input.expectedRevision, call)),
+                    delete: (input) => run((call) => checkpoint.write(extensionId, input.key, undefined, input.expectedRevision, call))
+                }
+            }
+            : {})
+    };
+}
+/** Explicit reactive state, not a proxy over the Session or a second persistence mechanism. */
+export class ExtensionState {
+    scope;
+    diagnose;
+    callback;
+    #values = new Map();
+    #observers = [];
+    #revision = 0;
+    constructor(scope, diagnose, callback = async (call, run) => run(call)) {
+        this.scope = scope;
+        this.diagnose = diagnose;
+        this.callback = callback;
+    }
+    read(key) {
+        const value = this.#values.get(key);
+        return value === undefined ? undefined : cloneCoreJson(value);
+    }
+    async write(key, value, call) {
+        if (typeof key !== 'string')
+            throw new AgentError('MAR_AGENT_EXTENSION_DATA_INVALID', 'State key must be a string.');
+        const committed = value === undefined ? undefined : cloneCoreJson(value);
+        if (committed === undefined)
+            this.#values.delete(key);
+        else
+            this.#values.set(key, committed);
+        const revision = ++this.#revision;
+        const change = {
+            key,
+            revision,
+            ...(committed !== undefined ? { value: cloneCoreJson(committed) } : {})
+        };
+        if (this.scope.state === 'ACTIVE')
+            for (const observer of [...this.#observers]) {
+                try {
+                    await this.scope.run((signal) => this.callback(Object.freeze({ ...call, signal }), (effective) => observer(structuredClone(change), effective)), call.signal);
+                }
+                catch {
+                    call.signal.throwIfAborted();
+                    this.diagnose();
+                }
+            }
+        return revision;
+    }
+    watch(handler) {
+        const registration = this.scope.effect(() => () => {
+            const index = this.#observers.indexOf(handler);
+            if (index !== -1)
+                this.#observers.splice(index, 1);
+        });
+        this.#observers.push(handler);
+        return registration;
+    }
+}