@myagentroam/agent 0.11.32 → 0.11.34

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

@@ -1,221 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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

@@ -1,61 +0,0 @@
-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

@@ -1,163 +0,0 @@
-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;
-    readonly async?: boolean;
-}
-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 {
-    /** SDK-owned admission barrier, never accepted from Extension input. */
-    nativeSteer?: {
-        readonly ready: Promise<void>;
-        recordId?: string;
-    };
-    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 boundarySize(): number;
-    get hasIdleBarrier(): boolean;
-    restoreSteer(recordId: string, text: string, source: CoreOperationContext): void;
-    get hasBoundaryPending(): boolean;
-    get executing(): boolean;
-    get hasBoundaryCompactPending(): 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;
-        /** 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: CoreSessionRequest): void;