@myagentroam/agent 0.11.33 → 0.11.34

package/dist/extensions/processes.js

@@ -0,0 +1,284 @@
+import { AgentError } 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 AgentError('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 AgentError('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 AgentError('MAR_AGENT_PROCESS_CLEANUP_FAILED', 'Native process cleanup failed.', {
+                    details: {
+                        reasonCode: error instanceof AgentError ? 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 AgentError('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 AgentError('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 AgentError('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 AgentError('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();
+                        // eslint-disable-next-line no-unsafe-finally -- Cleanup may fail only when there is no primary failure.
+                        else
+                            throw error;
+                    }
+                }
+            }), input.signal);
+        }
+    };
+}

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

@@ -0,0 +1,38 @@
+import type { PromptPart } from '../prompts/prompt-sections.js';
+import type { ExecutionMode } from '../runtime/contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+export interface ExtensionPromptFacts {
+    readonly modelId?: string;
+    readonly mode?: ExecutionMode;
+    readonly tools?: readonly string[];
+}
+export interface ExtensionPromptComposition {
+    readonly sections: readonly PromptPart[];
+    readonly facts?: ExtensionPromptFacts;
+}
+export interface ExtensionPromptSectionInput extends PromptPart {
+    readonly facts?: ExtensionPromptFacts;
+}
+export declare function normalizePromptComposition(value: unknown): ExtensionPromptComposition;
+export declare function composePromptSections(hooks: Pick<ExtensionHooks<DomainPromptCompositionOperations, DomainPromptCompositionFacts>, 'invoke' | 'emit'>, input: ExtensionPromptComposition, registered: readonly ExtensionPromptSection[], call: ExtensionOperationContext): Promise<ExtensionPromptComposition>;
+export interface DomainPromptCompositionOperations {
+    'prompt.compose': {
+        input: string;
+        output: string;
+    };
+    'prompt.sections': {
+        input: ExtensionPromptComposition;
+        output: ExtensionPromptComposition;
+    };
+    'prompt.section': {
+        input: ExtensionPromptSectionInput;
+        output: string | null;
+    };
+}
+export interface DomainPromptCompositionFacts {
+}
+export interface ExtensionPromptSection {
+    readonly id: string;
+    readonly text: string;
+}

package/dist/extensions/prompt-composition.js

@@ -0,0 +1,100 @@
+import { AgentError } from '../error.js';
+function invalid() {
+    throw new AgentError('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 AgentError('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 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/extensions/prompt-input.d.ts

@@ -0,0 +1,30 @@
+import type { RunInputImage } from '../runtime/contracts.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext } from './operation.js';
+/** Content only. Identity, queue policy and lifetime come from the physical ingress. */
+export interface ExtensionPromptInput {
+    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 ExtensionPromptResult {
+    /** An interceptor answer, not proof of queue admission or a storage write. */
+    readonly value?: unknown;
+}
+export declare function captureCorePromptInput(input: ExtensionPromptInput): ExtensionPromptInput;
+/** One admission chain for SDK input and queued Extension input, before either writer or FIFO. */
+export declare function invokeCorePromptSubmission(hooks: Pick<ExtensionHooks<DomainPromptInputOperations, DomainPromptInputFacts>, 'invoke' | 'emit'>, input: ExtensionPromptInput, call: ExtensionOperationContext, leaf: (input: ExtensionPromptInput, call: ExtensionOperationContext) => Promise<ExtensionPromptResult>): Promise<{
+    readonly entered: number;
+    readonly result: ExtensionPromptResult;
+}>;
+export interface DomainPromptInputOperations {
+    'prompt.submit': {
+        input: ExtensionPromptInput;
+        output: ExtensionPromptResult;
+    };
+}
+export interface DomainPromptInputFacts {
+}

package/dist/extensions/prompt-input.js

@@ -0,0 +1,48 @@
+import { AgentError } from '../error.js';
+import { isModelImageUrl } from '../model/image.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' &&
+                    (image.url === undefined || isModelImageUrl(image.url))))))
+        throw new AgentError('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 AgentError('MAR_AGENT_SESSION_INPUT_INVALID', 'Prompt admission result is invalid.');
+    return { entered, result };
+}

package/dist/extensions/prompts.d.ts

@@ -0,0 +1,31 @@
+import type { ModelTextBlock } from '../model/contracts.js';
+import { type PromptPart } from '../prompts/prompt-sections.js';
+import type { ExtensionHooks } from './hooks.js';
+import type { ExtensionOperationContext, ExtensionOperationRunner } from './operation.js';
+import { type ExtensionPromptComposition, type ExtensionPromptFacts, type ExtensionPromptSection, type DomainPromptCompositionOperations, type DomainPromptCompositionFacts } from './prompt-composition.js';
+import type { ExtensionResourceRegistration, ExtensionResourceScope } from './resources.js';
+import type { ExtensionSessionBackend } from './session-input.js';
+interface ExtensionPromptsApi {
+    register(section: ExtensionPromptSection): ExtensionResourceRegistration;
+    sections(): readonly ExtensionPromptSection[];
+    compose(system: string): Promise<string>;
+    composeSections(input: ExtensionPromptComposition): Promise<ExtensionPromptComposition>;
+    composeDefault(facts?: ExtensionPromptFacts): Promise<ExtensionPromptComposition>;
+}
+/** Owns Session prompt contributions and their single composition lane. */
+export declare class ExtensionPrompts {
+    #private;
+    private readonly hooks;
+    private readonly assertLive;
+    constructor(hooks: Pick<ExtensionHooks<DomainPromptCompositionOperations, DomainPromptCompositionFacts>, 'invoke' | 'emit'>, assertLive: () => void);
+    bind(scope: ExtensionResourceScope, run: ExtensionOperationRunner, backend?: Pick<ExtensionSessionBackend, 'composePrompt'>): ExtensionPromptsApi;
+    sections(): readonly ExtensionPromptSection[];
+    composeSections(input: ExtensionPromptComposition, call: ExtensionOperationContext): Promise<ExtensionPromptComposition>;
+    compose(system: string | ExtensionPromptComposition, call: ExtensionOperationContext): Promise<string>;
+    composeModelSystem(system: string | ExtensionPromptComposition, call: ExtensionOperationContext): Promise<{
+        text: string;
+        blocks?: readonly ModelTextBlock[];
+        sections?: readonly PromptPart[];
+    }>;
+}
+export {};

package/dist/extensions/prompts.js

@@ -0,0 +1,88 @@
+import { AgentError } from '../error.js';
+import { resolveModelTextBlocks } from '../model/text-blocks.js';
+import { renderPromptSections } from '../prompts/prompt-sections.js';
+import { composePromptSections, normalizePromptComposition } from './prompt-composition.js';
+/** Owns Session prompt contributions and their single composition lane. */
+export class ExtensionPrompts {
+    hooks;
+    assertLive;
+    #prompts = [];
+    constructor(hooks, assertLive) {
+        this.hooks = hooks;
+        this.assertLive = assertLive;
+    }
+    bind(scope, run, backend) {
+        return {
+            register: (input) => {
+                const section = normalizePromptComposition({ sections: [input] }).sections[0];
+                if (section.text === null)
+                    throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_INVALID', 'Prompt section is invalid.');
+                if (this.#prompts.some((entry) => entry.value.id === section.id))
+                    throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_CONFLICT', 'Prompt section id conflicts.');
+                const entry = { value: Object.freeze({ id: section.id, text: section.text }), scope };
+                const registration = scope.effect(() => () => {
+                    const index = this.#prompts.indexOf(entry);
+                    if (index !== -1)
+                        this.#prompts.splice(index, 1);
+                });
+                this.#prompts.push(entry);
+                return registration;
+            },
+            sections: () => this.sections(),
+            compose: (system) => run((call) => this.compose(system, call)),
+            composeSections: (input) => {
+                const snapshot = normalizePromptComposition(input);
+                return run((call) => this.composeSections(snapshot, call));
+            },
+            composeDefault: (facts = {}) => {
+                const snapshot = normalizePromptComposition({ sections: [], facts });
+                return run(async (call) => {
+                    if (!backend?.composePrompt)
+                        throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_UNAVAILABLE', 'Session default prompt composition is unavailable.');
+                    return this.composeSections(await backend.composePrompt(snapshot.facts, call), call);
+                });
+            }
+        };
+    }
+    sections() {
+        return this.#prompts
+            .filter((entry) => entry.scope.state === 'ACTIVE')
+            .map((entry) => entry.value);
+    }
+    composeSections(input, call) {
+        this.assertLive();
+        return composePromptSections(this.hooks, input, this.sections(), call);
+    }
+    async compose(system, call) {
+        return (await this.composeModelSystem(system, call)).text;
+    }
+    async composeModelSystem(system, call) {
+        if (typeof system !== 'string' && (system === null || typeof system !== 'object'))
+            throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_INVALID', 'Prompt composition is invalid.');
+        const input = typeof system === 'string'
+            ? { sections: [{ id: 'core:base', text: system }] }
+            : normalizePromptComposition(system);
+        const sections = await this.composeSections(input, call);
+        const composed = renderPromptSections(sections.sections);
+        const result = await this.hooks.invoke('prompt.compose', composed, call, async (value) => value);
+        call.signal.throwIfAborted();
+        if (typeof result !== 'string')
+            throw new AgentError('MAR_AGENT_EXTENSION_PROMPT_INVALID', 'Prompt composition is invalid.');
+        if (!sections.sections.some((part) => part.scope !== undefined))
+            return { text: result, sections: sections.sections };
+        const shared = sections.sections
+            .filter((part) => part.scope === 'shared' && part.text)
+            .map((part) => part.text)
+            .join('\n\n');
+        const session = sections.sections
+            .filter((part) => part.scope !== 'shared' && part.text)
+            .map((part) => part.text)
+            .join('\n\n');
+        const blocks = [];
+        if (shared)
+            blocks.push({ text: shared, cache: true });
+        if (session)
+            blocks.push({ text: `${shared ? '\n\n' : ''}${session}` });
+        return { text: result, blocks: resolveModelTextBlocks(result, blocks) };
+    }
+}

package/dist/extensions/resources.d.ts

@@ -0,0 +1,26 @@
+export type ExtensionDisposer = () => void | Promise<void>;
+export interface ExtensionResourceRegistration {
+    readonly ready: Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface ExtensionResourceScope {
+    effect(acquire: () => ExtensionDisposer | Promise<ExtensionDisposer>): ExtensionResourceRegistration;
+}
+/** An instance's managed resources, not an OS sandbox or a process-wide resource owner. */
+export declare class ExtensionResourceScope implements ExtensionResourceScope {
+    #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;
+    run<T>(operation: (signal: AbortSignal) => Promise<T>, parent?: AbortSignal): Promise<T>;
+    after(durationMs: number, callback: (signal: AbortSignal) => void | Promise<void>, onError?: (error: unknown) => void): ExtensionResourceRegistration;
+    every(durationMs: number, callback: (signal: AbortSignal) => void | Promise<void>, onError?: (error: unknown) => void): ExtensionResourceRegistration;
+    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>;
+}