@myagentroam/agent 0.9.159 → 0.9.160

package/dist/agent-core/extensions/agents.d.ts

@@ -0,0 +1,69 @@
+import type { MarAgentReasoningEffort } from '../model/configuration.js';
+import type { SubagentController, SubagentTaskSnapshot, SubagentHandledResult } from '../subagent/contracts.js';
+import type { CoreOperationContext } from './operation.js';
+import type { ExtensionResourceScope } from './resources.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { CoreDomainOperations, CoreDomainFacts, CoreCapabilitySnapshot } from './contracts.js';
+export type CoreAgentSnapshot = Readonly<SubagentTaskSnapshot>;
+export type CoreAgentHandledResult = SubagentHandledResult;
+export type CoreAgentSpawnResult = CoreAgentSnapshot | CoreAgentHandledResult;
+export declare function isHandledAgentResult(value: CoreAgentSpawnResult): value is CoreAgentHandledResult;
+export interface CoreAgentSpawnInput {
+    readonly turnSignal?: AbortSignal;
+    readonly waitFor?: 'start' | 'completion';
+    readonly background?: boolean;
+    readonly prompt: string;
+    readonly description?: string;
+    readonly modelId?: string;
+    readonly reasoningEffort?: MarAgentReasoningEffort;
+    readonly role?: 'general-purpose' | 'explore';
+    readonly signal?: AbortSignal;
+}
+export interface CoreAgentTarget {
+    readonly agentId: string;
+    readonly signal?: AbortSignal;
+}
+export interface CoreAgentWaitInput {
+    readonly untilSettled?: true;
+    readonly agentId?: string;
+    readonly signal?: AbortSignal;
+    readonly waitMs?: number;
+    readonly waitFor?: 'completion' | 'message';
+}
+export interface CoreAgentMessageInput extends CoreAgentTarget {
+    readonly message: string;
+    readonly delivery?: 'append' | 'replace';
+}
+export interface CoreAgentsBackend {
+    own(ownerInstanceId: string): () => Promise<void>;
+    spawn(input: CoreAgentSpawnInput, call: CoreOperationContext): Promise<CoreAgentSnapshot>;
+    list(call: CoreOperationContext): Promise<readonly CoreAgentSnapshot[]>;
+    inspect(input: CoreAgentTarget, call: CoreOperationContext): Promise<CoreAgentSnapshot>;
+    wait(input: CoreAgentWaitInput, call: CoreOperationContext): Promise<CoreAgentSnapshot>;
+    message(input: CoreAgentMessageInput, call: CoreOperationContext): Promise<CoreAgentSnapshot>;
+    cancel(input: CoreAgentTarget, call: CoreOperationContext): Promise<CoreAgentSnapshot>;
+}
+export interface CoreAgentsApi {
+    spawn(input: CoreAgentSpawnInput): Promise<CoreAgentSpawnResult>;
+    list(input?: {
+        readonly signal?: AbortSignal;
+    }): Promise<readonly CoreAgentSnapshot[]>;
+    inspect(input: CoreAgentTarget): Promise<CoreAgentSnapshot>;
+    wait(input: CoreAgentWaitInput): Promise<CoreAgentSnapshot>;
+    message(input: CoreAgentMessageInput): Promise<CoreAgentSnapshot>;
+    cancel(input: CoreAgentTarget): Promise<CoreAgentSnapshot>;
+}
+export interface CoreAgentCompletion {
+    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 CoreAgentAction = <Key extends AgentOperation>(key: Key, input: CoreDomainOperations[Key]['input'], leaf: (input: CoreDomainOperations[Key]['input'], call: CoreOperationContext) => Promise<CoreDomainOperations[Key]['output']>) => Promise<CoreDomainOperations[Key]['output']>;
+/** All callers share one interception and authoritative leaf-completion boundary. */
+export declare function invokeCoreAgentOperation<Key extends AgentOperation>(hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>, key: Key, input: CoreDomainOperations[Key]['input'], call: CoreOperationContext, leaf: (input: CoreDomainOperations[Key]['input'], call: CoreOperationContext) => Promise<CoreDomainOperations[Key]['output']>): Promise<CoreDomainOperations[Key]['output']>;
+export declare function bindAgentController(controller: SubagentController, action: CoreAgentAction): SubagentController;
+export declare function agentCapabilities(capabilities: CoreCapabilitySnapshot, available: boolean): CoreCapabilitySnapshot;
+export declare function bindCoreAgents(backend: CoreAgentsBackend, scope: ExtensionResourceScope, run: <Value>(operation: (call: CoreOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>): CoreAgentsApi;
+export {};

package/dist/agent-core/extensions/agents.js

@@ -0,0 +1,160 @@
+import { MarAgentError } from '../error.js';
+export function isHandledAgentResult(value) {
+    return 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;
+        await hooks.emit('agent.completed', {
+            operation: key.slice('agent.'.length),
+            agentId: result.agentId,
+            status: result.status,
+            ...(result.deliveryStatus === undefined ? {} : { deliveryStatus: result.deliveryStatus })
+        }, effective);
+        return result;
+    });
+}
+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 bindAgentController(controller, action) {
+    const wait = (input) => action('agent.wait', input, (target, call) => target.agentId === undefined
+        ? controller.outputAny({ ...target, signal: call.signal })
+        : controller.output(target.agentId, { ...target, signal: call.signal }));
+    return {
+        run: (input, options) => {
+            return action('agent.spawn', {
+                ...(options?.waitFor === undefined ? {} : { waitFor: options.waitFor }),
+                prompt: input.prompt,
+                description: input.description,
+                role: input.role,
+                background: input.background ?? false,
+                ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
+                ...(input.reasoningEffort === undefined ? {} : { reasoningEffort: input.reasoningEffort })
+            }, async (target, call) => {
+                const task = resolveAgentSpawn(target);
+                return controller.run({
+                    prompt: task.prompt,
+                    description: task.description ?? input.description,
+                    role: task.role ?? input.role,
+                    background: task.background ?? false,
+                    ...(input.parentSubagentId === undefined
+                        ? {}
+                        : { parentSubagentId: input.parentSubagentId }),
+                    ...(task.modelId === undefined ? {} : { modelId: task.modelId }),
+                    ...(task.reasoningEffort === undefined
+                        ? {}
+                        : { reasoningEffort: task.reasoningEffort })
+                }, {
+                    ...options,
+                    ...(task.turnSignal === undefined ? {} : { turnSignal: task.turnSignal }),
+                    ...(task.waitFor === undefined ? {} : { waitFor: task.waitFor }),
+                    signal: call.signal
+                });
+            });
+        },
+        output: (id, options) => wait({ ...options, agentId: id }),
+        outputAny: (options) => wait({ ...options }),
+        message: (id, message, options) => action('agent.message', { ...options, agentId: id, message }, (target, call) => controller.message(target.agentId, target.message, {
+            ...(target.delivery === undefined ? {} : { delivery: target.delivery }),
+            signal: call.signal
+        })),
+        cancel: (id) => action('agent.cancel', { agentId: id }, (target) => controller.cancel(target.agentId)),
+        listSessionResources: () => controller.listSessionResources(),
+        dispose: () => controller.dispose()
+    };
+}
+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.');
+            return invoke('agent.wait', input.agentId === undefined ? { ...input } : target(input));
+        },
+        message: async (input) => invoke('agent.message', target(input)),
+        cancel: async (input) => invoke('agent.cancel', target(input))
+    };
+}
+function invalid(message) {
+    return new MarAgentError('MAR_AGENT_EXTENSION_AGENT_INPUT_INVALID', message);
+}

package/dist/agent-core/extensions/contracts.d.ts

@@ -0,0 +1,260 @@
+import type { CoreModelRequest } from './model-request.js';
+import type { CorePromptInput, CorePromptResult } from './prompt-input.js';
+import type { CoreModelEvent } from './model-stream.js';
+import type { CorePromptComposition, CorePromptSectionInput } from './prompt-composition.js';
+import type { CoreModelsApi } from './models.js';
+import type { CoreAgentsApi, CoreAgentSpawnInput, CoreAgentWaitInput, CoreAgentMessageInput, CoreAgentTarget, CoreAgentSnapshot, CoreAgentSpawnResult, CoreAgentCompletion } from './agents.js';
+import type { CoreDataApi } from './data.js';
+import type { CoreMcpApi, CoreMcpConnectInput, CoreMcpConnectionInput, CoreMcpConnectionRef, CoreMcpCatalog, CoreMcpCompletion } from './mcp.js';
+import type { CoreFilesApi, CoreFileOperations, CoreFileCompletion } from './files.js';
+import type { CoreEnvironmentApi, CoreEnvironmentKey, CoreEnvironmentSet, CoreEnvironmentChange, CoreEnvironmentCompletion } from './environment.js';
+import type { CoreSettingsApi, CoreSettingsReadInput, CoreSettingsUpdate, CoreSettingsDescription, CoreSettingsSnapshot, CoreSettingsResult, CoreSettingsCompletion } from './settings.js';
+import type { CoreProcessesApi, CoreProcessInput, CoreProcessRunInput, CoreProcessHandle, CoreProcessResult, CoreProcessCompletion } from './processes.js';
+import type { CoreNetworkApi, CoreHttpRequest, CoreHttpResponse, CoreHttpCompletion } from './network.js';
+import type { CoreSessionApi, CoreAppendInput, CoreCompactInput, CoreSessionActionResult } from './session-input.js';
+import type { ToolCall, ToolExecutionResult } from '../tools/contracts.js';
+import type { CoreHookOptions, CoreInterceptor } from './hooks.js';
+import type { CoreOperationContext } from './operation.js';
+import type { CoreDisposer, CoreResourceRegistration, CoreResourceScope } from './resources.js';
+import type { CoreServiceRegistry } from './services.js';
+import type { CoreToolRef, CoreToolInvocation, CoreToolCheck, CoreToolSpec, CoreToolCompletion, CoreToolFailure } from './tools.js';
+export interface CoreDomainOperations extends CoreFileOperations {
+    'mcp.connect': {
+        input: CoreMcpConnectInput;
+        output: CoreMcpConnectionRef;
+    };
+    'mcp.catalog': {
+        input: CoreMcpConnectionInput;
+        output: CoreMcpCatalog;
+    };
+    'mcp.disconnect': {
+        input: CoreMcpConnectionInput;
+        output: void;
+    };
+    'agent.spawn': {
+        input: CoreAgentSpawnInput;
+        output: CoreAgentSpawnResult;
+    };
+    'agent.wait': {
+        input: CoreAgentWaitInput;
+        output: CoreAgentSnapshot;
+    };
+    'agent.message': {
+        input: CoreAgentMessageInput;
+        output: CoreAgentSnapshot;
+    };
+    'agent.cancel': {
+        input: CoreAgentTarget;
+        output: CoreAgentSnapshot;
+    };
+    'environment.get': {
+        input: CoreEnvironmentKey;
+        output: string | undefined;
+    };
+    'environment.set': {
+        input: CoreEnvironmentSet;
+        output: CoreEnvironmentChange;
+    };
+    'settings.describe': {
+        input: CoreSettingsReadInput;
+        output: CoreSettingsDescription;
+    };
+    'settings.read': {
+        input: CoreSettingsReadInput;
+        output: CoreSettingsSnapshot;
+    };
+    'settings.update': {
+        input: CoreSettingsUpdate;
+        output: CoreSettingsResult;
+    };
+    'process.spawn': {
+        input: CoreProcessInput;
+        output: CoreProcessHandle;
+    };
+    'process.run': {
+        input: CoreProcessRunInput;
+        output: CoreProcessResult;
+    };
+    'network.fetch': {
+        input: CoreHttpRequest;
+        output: CoreHttpResponse;
+    };
+    'prompt.compose': {
+        input: string;
+        output: string;
+    };
+    'prompt.submit': {
+        input: CorePromptInput;
+        output: CorePromptResult;
+    };
+    'prompt.sections': {
+        input: CorePromptComposition;
+        output: CorePromptComposition;
+    };
+    'prompt.section': {
+        input: CorePromptSectionInput;
+        output: string | null;
+    };
+    'model.request': {
+        input: CoreModelRequest;
+        output: CoreModelRequest;
+    };
+    'model.event': {
+        input: CoreModelEvent;
+        output: CoreModelEvent | undefined;
+    };
+    'tool.invoke': {
+        input: ToolCall;
+        output: ToolExecutionResult;
+    };
+    'session.append': {
+        input: CoreAppendInput;
+        output: CoreSessionActionResult;
+    };
+    'session.compact': {
+        input: CoreCompactInput;
+        output: CoreSessionActionResult;
+    };
+}
+export interface CoreDomainFacts {
+    'session.ending': {
+        readonly sessionId: string;
+        readonly reason: 'clear' | 'other';
+        readonly resumable: boolean;
+    };
+    'session.ready': {
+        readonly sessionId: string;
+    };
+    'model.event': CoreModelEvent;
+    'mcp.completed': CoreMcpCompletion;
+    'agent.completed': CoreAgentCompletion;
+    'environment.completed': CoreEnvironmentCompletion;
+    'settings.completed': CoreSettingsCompletion;
+    'process.completed': CoreProcessCompletion;
+    'network.completed': CoreHttpCompletion;
+    'files.completed': CoreFileCompletion;
+    'tool.completed': CoreToolCompletion;
+    'tool.failed': CoreToolFailure;
+    'tool.attempt.completed': CoreToolCompletion;
+    'tool.attempt.failed': CoreToolFailure;
+}
+export interface CoreHookRegistrar {
+    intercept<Key extends keyof CoreDomainOperations>(key: Key, handler: CoreInterceptor<CoreDomainOperations[Key]['input'], CoreDomainOperations[Key]['output']>, options?: CoreHookOptions): CoreResourceRegistration;
+    observe<Key extends keyof CoreDomainFacts>(key: Key, handler: (fact: CoreDomainFacts[Key], call: CoreOperationContext) => void | Promise<void>, options?: CoreHookOptions): CoreResourceRegistration;
+}
+export interface CoreCapabilitySnapshot {
+    has(id: string): boolean;
+    list(): readonly string[];
+}
+export interface CoreCommandSpec {
+    readonly name: string;
+    readonly description?: string;
+    readonly override?: 'replace';
+    handler(args: unknown, call: CoreOperationContext): unknown | Promise<unknown>;
+}
+export interface CorePromptSection {
+    readonly id: string;
+    readonly text: string;
+}
+export interface CoreAgentExtensionContext {
+    readonly data?: Pick<CoreDataApi, 'store'>;
+    readonly resources: CoreResourceScope;
+    readonly services: CoreServiceRegistry;
+    readonly capabilities: CoreCapabilitySnapshot;
+    readonly bindings: Readonly<Record<string, unknown>>;
+    readonly observability: {
+        log(message: string): void;
+    };
+}
+export interface CoreSessionExtensionContext extends CoreAgentExtensionContext {
+    readonly mcp?: CoreMcpApi;
+    readonly agents?: CoreAgentsApi;
+    readonly environment?: CoreEnvironmentApi;
+    readonly settings?: CoreSettingsApi;
+    readonly processes?: CoreProcessesApi;
+    readonly network?: CoreNetworkApi;
+    readonly files?: CoreFilesApi;
+    readonly sessionId: string;
+    readonly models?: CoreModelsApi;
+    readonly data: CoreDataApi;
+    readonly session?: CoreSessionApi;
+    readonly hooks: CoreHookRegistrar;
+    readonly tools: {
+        register(spec: CoreToolSpec): CoreResourceRegistration;
+        catalog(): readonly CoreToolRef[];
+        check(call: CoreToolInvocation): Promise<CoreToolCheck>;
+        invoke(call: CoreToolInvocation): Promise<ToolExecutionResult>;
+    };
+    readonly commands: {
+        register(spec: CoreCommandSpec): CoreResourceRegistration;
+        list(): readonly Pick<CoreCommandSpec, 'name' | 'description'>[];
+        run(input: {
+            readonly name: string;
+            readonly args?: unknown;
+        }): Promise<unknown>;
+    };
+    readonly prompts: {
+        register(section: CorePromptSection): CoreResourceRegistration;
+        sections(): readonly CorePromptSection[];
+        compose(system: string): Promise<string>;
+        composeSections(input: CorePromptComposition): Promise<CorePromptComposition>;
+        composeDefault(facts?: import('./prompt-composition.js').CorePromptFacts): Promise<CorePromptComposition>;
+    };
+    readonly clock: {
+        now(): number;
+        sleep(input: {
+            readonly durationMs: number;
+            readonly signal?: AbortSignal;
+        }): Promise<void>;
+        after(durationMs: number, callback: (call: CoreOperationContext) => void | Promise<void>): CoreResourceRegistration;
+        every(durationMs: number, callback: (call: CoreOperationContext) => void | Promise<void>): CoreResourceRegistration;
+    };
+}
+export interface CoreServiceDeclaration {
+    readonly key: {
+        readonly id: string;
+        readonly scope: 'agent' | 'session';
+    };
+    readonly intent?: 'provide' | 'replace' | 'wrap';
+}
+export interface CoreServiceDependency {
+    readonly key: {
+        readonly id: string;
+        readonly scope: 'agent' | 'session';
+    };
+    readonly optional?: boolean;
+}
+export interface CoreRuntimeExtension {
+    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 CoreServiceDeclaration[];
+    readonly serviceDependencies?: readonly CoreServiceDependency[];
+    readonly failurePolicy?: 'disable-extension' | 'fail-composition';
+    setup?(context: CoreAgentExtensionContext): void | CoreDisposer | Promise<void | CoreDisposer>;
+    attachSession?(context: CoreSessionExtensionContext): void | CoreDisposer | Promise<void | CoreDisposer>;
+}
+export interface CoreExtensionSnapshot {
+    readonly revision: string;
+    readonly extensions: readonly CoreRuntimeExtension[];
+}
+export interface CoreExtensionSource {
+    resolve(input: {
+        readonly signal: AbortSignal;
+    }): Promise<CoreExtensionSnapshot>;
+}
+export interface CoreExtensionDiagnostic {
+    readonly code: string;
+    readonly extensionId?: string;
+    readonly sessionId?: string;
+    readonly revision?: string;
+    readonly operationId?: string;
+    readonly message?: string;
+}

package/dist/agent-core/extensions/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-core/extensions/data.d.ts

@@ -0,0 +1,84 @@
+import type { CoreCallbackRunner, CoreOperationContext } from './operation.js';
+import type { CoreResourceRegistration } from './resources.js';
+import { ExtensionResourceScope } from './resources.js';
+export type CoreJsonValue = null | boolean | number | string | readonly CoreJsonValue[] | {
+    readonly [key: string]: CoreJsonValue;
+};
+export interface CoreCheckpoint {
+    readonly revision: number;
+    readonly value?: CoreJsonValue;
+}
+export interface CoreCheckpointApi {
+    get(input: {
+        readonly key: string;
+    }): Promise<CoreCheckpoint>;
+    set(input: {
+        readonly key: string;
+        readonly value: CoreJsonValue;
+        readonly expectedRevision?: number;
+    }): Promise<CoreCheckpoint>;
+    delete(input: {
+        readonly key: string;
+        readonly expectedRevision?: number;
+    }): Promise<CoreCheckpoint>;
+}
+export interface CoreCheckpointBackend {
+    read(extensionId: string, key: string, call: CoreOperationContext): Promise<CoreCheckpoint>;
+    write(extensionId: string, key: string, value: CoreJsonValue | undefined, expectedRevision: number | undefined, call: CoreOperationContext): Promise<CoreCheckpoint>;
+}
+export interface CoreStateChange {
+    readonly key: string;
+    readonly revision: number;
+    readonly value?: CoreJsonValue;
+}
+export interface CoreStateApi {
+    read(key: string): Promise<CoreJsonValue | undefined>;
+    write(key: string, value: CoreJsonValue): Promise<number>;
+    delete(key: string): Promise<number>;
+    watch(handler: (change: CoreStateChange, call: CoreOperationContext) => void | Promise<void>): CoreResourceRegistration;
+}
+export interface CoreDataApi {
+    readonly store?: CoreStoreApi;
+    readonly state: CoreStateApi;
+    readonly checkpoint?: CoreCheckpointApi;
+}
+export interface CoreStoreCommit {
+    readonly expectedRevision?: number;
+    readonly writes: readonly {
+        readonly key: string;
+        readonly value?: CoreJsonValue;
+    }[];
+}
+export interface CoreStoreApi {
+    get(input: {
+        readonly key: string;
+    }): Promise<CoreCheckpoint>;
+    keys(): Promise<{
+        readonly revision: number;
+        readonly keys: readonly string[];
+    }>;
+    set(input: {
+        readonly key: string;
+        readonly value: CoreJsonValue;
+        readonly expectedRevision?: number;
+    }): Promise<CoreCheckpoint>;
+    delete(input: {
+        readonly key: string;
+        readonly expectedRevision?: number;
+    }): Promise<CoreCheckpoint>;
+    commit(input: CoreStoreCommit): Promise<{
+        readonly revision: number;
+    }>;
+}
+export declare function cloneCoreJson(value: unknown): CoreJsonValue;
+/** 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: CoreCallbackRunner;
+    constructor(scope: ExtensionResourceScope, diagnose: () => void, callback?: CoreCallbackRunner);
+    read(key: string): CoreJsonValue | undefined;
+    write(key: string, value: CoreJsonValue | undefined, call: CoreOperationContext): Promise<number>;
+    watch(handler: (change: CoreStateChange, call: CoreOperationContext) => void | Promise<void>): CoreResourceRegistration;
+}

package/dist/agent-core/extensions/data.js

@@ -0,0 +1,83 @@
+import { MarAgentError } from '../error.js';
+export function cloneCoreJson(value) {
+    try {
+        const ancestors = new Set();
+        const copy = (value) => {
+            if (value === null || typeof value === 'string' || typeof value === 'boolean')
+                return value;
+            if (typeof value === 'number' && Number.isFinite(value))
+                return value;
+            if (typeof value !== 'object' || !value || ancestors.has(value))
+                throw new Error();
+            ancestors.add(value);
+            try {
+                if (Array.isArray(value))
+                    return Array.from(value, copy);
+                if (Object.prototype.toString.call(value) !== '[object Object]')
+                    throw new Error();
+                // Define own JSON keys, including __proto__, without assigning to a prototype setter.
+                return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copy(item)]));
+            }
+            finally {
+                ancestors.delete(value);
+            }
+        };
+        return copy(value);
+    }
+    catch {
+        throw new MarAgentError('MAR_AGENT_EXTENSION_DATA_INVALID', 'Extension data must be serializable JSON.');
+    }
+}
+/** 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 MarAgentError('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;
+    }
+}