@myagentroam/agent 0.9.158 → 0.9.160

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

@@ -0,0 +1,221 @@
+import { MarAgentError } 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 MarAgentError('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 MarAgentError('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 MarAgentError('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 MarAgentError('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 MarAgentError('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 MarAgentError('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 MarAgentError('MAR_AGENT_EXTENSION_RETIRED', 'Extension resource scope is retired.');
+    }
+}

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

@@ -0,0 +1,31 @@
+import type { CoreResourceScope } from './resources.js';
+export interface CoreServiceKey<T> {
+    readonly id: string;
+    readonly scope: 'agent' | 'session';
+    /** Compile-time service contract; never examined at runtime. */
+    readonly contract?: (implementation: T) => T;
+}
+export interface CoreServiceRegistry {
+    provide<T>(key: CoreServiceKey<T>, implementation: T): void;
+    replace<T>(key: CoreServiceKey<T>, implementation: T): void;
+    wrap<T>(key: CoreServiceKey<T>, factory: (below: T) => T): void;
+    consume<T>(key: CoreServiceKey<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: CoreResourceScope): boolean;
+    bind(owner: CoreResourceScope): CoreServiceRegistry;
+}

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

@@ -0,0 +1,61 @@
+import { MarAgentError } 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 MarAgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Required service is unavailable.');
+            return entry?.value;
+        };
+        const publish = (key, value, replace) => {
+            if (key.scope !== this.scope)
+                throw new MarAgentError('MAR_AGENT_EXTENSION_SERVICE_SCOPE', 'Service publication uses the wrong scope.');
+            if (!key.id.trim())
+                throw new MarAgentError('MAR_AGENT_EXTENSION_SERVICE_INVALID', 'Service key is empty.');
+            const entries = this.#entries.get(key.id) ?? [];
+            if (entries.length && !replace)
+                throw new MarAgentError('MAR_AGENT_EXTENSION_SERVICE_CONFLICT', 'Service is already provided.');
+            if (!entries.length && replace)
+                throw new MarAgentError('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 MarAgentError('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/agent-core/extensions/session-input.d.ts

@@ -0,0 +1,151 @@
+import type { CoreOperationContext } from './operation.js';
+import type { SessionSource } from '../session/types.js';
+import { type CorePromptInput } from './prompt-input.js';
+import type { CoreRequestSnapshot } from './model-request.js';
+import type { CorePromptComposition, CorePromptFacts } from './prompt-composition.js';
+import type { CoreSessionMessages, CoreSessionMessagesInput } from './session-messages.js';
+export type { CoreSessionMessages, CoreSessionMessagesInput, CoreSessionMessage } from './session-messages.js';
+export interface CoreAppendInput {
+    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 CoreInputSource {
+    readonly operationId: string;
+    readonly actor?: CoreOperationContext['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 CoreSubmitInput extends CorePromptInput {
+    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 CoreCompactInput {
+    readonly focus?: string;
+}
+export type CoreSessionRequest = {
+    readonly kind: 'append';
+    readonly input: CoreAppendInput;
+} | {
+    readonly kind: 'submit';
+    readonly input: CoreSubmitInput;
+} | {
+    readonly kind: 'compact';
+    readonly input: CoreCompactInput;
+};
+export type CoreSessionOperationStatus = 'queued' | 'accepted' | 'in-progress' | 'committed' | 'completed' | 'handled' | 'cancelled' | 'failed';
+export interface CoreSessionReceipt {
+    /** The actual committed record, absent before the writer has completed. */
+    readonly recordId?: string;
+    readonly operationId: string;
+    readonly sequence: number;
+    readonly kind: CoreSessionRequest['kind'];
+    readonly status: CoreSessionOperationStatus;
+    readonly executionId?: string;
+    readonly errorCode?: string;
+    readonly changed?: boolean;
+    readonly handledValue?: unknown;
+    readonly ownerInstanceId?: string;
+    readonly extensionId?: string;
+    readonly parentOperationId?: string;
+}
+export interface CoreSessionInspection {
+    readonly sessionId: string;
+    readonly epoch: number;
+    readonly activeExecutionId?: string;
+    readonly operations: readonly CoreSessionReceipt[];
+}
+export interface CoreSessionDescription {
+    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 CoreSessionApi {
+    captureRequest(input?: {
+        readonly completed?: boolean;
+    }): Promise<CoreRequestSnapshot | undefined>;
+    inspect(): Promise<CoreSessionInspection>;
+    describe(): Promise<CoreSessionDescription>;
+    messages(input?: CoreSessionMessagesInput): Promise<CoreSessionMessages>;
+    append(input: CoreAppendInput): Promise<CoreSessionReceipt>;
+    submit(input: CoreSubmitInput): Promise<CoreSessionReceipt>;
+    compact(input?: CoreCompactInput): Promise<CoreSessionReceipt>;
+}
+export interface CoreSessionActionResult {
+    /** 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 CoreSessionAction = (request: CoreSessionRequest, call: CoreOperationContext, leaf: (request: CoreSessionRequest, call: CoreOperationContext) => Promise<CoreSessionActionResult>) => Promise<CoreSessionActionResult>;
+export interface CoreSessionBackend {
+    describe?(call: CoreOperationContext): Promise<CoreSessionDescription>;
+    composePrompt?(facts: CorePromptFacts, call: CoreOperationContext): Promise<CorePromptComposition>;
+    captureRequest(call: CoreOperationContext, input?: {
+        readonly completed?: boolean;
+    }): Promise<CoreRequestSnapshot | undefined>;
+    inspect(call: CoreOperationContext): Promise<CoreSessionInspection>;
+    messages(input: CoreSessionMessagesInput, call: CoreOperationContext): Promise<CoreSessionMessages>;
+    enqueue(request: CoreSessionRequest, call: CoreOperationContext, action: CoreSessionAction): Promise<CoreSessionReceipt>;
+    own(instanceId: string): () => Promise<void>;
+    handled(input: CoreSubmitInput, call: CoreOperationContext, value?: unknown): CoreSessionReceipt;
+}
+export interface SessionInputEntry {
+    readonly request: CoreSessionRequest;
+    readonly source: CoreOperationContext;
+    readonly action: CoreSessionAction;
+    receipt: CoreSessionReceipt;
+    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: CoreSessionActionResult): void;
+/** One Session FIFO shared by native writes and the existing parent mailbox. No model loop. */
+export declare class SessionInputCoordinator {
+    #private;
+    readonly diagnose: (receipt: CoreSessionReceipt) => void;
+    constructor(diagnose?: (receipt: CoreSessionReceipt) => void);
+    get hasPending(): boolean;
+    get hasBoundaryPending(): boolean;
+    get executing(): boolean;
+    currentCompact(): CoreSessionReceipt | undefined;
+    inspect(): readonly CoreSessionReceipt[];
+    performAppend(input: CoreAppendInput, call: CoreOperationContext, action: CoreSessionAction, leaf: (entry: SessionInputEntry, request: CoreSessionRequest, call: CoreOperationContext) => Promise<CoreSessionActionResult>): Promise<CoreSessionReceipt>;
+    /** SDK manual/automatic compaction shares the same active receipt as queued compaction. */
+    recordCompactCommit(outcome: CoreSessionActionResult): void;
+    performCompact(input: CoreCompactInput, call: CoreOperationContext, action: (commit: (outcome: CoreSessionActionResult) => void) => Promise<CoreSessionActionResult>): Promise<CoreSessionActionResult>;
+    accept(request: CoreSessionRequest, source: CoreOperationContext, action: CoreSessionAction, status: 'accepted' | 'queued', parentMessage?: unknown): SessionInputEntry;
+    handled(input: CoreSubmitInput, call: CoreOperationContext, value?: unknown): CoreSessionReceipt;
+    drain(leaf: (entry: SessionInputEntry, request: CoreSessionRequest, call: CoreOperationContext) => Promise<CoreSessionActionResult>, execution?: {
+        readonly executionId: string;
+        readonly turnId: string;
+        readonly signal: AbortSignal;
+    }, 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: CoreSessionRequest): void;