@myagentroam/agent 0.11.33 → 0.11.34

package/dist/extensions/resources.js

@@ -0,0 +1,221 @@
+import { AgentError } from '../error.js';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+/** An instance's managed resources, not an OS sandbox or a process-wide resource owner. */
+export class ExtensionResourceScope {
+    instanceId = randomUUID();
+    static #initialization = new AsyncLocalStorage();
+    static get initializing() {
+        return this.#initialization.getStore()?.active === true;
+    }
+    static async initialize(run) {
+        const frame = { active: true };
+        return this.#initialization.run(frame, async () => {
+            try {
+                return await run();
+            }
+            finally {
+                frame.active = false;
+            }
+        });
+    }
+    #state = 'STAGED';
+    #controller = new AbortController();
+    #resources = [];
+    #operations = new Set();
+    #activators = new Set();
+    #disposal;
+    get state() {
+        return this.#state;
+    }
+    get signal() {
+        return this.#controller.signal;
+    }
+    activate() {
+        this.#assertOpen();
+        if (this.#state === 'ACTIVE')
+            return;
+        this.#state = 'ACTIVE';
+        for (const activate of this.#activators)
+            activate();
+        this.#activators.clear();
+    }
+    effect(acquire) {
+        this.#assertOpen();
+        const acquired = Promise.resolve()
+            .then(acquire)
+            .then((release) => {
+            if (typeof release !== 'function')
+                throw new AgentError('MAR_AGENT_EXTENSION_RESOURCE_INVALID', 'Resource acquisition must return a disposer.');
+            return release;
+        });
+        let releasing;
+        const disposalFrame = new AsyncLocalStorage();
+        const registration = {
+            ready: acquired.then(() => undefined),
+            dispose: () => {
+                if (disposalFrame.getStore())
+                    return Promise.resolve();
+                releasing ??= acquired.then(async (release) => {
+                    if (typeof release !== 'function')
+                        throw new AgentError('MAR_AGENT_EXTENSION_RESOURCE_INVALID', 'Resource acquisition must return a disposer.');
+                    await disposalFrame.run(true, release);
+                }, () => undefined);
+                return releasing;
+            }
+        };
+        // Acquisition errors remain observable through ready, without unhandled rejection noise.
+        void registration.ready.catch(() => undefined);
+        this.#resources.push(registration);
+        return registration;
+    }
+    async run(operation, parent) {
+        if (this.#state !== 'ACTIVE' &&
+            !(this.#state === 'STAGED' && ExtensionResourceScope.initializing))
+            throw new AgentError('MAR_AGENT_EXTENSION_RETIRED', 'Extension is not active.');
+        const signal = parent ? AbortSignal.any([this.signal, parent]) : this.signal;
+        signal.throwIfAborted();
+        const running = Promise.resolve().then(() => {
+            signal.throwIfAborted();
+            return operation(signal);
+        });
+        this.#operations.add(running);
+        try {
+            const result = await running;
+            signal.throwIfAborted();
+            return result;
+        }
+        finally {
+            this.#operations.delete(running);
+        }
+    }
+    after(durationMs, callback, onError = () => { }) {
+        return this.#timer(durationMs, false, callback, onError);
+    }
+    every(durationMs, callback, onError = () => { }) {
+        return this.#timer(durationMs, true, callback, onError);
+    }
+    async sleep(durationMs, parent) {
+        if (!Number.isFinite(durationMs) || durationMs < 0)
+            throw new AgentError('MAR_AGENT_EXTENSION_TIMER_INVALID', 'Sleep duration must be finite and non-negative.');
+        return this.run(async (signal) => {
+            const deadline = performance.now() + durationMs;
+            let timer;
+            let abort;
+            try {
+                await new Promise((resolve, reject) => {
+                    abort = () => reject(signal.reason);
+                    signal.addEventListener('abort', abort, { once: true });
+                    const schedule = () => {
+                        const remaining = deadline - performance.now();
+                        if (remaining <= 0) {
+                            resolve();
+                            return;
+                        }
+                        timer = setTimeout(schedule, Math.min(remaining, 2_147_483_647));
+                    };
+                    schedule();
+                });
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+                signal.removeEventListener('abort', abort);
+            }
+        }, parent);
+    }
+    /** Wait for acquisitions added by setup before publishing any callbacks. */
+    async ready() {
+        let count = -1;
+        while (count !== this.#resources.length) {
+            count = this.#resources.length;
+            await Promise.all(this.#resources.map((resource) => resource.ready));
+        }
+    }
+    retire() {
+        if (this.#state === 'DISPOSED')
+            return;
+        this.#state = 'RETIRING';
+        this.#controller.abort();
+        this.#activators.clear();
+    }
+    #timer(durationMs, repeat, callback, onError) {
+        this.#assertOpen();
+        if (!Number.isFinite(durationMs) || durationMs < 0 || (repeat && durationMs === 0))
+            throw new AgentError('MAR_AGENT_EXTENSION_TIMER_INVALID', 'Timer duration must be finite and non-negative; repeating timers must be positive.');
+        let stopped = false;
+        let timer;
+        const timerController = new AbortController();
+        const callbacks = new AsyncLocalStorage();
+        let running;
+        const schedule = () => {
+            if (stopped || this.#state !== 'ACTIVE')
+                return;
+            const due = performance.now() + durationMs;
+            const arm = () => {
+                timer = setTimeout(() => {
+                    timer = undefined;
+                    if (stopped || this.#state !== 'ACTIVE')
+                        return;
+                    if (performance.now() < due) {
+                        arm();
+                        return;
+                    }
+                    running = this.run(async (signal) => {
+                        await callbacks.run(true, () => callback(signal));
+                    }, timerController.signal)
+                        .catch((error) => {
+                        if (!this.signal.aborted && !timerController.signal.aborted)
+                            onError(error);
+                    })
+                        .finally(() => {
+                        if (repeat)
+                            schedule();
+                    });
+                    void running.catch(() => undefined);
+                }, Math.min(Math.max(0, due - performance.now()), 2_147_483_647));
+                timer.unref?.();
+            };
+            arm();
+        };
+        const registration = this.effect(() => async () => {
+            stopped = true;
+            this.#activators.delete(schedule);
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timerController.abort();
+            if (!callbacks.getStore())
+                await running;
+        });
+        if (this.#state === 'ACTIVE')
+            schedule();
+        else
+            this.#activators.add(schedule);
+        return registration;
+    }
+    dispose() {
+        if (this.#disposal)
+            return this.#disposal;
+        this.retire();
+        this.#disposal = Promise.resolve().then(async () => {
+            await Promise.allSettled([...this.#operations]);
+            let failures = 0;
+            for (const resource of [...this.#resources].reverse()) {
+                try {
+                    await resource.dispose();
+                }
+                catch {
+                    failures++;
+                }
+            }
+            if (failures)
+                throw new AgentError('MAR_AGENT_EXTENSION_CLEANUP_FAILED', 'Extension resource cleanup failed.', { details: { failures } });
+            this.#state = 'DISPOSED';
+        });
+        return this.#disposal;
+    }
+    #assertOpen() {
+        if (this.#state === 'RETIRING' || this.#state === 'DISPOSED')
+            throw new AgentError('MAR_AGENT_EXTENSION_RETIRED', 'Extension resource scope is retired.');
+    }
+}

package/dist/extensions/services.d.ts

@@ -0,0 +1,31 @@
+import type { ExtensionResourceScope } from './resources.js';
+export interface ExtensionServiceKey<T> {
+    readonly id: string;
+    readonly scope: 'agent' | 'session';
+    /** Compile-time service contract; never examined at runtime. */
+    readonly contract?: (implementation: T) => T;
+}
+export interface ExtensionServiceRegistry {
+    provide<T>(key: ExtensionServiceKey<T>, implementation: T): void;
+    replace<T>(key: ExtensionServiceKey<T>, implementation: T): void;
+    wrap<T>(key: ExtensionServiceKey<T>, factory: (below: T) => T): void;
+    consume<T>(key: ExtensionServiceKey<T>, options?: {
+        readonly optional?: boolean;
+    }): T | undefined;
+}
+/** A composition's typed values, not a dynamic IoC container or dependency solver. */
+export declare class ExtensionServices {
+    #private;
+    readonly scope: 'agent' | 'session';
+    readonly parent?: ExtensionServices | undefined;
+    constructor(scope: 'agent' | 'session', parent?: ExtensionServices | undefined);
+    has(key: {
+        readonly id: string;
+        readonly scope: 'agent' | 'session';
+    }): boolean;
+    hasOwned(key: {
+        readonly id: string;
+        readonly scope: 'agent' | 'session';
+    }, owner: ExtensionResourceScope): boolean;
+    bind(owner: ExtensionResourceScope): ExtensionServiceRegistry;
+}

package/dist/extensions/services.js

@@ -0,0 +1,61 @@
+import { AgentError } from '../error.js';
+/** A composition's typed values, not a dynamic IoC container or dependency solver. */
+export class ExtensionServices {
+    scope;
+    parent;
+    #entries = new Map();
+    constructor(scope, parent) {
+        this.scope = scope;
+        this.parent = parent;
+    }
+    has(key) {
+        return this.#find(key) !== undefined;
+    }
+    hasOwned(key, owner) {
+        return (key.scope === this.scope &&
+            (this.#entries.get(key.id)?.some((entry) => entry.owner === owner) ?? false));
+    }
+    bind(owner) {
+        const consume = (key, options) => {
+            const entry = this.#find(key);
+            if (!entry && !options?.optional)
+                throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Required service is unavailable.');
+            return entry?.value;
+        };
+        const publish = (key, value, replace) => {
+            if (key.scope !== this.scope)
+                throw new AgentError('MAR_AGENT_EXTENSION_SERVICE_SCOPE', 'Service publication uses the wrong scope.');
+            if (!key.id.trim())
+                throw new AgentError('MAR_AGENT_EXTENSION_SERVICE_INVALID', 'Service key is empty.');
+            const entries = this.#entries.get(key.id) ?? [];
+            if (entries.length && !replace)
+                throw new AgentError('MAR_AGENT_EXTENSION_SERVICE_CONFLICT', 'Service is already provided.');
+            if (!entries.length && replace)
+                throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Service replacement has no lower provider.');
+            const entry = { value, owner };
+            owner.effect(() => () => {
+                const index = entries.indexOf(entry);
+                if (index !== -1)
+                    entries.splice(index, 1);
+            });
+            entries.push(entry);
+            this.#entries.set(key.id, entries);
+        };
+        return {
+            provide: (key, value) => publish(key, value, false),
+            replace: (key, value) => publish(key, value, true),
+            wrap: (key, factory) => {
+                const entry = this.#find(key);
+                if (!entry)
+                    throw new AgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Service wrapper has no lower provider.');
+                publish(key, factory(entry.value), true);
+            },
+            consume
+        };
+    }
+    #find(key) {
+        if (key.scope === this.scope)
+            return this.#entries.get(key.id)?.at(-1);
+        return this.parent ? this.parent.#find(key) : undefined;
+    }
+}

package/dist/extensions/session-api.d.ts

@@ -0,0 +1,6 @@
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationRunner, ExtensionOperations } from './operation.js';
+import { type DomainPromptInputOperations, type DomainPromptInputFacts } from './prompt-input.js';
+import type { ExtensionResourceScope } from './resources.js';
+import type { ExtensionSessionApi, ExtensionSessionBackend, DomainSessionOperations, DomainSessionFacts } from './session-input.js';
+export declare function bindCoreSession(backend: ExtensionSessionBackend, scope: ExtensionResourceScope, run: ExtensionOperationRunner, operations: Pick<ExtensionOperations, 'continue'>, hooks: Pick<ExtensionHooks<DomainSessionOperations & DomainPromptInputOperations, DomainSessionFacts & DomainPromptInputFacts>, 'invoke' | 'emit'>): ExtensionSessionApi;

package/dist/extensions/session-api.js

@@ -0,0 +1,52 @@
+import { AgentError } from '../error.js';
+import { invokeCorePromptSubmission } from './prompt-input.js';
+export function bindCoreSession(backend, scope, run, operations, hooks) {
+    const sessionAction = (request, call, leaf) => operations.continue(call, async () => {
+        if (request.kind === 'append')
+            return hooks.invoke('session.append', request.input, call, (input, effective) => leaf({ kind: 'append', input }, effective));
+        return leaf(request, call);
+    });
+    return {
+        captureRequest: (input = {}) => run((call) => backend.captureRequest(call, input)),
+        inspect: () => run((call) => backend.inspect(call)),
+        describe: () => run((call) => {
+            if (!backend.describe)
+                throw new AgentError('MAR_AGENT_SESSION_INPUT_UNAVAILABLE', 'Session metadata is unavailable.');
+            return backend.describe(call);
+        }),
+        messages: (input = {}) => run((call) => backend.messages(input, call)),
+        append: (input) => run((call) => backend.enqueue({ kind: 'append', input }, call, sessionAction)),
+        submit: (input) => run(async (call) => {
+            const { queueSignal, ...request } = input;
+            if (queueSignal !== undefined && !(queueSignal instanceof AbortSignal))
+                throw new AgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Session input lifetime must be an AbortSignal.');
+            // Admission uses the caller's cancellation; accepted work may outlive it.
+            call.signal.throwIfAborted();
+            const accepted = queueSignal
+                ? Object.freeze({
+                    ...call,
+                    signal: AbortSignal.any([scope.signal, queueSignal])
+                })
+                : call;
+            let receipt;
+            const admission = await invokeCorePromptSubmission(hooks, request, call, async (content, effective) => {
+                effective.signal.throwIfAborted();
+                receipt = await backend.enqueue({
+                    kind: 'submit',
+                    input: {
+                        ...content,
+                        ...(request.provenance === undefined ? {} : { provenance: request.provenance }),
+                        ...(request.modelAttribution === undefined
+                            ? {}
+                            : { modelAttribution: request.modelAttribution }),
+                        ...(request.delivery === undefined ? {} : { delivery: request.delivery }),
+                        ...(request.waitFor === undefined ? {} : { waitFor: request.waitFor })
+                    }
+                }, queueSignal ? accepted : effective, sessionAction);
+                return {};
+            });
+            return receipt ?? backend.handled(request, call, admission.result.value);
+        }),
+        compact: (input = {}) => run((call) => backend.enqueue({ kind: 'compact', input }, call, sessionAction))
+    };
+}

package/dist/extensions/session-input.d.ts

@@ -0,0 +1,184 @@
+import type { ExtensionOperationContext } from './operation.js';
+import type { SessionSource } from '../session/types.js';
+import { type ExtensionPromptInput } from './prompt-input.js';
+import type { ExtensionRequestSnapshot } from './model-request.js';
+import type { ExtensionPromptComposition, ExtensionPromptFacts } from './prompt-composition.js';
+import type { ExtensionSessionMessages, ExtensionSessionMessagesInput } from './session-messages.js';
+export type { ExtensionSessionMessages, ExtensionSessionMessagesInput, ExtensionSessionMessage } from './session-messages.js';
+export interface ExtensionAppendInput {
+    readonly content: string;
+    readonly textBlocks?: readonly {
+        readonly text: string;
+    }[];
+    readonly visibility?: 'model' | 'transcript';
+    /** Immediate records commit without scheduling an input or waking a model round. */
+    readonly delivery?: 'boundary' | 'immediate';
+    readonly attribution?: string;
+}
+export interface ExtensionInputSource {
+    readonly operationId: string;
+    readonly actor?: ExtensionOperationContext['actor'];
+    readonly extensionId?: string;
+    readonly ownerInstanceId?: string;
+    readonly provenance?: string;
+    /** Presentation intent only; it never changes the actual author or authority. */
+    readonly modelAttribution?: 'none';
+}
+export interface ExtensionSubmitInput extends ExtensionPromptInput {
+    readonly provenance?: string;
+    readonly modelAttribution?: 'none';
+    readonly delivery?: 'boundary' | 'idle';
+    readonly waitFor?: 'admission' | 'start' | 'commit';
+    /** Explicit lifetime after admission; the Extension owner remains authoritative. */
+    readonly queueSignal?: AbortSignal;
+}
+export interface ExtensionCompactInput {
+    readonly focus?: string;
+    readonly async?: boolean;
+}
+export type ExtensionSessionRequest = {
+    readonly kind: 'append';
+    readonly input: ExtensionAppendInput;
+} | {
+    readonly kind: 'submit';
+    readonly input: ExtensionSubmitInput;
+} | {
+    readonly kind: 'compact';
+    readonly input: ExtensionCompactInput;
+};
+export type ExtensionSessionOperationStatus = 'queued' | 'accepted' | 'in-progress' | 'committed' | 'completed' | 'handled' | 'cancelled' | 'failed';
+export interface ExtensionSessionReceipt {
+    /** The actual committed record, absent before the writer has completed. */
+    readonly recordId?: string;
+    readonly operationId: string;
+    readonly sequence: number;
+    readonly kind: ExtensionSessionRequest['kind'];
+    readonly status: ExtensionSessionOperationStatus;
+    readonly executionId?: string;
+    readonly errorCode?: string;
+    readonly changed?: boolean;
+    readonly handledValue?: unknown;
+    readonly ownerInstanceId?: string;
+    readonly extensionId?: string;
+    readonly parentOperationId?: string;
+}
+export interface ExtensionSessionInspection {
+    readonly sessionId: string;
+    readonly epoch: number;
+    readonly activeExecutionId?: string;
+    readonly operations: readonly ExtensionSessionReceipt[];
+}
+export interface ExtensionSessionDescription {
+    readonly sessionId: string;
+    readonly source?: SessionSource;
+    readonly cwd?: string;
+    readonly root?: string;
+    readonly modelId: string;
+    readonly modelName: string;
+    readonly startedAt: number;
+    readonly userTurns: number;
+}
+export interface ExtensionSessionApi {
+    captureRequest(input?: {
+        readonly completed?: boolean;
+    }): Promise<ExtensionRequestSnapshot | undefined>;
+    inspect(): Promise<ExtensionSessionInspection>;
+    describe(): Promise<ExtensionSessionDescription>;
+    messages(input?: ExtensionSessionMessagesInput): Promise<ExtensionSessionMessages>;
+    append(input: ExtensionAppendInput): Promise<ExtensionSessionReceipt>;
+    submit(input: ExtensionSubmitInput): Promise<ExtensionSessionReceipt>;
+    compact(input?: ExtensionCompactInput): Promise<ExtensionSessionReceipt>;
+}
+export interface ExtensionSessionActionResult {
+    /** The physical boundary deliberately skipped a record before any commit. */
+    readonly handled?: true;
+    readonly changed: boolean;
+    readonly recordId?: string;
+    readonly modelChanged?: boolean;
+    readonly executionId?: string;
+}
+export type ExtensionSessionAction = (request: ExtensionSessionRequest, call: ExtensionOperationContext, leaf: (request: ExtensionSessionRequest, call: ExtensionOperationContext) => Promise<ExtensionSessionActionResult>) => Promise<ExtensionSessionActionResult>;
+export interface ExtensionSessionBackend {
+    describe?(call: ExtensionOperationContext): Promise<ExtensionSessionDescription>;
+    composePrompt?(facts: ExtensionPromptFacts, call: ExtensionOperationContext): Promise<ExtensionPromptComposition>;
+    captureRequest(call: ExtensionOperationContext, input?: {
+        readonly completed?: boolean;
+    }): Promise<ExtensionRequestSnapshot | undefined>;
+    inspect(call: ExtensionOperationContext): Promise<ExtensionSessionInspection>;
+    messages(input: ExtensionSessionMessagesInput, call: ExtensionOperationContext): Promise<ExtensionSessionMessages>;
+    enqueue(request: ExtensionSessionRequest, call: ExtensionOperationContext, action: ExtensionSessionAction): Promise<ExtensionSessionReceipt>;
+    own(instanceId: string): () => Promise<void>;
+    handled(input: ExtensionSubmitInput, call: ExtensionOperationContext, value?: unknown): ExtensionSessionReceipt;
+}
+export interface SessionInputEntry {
+    /** SDK-owned admission barrier, never accepted from Extension input. */
+    nativeSteer?: {
+        readonly ready: Promise<void>;
+        recordId?: string;
+        restored?: true;
+    };
+    readonly request: ExtensionSessionRequest;
+    readonly source: ExtensionOperationContext;
+    readonly action: ExtensionSessionAction;
+    receipt: ExtensionSessionReceipt;
+    readonly parentMessage?: unknown;
+    readonly started: Promise<void>;
+    start(): void;
+    readonly terminal: Promise<void>;
+    complete(): void;
+}
+/** Internal writer evidence survives errors after commit, without settling the operation early. */
+export declare function recordSessionInputCommit(entry: SessionInputEntry, outcome: ExtensionSessionActionResult): void;
+/** One Session FIFO shared by native writes and the existing parent mailbox. No model loop. */
+export declare class SessionInputCoordinator {
+    #private;
+    readonly diagnose: (receipt: ExtensionSessionReceipt) => void;
+    constructor(diagnose?: (receipt: ExtensionSessionReceipt) => void);
+    get hasPending(): boolean;
+    get boundarySize(): number;
+    get hasIdleBarrier(): boolean;
+    restoreSteer(recordId: string, text: string, source: ExtensionOperationContext): void;
+    get hasBoundaryPending(): boolean;
+    get executing(): boolean;
+    get hasBoundaryCompactPending(): boolean;
+    currentCompact(): ExtensionSessionReceipt | undefined;
+    inspect(): readonly ExtensionSessionReceipt[];
+    performAppend(input: ExtensionAppendInput, call: ExtensionOperationContext, action: ExtensionSessionAction, leaf: (entry: SessionInputEntry, request: ExtensionSessionRequest, call: ExtensionOperationContext) => Promise<ExtensionSessionActionResult>): Promise<ExtensionSessionReceipt>;
+    /** SDK manual/automatic compaction shares the same active receipt as queued compaction. */
+    recordCompactCommit(outcome: ExtensionSessionActionResult): void;
+    performCompact(input: ExtensionCompactInput, call: ExtensionOperationContext, action: (commit: (outcome: ExtensionSessionActionResult) => void) => Promise<ExtensionSessionActionResult>): Promise<ExtensionSessionActionResult>;
+    accept(request: ExtensionSessionRequest, source: ExtensionOperationContext, action: ExtensionSessionAction, status: 'accepted' | 'queued', parentMessage?: unknown): SessionInputEntry;
+    handled(input: ExtensionSubmitInput, call: ExtensionOperationContext, value?: unknown): ExtensionSessionReceipt;
+    drain(leaf: (entry: SessionInputEntry, request: ExtensionSessionRequest, call: ExtensionOperationContext) => Promise<ExtensionSessionActionResult>, execution?: {
+        readonly executionId: string;
+        readonly turnId: string;
+        readonly signal: AbortSignal;
+        /** An already authorized idle launch restores older durable input before its own prompt. */
+        readonly restoring?: true;
+    }, limit?: number): Promise<boolean>;
+    idle(): Promise<void>;
+    retire(instanceId?: string): Promise<void>;
+    startExecution(entry: SessionInputEntry, executionId: string): void;
+    settleExecution(executionId: string, status: 'completed' | 'failed' | 'cancelled'): void;
+}
+export declare function validateCoreSessionRequest(request: ExtensionSessionRequest): void;
+export interface DomainSessionOperations {
+    'session.append': {
+        input: ExtensionAppendInput;
+        output: ExtensionSessionActionResult;
+    };
+    'session.compact': {
+        input: ExtensionCompactInput;
+        output: ExtensionSessionActionResult;
+    };
+}
+export interface DomainSessionFacts {
+    'session.ending': {
+        readonly sessionId: string;
+        readonly reason: 'clear' | 'other';
+        readonly resumable: boolean;
+    };
+    'session.ready': {
+        readonly sessionId: string;
+    };
+}