@myagentroam/agent 0.9.159 → 0.9.160

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

@@ -0,0 +1,283 @@
+import { MarAgentError } from '../error.js';
+export function validateCoreProcessInput(input) {
+    if (!input ||
+        typeof input.executable !== 'string' ||
+        !input.executable ||
+        input.executable.includes('\0') ||
+        (input.argv !== undefined &&
+            (!Array.isArray(input.argv) ||
+                input.argv.some((value) => typeof value !== 'string' || value.includes('\0')))) ||
+        (input.cwd !== undefined && (typeof input.cwd !== 'string' || input.cwd.includes('\0'))) ||
+        (input.env !== undefined &&
+            (!input.env ||
+                typeof input.env !== 'object' ||
+                Array.isArray(input.env) ||
+                Object.entries(input.env).some(([key, value]) => !key ||
+                    key.includes('=') ||
+                    key.includes('\0') ||
+                    typeof value !== 'string' ||
+                    value.includes('\0')))) ||
+        (input.input !== undefined &&
+            typeof input.input !== 'string' &&
+            !(input.input instanceof Uint8Array)))
+        throw new MarAgentError('MAR_AGENT_PROCESS_INPUT_INVALID', 'Process input is invalid.');
+}
+function copyProcessInput(input) {
+    validateCoreProcessInput(input);
+    return {
+        ...input,
+        ...(input.argv === undefined ? {} : { argv: [...input.argv] }),
+        ...(input.env === undefined ? {} : { env: { ...input.env } }),
+        ...(input.input instanceof Uint8Array ? { input: new Uint8Array(input.input) } : {})
+    };
+}
+export function bindCoreProcesses(backend, run, scope, hooks, diagnose) {
+    const acquire = async (input, call, emitExit = true) => {
+        input = copyProcessInput(input);
+        if (typeof backend.spawn !== 'function')
+            throw new MarAgentError('MAR_AGENT_HOST_PORT_UNAVAILABLE', 'Native process port is unavailable.');
+        let closed = false;
+        const iterators = [];
+        let pending;
+        const resource = scope.effect(() => async () => {
+            closed = true;
+            call.signal.removeEventListener('abort', abort);
+            const handle = await pending.catch(() => undefined);
+            let firstError;
+            let failed = false;
+            try {
+                if (typeof handle?.cancel === 'function')
+                    await handle.cancel();
+            }
+            catch (error) {
+                failed = true;
+                firstError = error;
+            }
+            const released = await Promise.allSettled(iterators.map((iterator) => Promise.resolve().then(() => iterator.return?.())));
+            const failure = released.find((result) => result.status === 'rejected');
+            if (failed || failure?.status === 'rejected') {
+                const error = failed
+                    ? firstError
+                    : failure?.status === 'rejected'
+                        ? failure.reason
+                        : undefined;
+                throw new MarAgentError('MAR_AGENT_PROCESS_CLEANUP_FAILED', 'Native process cleanup failed.', {
+                    details: {
+                        reasonCode: error instanceof MarAgentError ? error.code : 'BACKEND_CLEANUP_FAILED'
+                    }
+                });
+            }
+        });
+        const cancel = () => resource.dispose();
+        const abort = () => {
+            void cancel().catch(() => diagnose());
+        };
+        pending = Promise.resolve().then(() => backend.spawn(input, call));
+        call.signal.addEventListener('abort', abort, { once: true });
+        let handle;
+        try {
+            handle = await pending;
+            if (!handle ||
+                typeof handle.processId !== 'string' ||
+                !handle.processId ||
+                typeof handle.wait !== 'function' ||
+                typeof handle.cancel !== 'function' ||
+                typeof handle.stdout?.[Symbol.asyncIterator] !== 'function' ||
+                typeof handle.stderr?.[Symbol.asyncIterator] !== 'function')
+                throw new MarAgentError('MAR_AGENT_PROCESS_OUTPUT_INVALID', 'Native process handle is invalid.');
+            await resource.ready;
+            call.signal.throwIfAborted();
+        }
+        catch (error) {
+            try {
+                await cancel();
+            }
+            catch {
+                diagnose();
+            }
+            call.signal.throwIfAborted();
+            throw error;
+        }
+        const stream = (source) => {
+            const iterator = source[Symbol.asyncIterator]();
+            iterators.push(iterator);
+            let done = false;
+            let tail = Promise.resolve();
+            async function pull() {
+                if (done || closed)
+                    return { done: true, value: undefined };
+                try {
+                    return await scope.run(async (signal) => {
+                        signal.throwIfAborted();
+                        const next = await iterator.next();
+                        signal.throwIfAborted();
+                        if (next.done) {
+                            done = true;
+                            return { done: true, value: undefined };
+                        }
+                        if (!(next.value instanceof Uint8Array))
+                            throw new MarAgentError('MAR_AGENT_PROCESS_OUTPUT_INVALID', 'Process stream must yield raw bytes.');
+                        return { done: false, value: new Uint8Array(next.value) };
+                    }, call.signal);
+                }
+                catch (error) {
+                    done = true;
+                    try {
+                        await cancel();
+                    }
+                    catch {
+                        diagnose();
+                    }
+                    throw error;
+                }
+            }
+            return {
+                [Symbol.asyncIterator]() {
+                    return this;
+                },
+                next() {
+                    const pending = tail.then(pull);
+                    tail = pending.catch(() => undefined);
+                    return pending;
+                },
+                async return() {
+                    done = true;
+                    await cancel();
+                    return { done: true, value: undefined };
+                }
+            };
+        };
+        let completion;
+        return {
+            processId: handle.processId,
+            stdout: stream(handle.stdout),
+            stderr: stream(handle.stderr),
+            cancel,
+            wait: () => (completion ??= scope
+                .run(async (signal) => {
+                signal.throwIfAborted();
+                const exit = await handle.wait();
+                signal.throwIfAborted();
+                if (!exit ||
+                    (exit.code !== null && !Number.isInteger(exit.code)) ||
+                    (exit.signal !== null && typeof exit.signal !== 'string'))
+                    throw new MarAgentError('MAR_AGENT_PROCESS_OUTPUT_INVALID', 'Native process exit result is invalid.');
+                if (emitExit)
+                    await hooks.emit('process.completed', { processId: handle.processId, ...exit }, call);
+                return exit;
+            }, call.signal)
+                .catch(async (error) => {
+                try {
+                    await cancel();
+                }
+                catch {
+                    diagnose();
+                }
+                throw error;
+            }))
+        };
+    };
+    return {
+        spawn: async (input) => {
+            input = copyProcessInput(input);
+            return run((call) => hooks.invoke('process.spawn', input, call, (input, effective) => acquire(input, effective)), input.signal);
+        },
+        run: async (input) => {
+            input = copyProcessInput(input);
+            return run((call) => hooks.invoke('process.run', input, call, async (input, effective) => {
+                const limit = input.outputLimitBytes ?? 4_194_304;
+                const timeout = input.timeoutMs ?? 30_000;
+                if (!Number.isSafeInteger(limit) ||
+                    limit < 0 ||
+                    !Number.isSafeInteger(timeout) ||
+                    timeout <= 0)
+                    throw new MarAgentError('MAR_AGENT_PROCESS_INPUT_INVALID', 'Process timeout and output limit are invalid.');
+                const handle = await acquire(input, effective, false);
+                let timedOut = false;
+                const due = performance.now() + timeout;
+                let timer;
+                let timeoutWork;
+                const arm = () => {
+                    timer = setTimeout(() => {
+                        if (performance.now() < due) {
+                            arm();
+                            return;
+                        }
+                        timedOut = true;
+                        timeoutWork = handle.cancel();
+                        void timeoutWork.catch(() => undefined);
+                    }, Math.min(Math.max(0, due - performance.now()), 2_147_483_647));
+                    timer.unref();
+                };
+                arm();
+                const collect = async (stream) => {
+                    const chunks = [];
+                    let total = 0;
+                    let retained = 0;
+                    for await (const chunk of stream) {
+                        total += chunk.length;
+                        const keep = Math.min(chunk.length, limit - retained);
+                        if (keep > 0) {
+                            chunks.push(chunk.slice(0, keep));
+                            retained += keep;
+                        }
+                    }
+                    const bytes = new Uint8Array(retained);
+                    let offset = 0;
+                    for (const chunk of chunks) {
+                        bytes.set(chunk, offset);
+                        offset += chunk.length;
+                    }
+                    return { bytes, total };
+                };
+                let failed = false;
+                const work = [handle.wait(), collect(handle.stdout), collect(handle.stderr)];
+                try {
+                    const [exit, stdout, stderr] = await Promise.all(work);
+                    await timeoutWork;
+                    await hooks.emit('process.completed', {
+                        ...exit,
+                        processId: handle.processId,
+                        stdoutBytes: stdout.total,
+                        stderrBytes: stderr.total,
+                        truncated: stdout.total > limit || stderr.total > limit,
+                        timedOut
+                    }, effective);
+                    return {
+                        ...exit,
+                        processId: handle.processId,
+                        stdout: stdout.bytes,
+                        stderr: stderr.bytes,
+                        stdoutBytes: stdout.total,
+                        stderrBytes: stderr.total,
+                        truncated: stdout.total > limit || stderr.total > limit,
+                        timedOut
+                    };
+                }
+                catch (error) {
+                    failed = true;
+                    try {
+                        await handle.cancel();
+                    }
+                    catch {
+                        diagnose();
+                    }
+                    await Promise.allSettled(work);
+                    throw error;
+                }
+                finally {
+                    clearTimeout(timer);
+                    try {
+                        await handle.cancel();
+                    }
+                    catch (error) {
+                        if (failed)
+                            diagnose();
+                        else
+                            throw error;
+                    }
+                }
+            }), input.signal);
+        }
+    };
+}

package/dist/agent-core/extensions/prompt-composition.d.ts

@@ -0,0 +1,24 @@
+import type { ExecutionMode } from '../runtime/contracts.js';
+import type { CoreDomainFacts, CoreDomainOperations, CorePromptSection } from './contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { CoreOperationContext } from './operation.js';
+export interface CorePromptPart {
+    readonly id: string;
+    readonly text: string | null;
+    readonly scope?: 'shared' | 'session';
+}
+export interface CorePromptFacts {
+    readonly modelId?: string;
+    readonly mode?: ExecutionMode;
+    readonly tools?: readonly string[];
+}
+export interface CorePromptComposition {
+    readonly sections: readonly CorePromptPart[];
+    readonly facts?: CorePromptFacts;
+}
+export interface CorePromptSectionInput extends CorePromptPart {
+    readonly facts?: CorePromptFacts;
+}
+export declare function normalizePromptComposition(value: unknown): CorePromptComposition;
+export declare function renderPromptSections(sections: readonly CorePromptPart[]): string;
+export declare function composePromptSections(hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>, input: CorePromptComposition, registered: readonly CorePromptSection[], call: CoreOperationContext): Promise<CorePromptComposition>;

package/dist/agent-core/extensions/prompt-composition.js

@@ -0,0 +1,106 @@
+import { MarAgentError } from '../error.js';
+function invalid() {
+    throw new MarAgentError('MAR_AGENT_EXTENSION_PROMPT_INVALID', 'Prompt composition is invalid.');
+}
+function object(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        invalid();
+    return value;
+}
+function text(value) {
+    if (value !== null && typeof value !== 'string')
+        invalid();
+    return value;
+}
+export function normalizePromptComposition(value) {
+    const source = object(value);
+    const sections = source.sections;
+    const facts = source.facts;
+    if (!Array.isArray(sections))
+        invalid();
+    const ids = new Set();
+    let sessionScope = false;
+    const parts = Array.from(sections, (value) => {
+        const source = object(value);
+        const id = source.id;
+        const content = source.text;
+        const scope = source.scope;
+        if (typeof id !== 'string' || !id.trim())
+            invalid();
+        if (ids.has(id))
+            throw new MarAgentError('MAR_AGENT_EXTENSION_PROMPT_CONFLICT', 'Prompt section id conflicts.');
+        ids.add(id);
+        if (scope !== undefined && scope !== 'shared' && scope !== 'session')
+            invalid();
+        if (scope === 'shared' && sessionScope)
+            invalid();
+        if (scope === 'session')
+            sessionScope = true;
+        return Object.freeze({ id, text: text(content), ...(scope === undefined ? {} : { scope }) });
+    });
+    let copiedFacts;
+    if (facts !== undefined) {
+        const source = object(facts);
+        const modelId = source.modelId;
+        const mode = source.mode;
+        const tools = source.tools;
+        const copiedTools = Array.isArray(tools) ? Array.from(tools) : undefined;
+        if (modelId !== undefined && (typeof modelId !== 'string' || !modelId))
+            invalid();
+        if (mode !== undefined && mode !== 'run' && mode !== 'plan' && mode !== 'compact')
+            invalid();
+        if (tools !== undefined &&
+            (copiedTools === undefined || copiedTools.some((name) => typeof name !== 'string' || !name)))
+            invalid();
+        copiedFacts = Object.freeze({
+            ...(modelId === undefined ? {} : { modelId: modelId }),
+            ...(mode === undefined ? {} : { mode: mode }),
+            ...(copiedTools === undefined ? {} : { tools: Object.freeze(copiedTools) })
+        });
+    }
+    return Object.freeze({
+        sections: Object.freeze(parts),
+        ...(copiedFacts === undefined ? {} : { facts: copiedFacts })
+    });
+}
+export function renderPromptSections(sections) {
+    return sections
+        .map((part) => part.text)
+        .filter(Boolean)
+        .join('\n\n');
+}
+export async function composePromptSections(hooks, input, registered, call) {
+    const snapshot = normalizePromptComposition({
+        ...input,
+        sections: [...input.sections, ...registered]
+    });
+    const result = await hooks.invoke('prompt.sections', snapshot, call, async (input, call) => {
+        const selected = normalizePromptComposition(input);
+        const sections = [];
+        for (const part of selected.sections) {
+            const output = await hooks.invoke('prompt.section', Object.freeze({
+                ...part,
+                ...(selected.facts === undefined ? {} : { facts: selected.facts })
+            }), call, async (input, call) => {
+                call.signal.throwIfAborted();
+                const selected = normalizePromptComposition({
+                    sections: [input],
+                    facts: object(input).facts
+                });
+                // A text handler cannot silently retarget its captured section. Whole-list edits use prompt.sections.
+                if (selected.sections[0].id !== part.id)
+                    invalid();
+                return selected.sections[0].text;
+            });
+            call.signal.throwIfAborted();
+            sections.push({
+                id: part.id,
+                text: text(output),
+                ...(part.scope === undefined ? {} : { scope: part.scope })
+            });
+        }
+        return normalizePromptComposition({ ...selected, sections });
+    });
+    call.signal.throwIfAborted();
+    return normalizePromptComposition(result);
+}

package/dist/agent-core/extensions/prompt-input.d.ts

@@ -0,0 +1,23 @@
+import type { RunInputImage } from '../runtime/contracts.js';
+import type { CoreDomainOperations, CoreDomainFacts } from './contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { CoreOperationContext } from './operation.js';
+/** Content only. Identity, queue policy and lifetime come from the physical ingress. */
+export interface CorePromptInput {
+    readonly text: string;
+    readonly modelText?: string;
+    readonly context?: readonly string[];
+    /** Optional model projection; context remains the original admitted content. */
+    readonly modelContext?: readonly string[];
+    readonly images?: readonly RunInputImage[];
+}
+export interface CorePromptResult {
+    /** An interceptor answer, not proof of queue admission or a storage write. */
+    readonly value?: unknown;
+}
+export declare function captureCorePromptInput(input: CorePromptInput): CorePromptInput;
+/** One admission chain for SDK input and queued Extension input, before either writer or FIFO. */
+export declare function invokeCorePromptSubmission(hooks: ExtensionHooks<CoreDomainOperations, CoreDomainFacts>, input: CorePromptInput, call: CoreOperationContext, leaf: (input: CorePromptInput, call: CoreOperationContext) => Promise<CorePromptResult>): Promise<{
+    readonly entered: number;
+    readonly result: CorePromptResult;
+}>;

package/dist/agent-core/extensions/prompt-input.js

@@ -0,0 +1,46 @@
+import { MarAgentError } from '../error.js';
+export function captureCorePromptInput(input) {
+    if (!input ||
+        typeof input.text !== 'string' ||
+        (input.modelText !== undefined && typeof input.modelText !== 'string') ||
+        (input.context !== undefined &&
+            (!Array.isArray(input.context) ||
+                !Array.from(input.context).every((item) => typeof item === 'string'))) ||
+        (input.modelContext !== undefined &&
+            (!Array.isArray(input.modelContext) ||
+                !Array.from(input.modelContext).every((item) => typeof item === 'string'))) ||
+        (input.images !== undefined &&
+            (!Array.isArray(input.images) ||
+                !Array.from(input.images).every((image) => image &&
+                    typeof image.name === 'string' &&
+                    typeof image.mimeType === 'string' &&
+                    typeof image.dataBase64 === 'string'))))
+        throw new MarAgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Prompt content is invalid.');
+    return structuredClone({
+        text: input.text,
+        ...(input.modelText === undefined ? {} : { modelText: input.modelText }),
+        ...(input.context === undefined ? {} : { context: input.context }),
+        ...(input.modelContext === undefined ? {} : { modelContext: input.modelContext }),
+        ...(input.images === undefined ? {} : { images: input.images })
+    });
+}
+/** One admission chain for SDK input and queued Extension input, before either writer or FIFO. */
+export async function invokeCorePromptSubmission(hooks, input, call, leaf) {
+    let entered = 0;
+    let tail = Promise.resolve();
+    const result = await hooks.invoke('prompt.submit', captureCorePromptInput(input), call, (input, effective) => {
+        const captured = captureCorePromptInput(input);
+        // Concurrent next calls keep their invocation order at the single writer/FIFO boundary.
+        const pending = tail.then(async () => {
+            effective.signal.throwIfAborted();
+            const result = await leaf(captured, effective);
+            entered++;
+            return result;
+        });
+        tail = pending.catch(() => undefined);
+        return pending;
+    });
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        throw new MarAgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Prompt admission result is invalid.');
+    return { entered, result };
+}

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

@@ -0,0 +1,27 @@
+export type CoreDisposer = () => void | Promise<void>;
+export interface CoreResourceRegistration {
+    readonly ready: Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface CoreResourceScope {
+    effect(acquire: () => CoreDisposer | Promise<CoreDisposer>): CoreResourceRegistration;
+}
+/** An instance's managed resources, not an OS sandbox or a process-wide resource owner. */
+export declare class ExtensionResourceScope implements CoreResourceScope {
+    #private;
+    readonly instanceId: `${string}-${string}-${string}-${string}-${string}`;
+    static get initializing(): boolean;
+    static initialize<T>(run: () => Promise<T>): Promise<T>;
+    get state(): "STAGED" | "ACTIVE" | "RETIRING" | "DISPOSED";
+    get signal(): AbortSignal;
+    activate(): void;
+    effect(acquire: () => CoreDisposer | Promise<CoreDisposer>): CoreResourceRegistration;
+    run<T>(operation: (signal: AbortSignal) => Promise<T>, parent?: AbortSignal): Promise<T>;
+    after(durationMs: number, callback: (signal: AbortSignal) => void | Promise<void>, onError?: (error: unknown) => void): CoreResourceRegistration;
+    every(durationMs: number, callback: (signal: AbortSignal) => void | Promise<void>, onError?: (error: unknown) => void): CoreResourceRegistration;
+    sleep(durationMs: number, parent?: AbortSignal): Promise<void>;
+    /** Wait for acquisitions added by setup before publishing any callbacks. */
+    ready(): Promise<void>;
+    retire(): void;
+    dispose(): Promise<void>;
+}