@myagentroam/agent 0.9.159 → 0.9.161

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

@@ -0,0 +1,27 @@
+import type { CoreOperationContext } from './operation.js';
+import type { CoreDomainFacts, CoreDomainOperations } from './contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+export interface CoreEnvironmentKey {
+    readonly key: string;
+    readonly signal?: AbortSignal;
+}
+export interface CoreEnvironmentSet extends CoreEnvironmentKey {
+    readonly value?: string;
+}
+export interface CoreEnvironmentChange {
+    readonly changed: boolean;
+}
+export interface CoreEnvironmentApi {
+    get(input: CoreEnvironmentKey): Promise<string | undefined>;
+    set(input: CoreEnvironmentSet): Promise<CoreEnvironmentChange>;
+}
+export interface CoreEnvironmentBackend {
+    get(input: CoreEnvironmentKey, call: CoreOperationContext): Promise<string | undefined>;
+    set(input: CoreEnvironmentSet, call: CoreOperationContext): Promise<CoreEnvironmentChange>;
+}
+export interface CoreEnvironmentCompletion {
+    readonly operation: 'get' | 'set';
+    readonly changed?: boolean;
+}
+export declare function validateEnvironmentInput(input: CoreEnvironmentKey): void;
+export declare function bindCoreEnvironment(backend: CoreEnvironmentBackend, run: <Value>(operation: (call: CoreOperationContext) => Promise<Value>, signal?: AbortSignal) => Promise<Value>, hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>): CoreEnvironmentApi;

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

@@ -0,0 +1,52 @@
+import { MarAgentError } from '../error.js';
+export function validateEnvironmentInput(input) {
+    if (!input ||
+        typeof input.key !== 'string' ||
+        !input.key ||
+        input.key.includes('=') ||
+        input.key.includes('\0') ||
+        ('value' in input &&
+            input.value !== undefined &&
+            (typeof input.value !== 'string' || input.value.includes('\0'))))
+        throw new MarAgentError('MAR_AGENT_ENVIRONMENT_INPUT_INVALID', 'Environment variable input is invalid.');
+}
+export function bindCoreEnvironment(backend, run, hooks) {
+    return {
+        get: async (input) => {
+            input = { ...input };
+            validateEnvironmentInput(input);
+            return run((call) => hooks.invoke('environment.get', input, call, async (input, effective) => {
+                validateEnvironmentInput(input);
+                if (typeof backend.get !== 'function')
+                    throw unavailable('get');
+                const value = await backend.get({ ...input }, effective);
+                if (value !== undefined && typeof value !== 'string')
+                    throw invalidResult();
+                await hooks.emit('environment.completed', { operation: 'get' }, effective);
+                return value;
+            }), input.signal);
+        },
+        set: async (input) => {
+            input = { ...input };
+            validateEnvironmentInput(input);
+            return run((call) => hooks.invoke('environment.set', input, call, async (input, effective) => {
+                validateEnvironmentInput(input);
+                if (typeof backend.set !== 'function')
+                    throw unavailable('set');
+                const output = await backend.set({ ...input }, effective);
+                const changed = output?.changed;
+                if (typeof changed !== 'boolean')
+                    throw invalidResult();
+                const result = { changed };
+                await hooks.emit('environment.completed', { operation: 'set', ...result }, effective);
+                return result;
+            }), input.signal);
+        }
+    };
+}
+function unavailable(operation) {
+    return new MarAgentError('MAR_AGENT_HOST_PORT_UNAVAILABLE', 'Native environment port is unavailable.', { details: { operation } });
+}
+function invalidResult() {
+    return new MarAgentError('MAR_AGENT_ENVIRONMENT_OUTPUT_INVALID', 'Native environment result is invalid.');
+}

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

@@ -0,0 +1,64 @@
+import type { CoreOperationContext } from './operation.js';
+import type { CoreDomainFacts, CoreDomainOperations } from './contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+export type CoreFileType = 'file' | 'directory' | 'symlink' | 'other';
+export interface CoreFilePath {
+    readonly path: string;
+}
+export interface CoreFileInfo {
+    readonly path: string;
+    readonly type: CoreFileType;
+    readonly size: number;
+    readonly modifiedAtMs: number;
+    readonly createdAtMs: number;
+}
+export interface CoreFileEntry {
+    readonly name: string;
+    readonly type: CoreFileType;
+}
+export interface CoreFileWrite extends CoreFilePath {
+    readonly bytes: Uint8Array;
+    readonly createParents?: boolean;
+}
+export interface CoreFileRemove extends CoreFilePath {
+    readonly recursive?: boolean;
+    readonly force?: boolean;
+}
+export interface CoreFileTransfer {
+    readonly from: string;
+    readonly to: string;
+}
+export interface CoreFilesApi {
+    read(input: CoreFilePath): Promise<Uint8Array>;
+    write(input: CoreFileWrite): Promise<{
+        readonly bytesWritten: number;
+    }>;
+    stat(input: CoreFilePath): Promise<CoreFileInfo>;
+    list(input: CoreFilePath): Promise<readonly CoreFileEntry[]>;
+    mkdir(input: CoreFilePath & {
+        readonly recursive?: boolean;
+    }): Promise<void>;
+    remove(input: CoreFileRemove): Promise<void>;
+    move(input: CoreFileTransfer): Promise<void>;
+    copy(input: CoreFileTransfer): Promise<void>;
+}
+type Input<Name extends keyof CoreFilesApi> = Parameters<CoreFilesApi[Name]>[0];
+type Output<Name extends keyof CoreFilesApi> = Awaited<ReturnType<CoreFilesApi[Name]>>;
+export type CoreFilesBackend = {
+    [Name in keyof CoreFilesApi]: (input: Input<Name>, call: CoreOperationContext) => Promise<Output<Name>>;
+};
+export type CoreFileOperations = {
+    [Name in keyof CoreFilesApi as `files.${Name}`]: {
+        input: Input<Name>;
+        output: Output<Name>;
+    };
+};
+export type CoreFileCompletion = {
+    [Name in keyof CoreFilesApi]: {
+        readonly operation: Name;
+        readonly input: Input<Name>;
+        readonly output: Output<Name>;
+    };
+}[keyof CoreFilesApi];
+export declare function bindCoreFiles(backend: CoreFilesBackend, run: <Value>(operation: (call: CoreOperationContext) => Promise<Value>) => Promise<Value>, hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>): CoreFilesApi;
+export {};

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

@@ -0,0 +1,26 @@
+import { MarAgentError } from '../error.js';
+export function bindCoreFiles(backend, run, hooks) {
+    const invoke = (name, input) => run((call) => {
+        const handler = backend[name];
+        if (typeof handler !== 'function')
+            throw new MarAgentError('MAR_AGENT_HOST_PORT_UNAVAILABLE', 'Native file port is unavailable.', { details: { operation: name } });
+        return hooks.invoke(`files.${name}`, input, call, async (input, effective) => {
+            const factInput = input && 'bytes' in input && input.bytes instanceof Uint8Array
+                ? { ...input, bytes: new Uint8Array(input.bytes) }
+                : { ...input };
+            const output = await handler.call(backend, input, effective);
+            await hooks.emit('files.completed', { operation: name, input: factInput, output }, effective);
+            return output;
+        });
+    });
+    return {
+        read: (input) => invoke('read', input),
+        write: (input) => invoke('write', input),
+        stat: (input) => invoke('stat', input),
+        list: (input) => invoke('list', input),
+        mkdir: (input) => invoke('mkdir', input),
+        remove: (input) => invoke('remove', input),
+        move: (input) => invoke('move', input),
+        copy: (input) => invoke('copy', input)
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { CoreCallbackRunner, CoreOperationContext } from './operation.js';
+import type { CoreResourceRegistration } from './resources.js';
+import { ExtensionResourceScope } from './resources.js';
+export interface CoreHookOptions {
+    readonly reentry?: 'skip-active' | 'allow';
+}
+export interface CoreHookDiagnostic {
+    readonly code: 'MAR_AGENT_EXTENSION_OBSERVER_FAILED';
+    readonly operationId: string;
+}
+export type CoreInterceptor<Input, Output> = (input: Input, call: CoreOperationContext, next: (input: Input) => Promise<Output>) => Output | Promise<Output>;
+/** Typed domain chains with per-dispatch snapshots and async-ancestor reentry tracking. */
+export declare class ExtensionHooks<Operations extends {
+    [Key in keyof Operations]: {
+        input: unknown;
+        output: unknown;
+    };
+}, Facts extends object> {
+    #private;
+    readonly diagnose: (diagnostic: CoreHookDiagnostic) => void;
+    readonly callback: CoreCallbackRunner;
+    constructor(diagnose?: (diagnostic: CoreHookDiagnostic) => void, callback?: CoreCallbackRunner);
+    /** Internal physical callback ingress; unrelated dispatch must not inherit reentry suppression. */
+    independent<Value>(run: () => Value): Value;
+    /** Avoid materializing public views when no active interceptor can consume them. */
+    hasInterceptors(key: keyof Operations): boolean;
+    intercept<Key extends keyof Operations>(owner: ExtensionResourceScope, key: Key, handler: CoreInterceptor<Operations[Key]['input'], Operations[Key]['output']>, options?: CoreHookOptions): CoreResourceRegistration;
+    observe<Key extends keyof Facts>(owner: ExtensionResourceScope, key: Key, handler: (fact: Facts[Key], call: CoreOperationContext) => void | Promise<void>, options?: CoreHookOptions): CoreResourceRegistration;
+    invoke<Key extends keyof Operations>(key: Key, input: Operations[Key]['input'], call: CoreOperationContext, leaf: (input: Operations[Key]['input'], call: CoreOperationContext) => Promise<Operations[Key]['output']>): Promise<Operations[Key]['output']>;
+    hasObservers<Key extends keyof Facts>(key: Key): boolean;
+    emit<Key extends keyof Facts>(key: Key, fact: Facts[Key], call: CoreOperationContext, settled?: boolean): Promise<void>;
+}

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

@@ -0,0 +1,135 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** Typed domain chains with per-dispatch snapshots and async-ancestor reentry tracking. */
+export class ExtensionHooks {
+    diagnose;
+    callback;
+    #interceptors = new Map();
+    #observers = new Map();
+    #active = new AsyncLocalStorage();
+    constructor(diagnose = () => { }, callback = async (call, run) => run(call)) {
+        this.diagnose = diagnose;
+        this.callback = callback;
+    }
+    /** Internal physical callback ingress; unrelated dispatch must not inherit reentry suppression. */
+    independent(run) {
+        return this.#active.run([], run);
+    }
+    /** Avoid materializing public views when no active interceptor can consume them. */
+    hasInterceptors(key) {
+        return this.#interceptors.get(key)?.some((entry) => entry.owner.state === 'ACTIVE') ?? false;
+    }
+    intercept(owner, key, handler, options = {}) {
+        const entry = {
+            owner,
+            handler: handler,
+            reentry: options.reentry ?? 'skip-active'
+        };
+        const entries = this.#interceptors.get(key) ?? [];
+        const registration = owner.effect(() => () => {
+            const index = entries.indexOf(entry);
+            if (index !== -1)
+                entries.splice(index, 1);
+        });
+        entries.push(entry);
+        this.#interceptors.set(key, entries);
+        return registration;
+    }
+    observe(owner, key, handler, options = {}) {
+        const entry = {
+            owner,
+            handler: handler,
+            reentry: options.reentry ?? 'skip-active'
+        };
+        const entries = this.#observers.get(key) ?? [];
+        const registration = owner.effect(() => () => {
+            const index = entries.indexOf(entry);
+            if (index !== -1)
+                entries.splice(index, 1);
+        });
+        entries.push(entry);
+        this.#observers.set(key, entries);
+        return registration;
+    }
+    async invoke(key, input, call, leaf) {
+        call.signal.throwIfAborted();
+        const snapshot = [...(this.#interceptors.get(key) ?? [])].filter((entry) => entry.owner.state === 'ACTIVE');
+        const dispatch = async (index, value, signal) => {
+            signal.throwIfAborted();
+            const entry = snapshot[index];
+            if (!entry)
+                return leaf(value, Object.freeze({ ...call, signal }));
+            const ancestors = this.#active.getStore() ?? [];
+            if (entry.reentry === 'skip-active' &&
+                ancestors.some((frame) => frame.active && frame.entry === entry))
+                return dispatch(index + 1, value, signal);
+            return entry.owner.run(async (signal) => {
+                const frame = { entry, active: true };
+                return this.#active.run([...ancestors, frame], async () => {
+                    const controller = new AbortController();
+                    const effectiveSignal = AbortSignal.any([signal, controller.signal]);
+                    const pending = new Set();
+                    try {
+                        return await this.callback(Object.freeze({ ...call, signal: effectiveSignal }), (effective) => entry.handler(value, effective, (nextValue) => {
+                            const result = dispatch(index + 1, nextValue, effective.signal);
+                            const settled = result.then(() => undefined, () => undefined);
+                            pending.add(settled);
+                            void settled.then(() => pending.delete(settled));
+                            return result;
+                        }));
+                    }
+                    catch (error) {
+                        controller.abort();
+                        throw error;
+                    }
+                    finally {
+                        while (pending.size)
+                            await Promise.all([...pending]);
+                        frame.active = false;
+                    }
+                });
+            }, signal);
+        };
+        return (await dispatch(0, input, call.signal));
+    }
+    hasObservers(key) {
+        return (this.#observers.get(key) ?? []).some((entry) => entry.owner.state === 'ACTIVE');
+    }
+    async emit(key, fact, call, settled = false) {
+        const snapshot = [...(this.#observers.get(key) ?? [])].filter((entry) => entry.owner.state === 'ACTIVE');
+        for (const entry of snapshot) {
+            if (!settled)
+                call.signal.throwIfAborted();
+            const ancestors = this.#active.getStore() ?? [];
+            if (entry.reentry === 'skip-active' &&
+                ancestors.some((frame) => frame.active && frame.entry === entry))
+                continue;
+            try {
+                // Each observer gets its own copy, never writable authoritative state or another observer's view.
+                await entry.owner.run(async (signal) => {
+                    const frame = { entry, active: true };
+                    await this.#active.run([...ancestors, frame], async () => {
+                        try {
+                            await this.callback(Object.freeze({ ...call, signal: AbortSignal.any([signal, call.signal]) }), (effective) => entry.handler(structuredClone(fact), effective), settled);
+                        }
+                        finally {
+                            frame.active = false;
+                        }
+                    });
+                }, settled ? undefined : call.signal);
+            }
+            catch {
+                if (!settled)
+                    call.signal.throwIfAborted();
+                try {
+                    this.diagnose({
+                        code: 'MAR_AGENT_EXTENSION_OBSERVER_FAILED',
+                        operationId: call.operationId
+                    });
+                }
+                catch {
+                    /* A diagnostic sink must not change an already completed fact. */
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,39 @@
+import type { CoreCapabilitySnapshot, CoreExtensionDiagnostic, CoreExtensionSource, CoreRuntimeExtension } from './contracts.js';
+import { ExtensionOperations, type CoreOperationContext } from './operation.js';
+import { ExtensionSession } from './session.js';
+import type { CoreToolBinding } from './tools.js';
+import type { CoreModelsBackend } from './models.js';
+import type { CoreCheckpointBackend } from './data.js';
+import type { CoreSessionBackend } from './session-input.js';
+import type { CoreHostExtensionPorts } from '../host/contracts.js';
+import { type CoreAgentsBackend } from './agents.js';
+export interface ExtensionManagerOptions {
+    readonly hostPorts?: CoreHostExtensionPorts;
+    readonly extensions: readonly CoreRuntimeExtension[] | CoreExtensionSource;
+    readonly capabilities: readonly string[];
+    readonly busyExcept: (sessionId: string) => boolean;
+    readonly baseTools?: (sessionId: string, context?: Pick<CoreOperationContext, 'executionId'>) => readonly CoreToolBinding[];
+    readonly models?: CoreModelsBackend;
+    readonly checkpoint?: CoreCheckpointBackend;
+    readonly sessionBackend?: (sessionId: string) => CoreSessionBackend | undefined;
+    readonly agentsBackend?: (sessionId: string) => CoreAgentsBackend | undefined;
+    readonly allowTool?: (sessionId: string, name: string, definition?: CoreToolBinding['definition']) => boolean;
+    readonly scheduleTool?: (sessionId: string) => ExtensionSession['scheduleTool'];
+}
+/** Agent admission coordinates a single composition generation, never parallel replacement loops. */
+export declare class ExtensionManager {
+    #private;
+    readonly options: ExtensionManagerOptions;
+    readonly operations: ExtensionOperations;
+    readonly capabilities: CoreCapabilitySnapshot;
+    constructor(options: ExtensionManagerOptions);
+    diagnostics(): readonly CoreExtensionDiagnostic[];
+    session(id: string): ExtensionSession | undefined;
+    get revision(): string | undefined;
+    hasReferences(): boolean;
+    prepare(sessionId: string, signal: AbortSignal, baseTools?: readonly CoreToolBinding[], refresh?: boolean): Promise<ExtensionSession>;
+    clearSession(id: string): Promise<void>;
+    endSession(id: string, reason: 'clear' | 'other', resumable?: boolean): Promise<void>;
+    retireSession(id: string): void;
+    dispose(): Promise<void>;
+}