@myagentroam/agent 0.9.158 → 0.9.160

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

@@ -0,0 +1,115 @@
+import { MarAgentError } from '../error.js';
+import { cloneCoreJson } from './data.js';
+export function coreSettingsBinding(bindings) {
+    const backend = bindings?.['settings'];
+    if (backend === undefined)
+        return undefined;
+    if (!backend ||
+        typeof backend !== 'object' ||
+        ['describe', 'read', 'update'].some((name) => typeof backend[name] !== 'function'))
+        throw new MarAgentError('MAR_AGENT_SETTINGS_BINDING_INVALID', 'Settings binding must provide describe, read and update.');
+    return backend;
+}
+export function settingsCapabilities(base, bound) {
+    const list = Object.freeze([
+        ...base.list().filter((id) => id !== 'settings'),
+        ...(bound ? ['settings'] : [])
+    ]);
+    return Object.freeze({ has: (id) => list.includes(id), list: () => list });
+}
+function copyInput(input) {
+    if (!input ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        (input.scope !== undefined && (typeof input.scope !== 'string' || !input.scope)))
+        throw invalid('INPUT');
+    if ('key' in input) {
+        const update = input;
+        if (typeof update.key !== 'string' ||
+            !update.key ||
+            (update.expectedRevision !== undefined &&
+                (!Number.isSafeInteger(update.expectedRevision) || update.expectedRevision < 0)))
+            throw invalid('INPUT');
+        try {
+            return { ...input, value: cloneCoreJson(update.value) };
+        }
+        catch {
+            throw invalid('INPUT');
+        }
+    }
+    return { ...input };
+}
+function copyOutput(value) {
+    try {
+        return cloneCoreJson(value);
+    }
+    catch {
+        throw invalid('OUTPUT');
+    }
+}
+function invalid(kind) {
+    return new MarAgentError(`MAR_AGENT_SETTINGS_${kind}_INVALID`, `Settings ${kind === 'INPUT' ? 'input' : 'result'} is invalid.`);
+}
+function object(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+export function bindCoreSettings(backend, run, hooks) {
+    const invoke = async (name, raw) => {
+        const input = copyInput(raw);
+        return run((call) => hooks.invoke(`settings.${name}`, input, call, async (candidate, effective) => {
+            const supplied = copyInput(candidate);
+            if (name === 'update' && (!('key' in supplied) || !('value' in supplied)))
+                throw invalid('INPUT');
+            if (typeof backend[name] !== 'function')
+                throw new MarAgentError('MAR_AGENT_HOST_PORT_UNAVAILABLE', 'Bound settings operation is unavailable.', { details: { operation: name } });
+            const handler = backend[name];
+            const output = copyOutput(await handler.call(backend, supplied, effective));
+            if (!object(output) ||
+                !Number.isSafeInteger(output['revision']) ||
+                output['revision'] < 0)
+                throw invalid('OUTPUT');
+            if (name === 'describe') {
+                const definitions = output['definitions'];
+                if (!Array.isArray(definitions) ||
+                    definitions.some((item) => !object(item) ||
+                        typeof item['key'] !== 'string' ||
+                        !item['key'] ||
+                        typeof item['source'] !== 'string' ||
+                        typeof item['writable'] !== 'boolean' ||
+                        (item['sensitive'] !== undefined && typeof item['sensitive'] !== 'boolean') ||
+                        (item['label'] !== undefined && typeof item['label'] !== 'string') ||
+                        (item['owner'] !== undefined && typeof item['owner'] !== 'string') ||
+                        (typeof item['schema'] !== 'boolean' && !object(item['schema']))) ||
+                    new Set(definitions.map((item) => item.key)).size !==
+                        definitions.length)
+                    throw invalid('OUTPUT');
+            }
+            else if (name === 'read') {
+                if (!object(output['values']))
+                    throw invalid('OUTPUT');
+            }
+            else if (!['updated', 'unchanged', 'denied'].includes(String(output['status'])) ||
+                (output['status'] === 'denied'
+                    ? !object(output['reason']) ||
+                        typeof output['reason']['code'] !== 'string' ||
+                        !output['reason']['code'] ||
+                        typeof output['reason']['message'] !== 'string'
+                    : !('value' in output)))
+                throw invalid('OUTPUT');
+            await hooks.emit('settings.completed', {
+                operation: name,
+                revision: output['revision'],
+                ...(supplied.scope === undefined ? {} : { scope: supplied.scope }),
+                ...(name === 'update'
+                    ? { status: output['status'] }
+                    : {})
+            }, effective);
+            return output;
+        }), input.signal);
+    };
+    return {
+        describe: (input = {}) => invoke('describe', input),
+        read: (input = {}) => invoke('read', input),
+        update: (input) => invoke('update', input)
+    };
+}

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

@@ -0,0 +1,10 @@
+import { type CoreStoreApi } from './data.js';
+type StoreRun = <T>(operation: (signal: AbortSignal) => Promise<T>) => Promise<T>;
+/** One application-bound installation namespace, independent from Session JSONL or Code Mode state. */
+export declare class ExtensionStore {
+    #private;
+    readonly directory: string;
+    constructor(directory: string);
+    bind(run: StoreRun): CoreStoreApi;
+}
+export {};

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

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { MarAgentError } from '../error.js';
+import { acquireFileLock } from '../storage/file-lock.js';
+import { cloneCoreJson } from './data.js';
+/** One application-bound installation namespace, independent from Session JSONL or Code Mode state. */
+export class ExtensionStore {
+    directory;
+    #path;
+    constructor(directory) {
+        this.directory = directory;
+        if (typeof directory !== 'string' || !isAbsolute(directory))
+            throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_INVALID', 'Extension store requires an absolute data directory.');
+        this.#path = join(directory, 'core-store.json');
+    }
+    bind(run) {
+        const commit = (input) => run((signal) => this.#commit(input, signal));
+        return {
+            get: ({ key }) => run(async (signal) => {
+                validateKey(key);
+                const document = await this.#read(signal);
+                const value = Object.hasOwn(document.values, key) ? document.values[key] : undefined;
+                return {
+                    revision: document.revision,
+                    ...(value === undefined ? {} : { value: cloneCoreJson(value) })
+                };
+            }),
+            keys: () => run(async (signal) => {
+                const document = await this.#read(signal);
+                return { revision: document.revision, keys: Object.keys(document.values).sort() };
+            }),
+            set: async ({ key, value, expectedRevision }) => {
+                const copied = cloneCoreJson(value);
+                const result = await commit({
+                    writes: [{ key, value: copied }],
+                    ...(expectedRevision === undefined ? {} : { expectedRevision })
+                });
+                return { revision: result.revision, value: copied };
+            },
+            delete: ({ key, expectedRevision }) => commit({
+                writes: [{ key }],
+                ...(expectedRevision === undefined ? {} : { expectedRevision })
+            }),
+            commit
+        };
+    }
+    async #read(signal) {
+        signal.throwIfAborted();
+        let text;
+        try {
+            text = await readFile(this.#path, { encoding: 'utf8', signal });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { revision: 0, values: {} };
+            throw error;
+        }
+        signal.throwIfAborted();
+        try {
+            const value = JSON.parse(text);
+            if (!value ||
+                !Number.isSafeInteger(value.revision) ||
+                value.revision < 0 ||
+                !value.values ||
+                typeof value.values !== 'object' ||
+                Array.isArray(value.values))
+                throw new Error();
+            const values = cloneCoreJson(value.values);
+            return { revision: value.revision, values };
+        }
+        catch {
+            throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_CORRUPT', 'Extension store document is invalid.');
+        }
+    }
+    async #commit(input, signal) {
+        if (!input ||
+            !Array.isArray(input.writes) ||
+            (input.expectedRevision !== undefined &&
+                (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0)))
+            throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_INVALID', 'Store mutation or expected revision is invalid.');
+        const writes = input.writes.map((write) => {
+            if (!write || typeof write !== 'object')
+                throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_INVALID', 'Store mutation is invalid.');
+            const { key, value } = write;
+            validateKey(key);
+            return { key, ...(value === undefined ? {} : { value: cloneCoreJson(value) }) };
+        });
+        signal.throwIfAborted();
+        await mkdir(this.directory, { recursive: true });
+        const release = await acquireFileLock(join(this.directory, 'core-store.lock'), 'Extension store is busy.', 5000, { signal, code: 'MAR_AGENT_EXTENSION_STORE_LOCKED' });
+        const temporary = join(this.directory, `.core-store-${randomUUID()}.tmp`);
+        try {
+            const document = await this.#read(signal);
+            if (input.expectedRevision !== undefined && document.revision !== input.expectedRevision)
+                throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_CONFLICT', 'Store revision changed before commit.');
+            const values = Object.assign(Object.create(null), document.values);
+            for (const { key, value } of writes)
+                if (value === undefined)
+                    delete values[key];
+                else
+                    values[key] = value;
+            const revision = document.revision + 1;
+            if (!Number.isSafeInteger(revision))
+                throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_INVALID', 'Store revision is exhausted.');
+            const handle = await open(temporary, 'wx', 0o600);
+            try {
+                await handle.writeFile(JSON.stringify({ revision, values }));
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            signal.throwIfAborted();
+            await rename(temporary, this.#path);
+            return { revision };
+        }
+        finally {
+            try {
+                await rm(temporary, { force: true });
+            }
+            finally {
+                await release();
+            }
+        }
+    }
+}
+function validateKey(key) {
+    if (typeof key !== 'string')
+        throw new MarAgentError('MAR_AGENT_EXTENSION_STORE_INVALID', 'Store key must be a string.');
+}

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

@@ -0,0 +1,61 @@
+import type { ClientToolDefinition, McpCatalogTool, ToolCall, ToolExecutionResult } from '../tools/contracts.js';
+import type { CoreCallbackRunner, CoreOperationContext } from './operation.js';
+import { ExtensionResourceScope, type CoreResourceRegistration } from './resources.js';
+export interface CoreToolSpec extends ClientToolDefinition {
+    readonly override?: 'replace' | 'wrap';
+    /** Optional native validator/parser for schema features outside the built-in converter. */
+    readonly parseInput?: (input: unknown) => unknown | Promise<unknown>;
+    readonly validateOutput?: (data: unknown) => void | Promise<void>;
+    execute(input: unknown, call: CoreOperationContext, next: (input: unknown) => Promise<ToolExecutionResult>): ToolExecutionResult | Promise<ToolExecutionResult>;
+}
+export interface CoreToolRef {
+    readonly mcp?: McpCatalogTool;
+    readonly definition: ClientToolDefinition;
+    readonly source: Readonly<{
+        id: string;
+        revision: string;
+        kind: 'builtin' | 'host' | 'mcp' | 'extension';
+        instanceId?: string;
+    }>;
+}
+export interface CoreToolInvocation extends ToolCall {
+    readonly ref?: CoreToolRef;
+}
+export interface CoreToolCheck {
+    readonly available: boolean;
+    readonly code?: string;
+    readonly source?: CoreToolRef['source'];
+}
+export interface CoreToolAttempt {
+    readonly attemptId: string;
+    readonly parentAttemptId?: string;
+    readonly name: string;
+    readonly callId?: string;
+    readonly stage: 'leaf' | 'wrapper' | 'result';
+    readonly source?: CoreToolRef['source'];
+}
+export interface CoreToolCompletion extends CoreToolAttempt {
+    readonly result: ToolExecutionResult;
+}
+export interface CoreToolFailure extends CoreToolAttempt {
+    readonly status: 'failed' | 'cancelled';
+    readonly errorCode: string;
+}
+export interface CoreToolBinding extends CoreToolRef {
+    readonly mcp?: McpCatalogTool;
+    registered?(): boolean;
+    available?(context: CoreOperationContext): boolean;
+    invoke(call: ToolCall, context: CoreOperationContext): Promise<ToolExecutionResult>;
+}
+/** Builds one immutable catalog from real sources; snapshots keep their captured handlers. */
+export declare class ExtensionTools {
+    #private;
+    readonly trace: (binding: CoreToolBinding, stage: 'leaf' | 'wrapper') => CoreToolBinding;
+    readonly callback: CoreCallbackRunner;
+    constructor(trace?: (binding: CoreToolBinding, stage: 'leaf' | 'wrapper') => CoreToolBinding, callback?: CoreCallbackRunner);
+    get revision(): number;
+    /** Internal bridge for a real owner-bound backend, not an author-supplied handler authority. */
+    contributeSource(owner: ExtensionResourceScope, source: CoreToolBinding): CoreResourceRegistration;
+    register(owner: ExtensionResourceScope, id: string, spec: CoreToolSpec): CoreResourceRegistration;
+    capture(base?: readonly CoreToolBinding[], includeStaged?: boolean): ReadonlyMap<string, CoreToolBinding>;
+}

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

@@ -0,0 +1,266 @@
+import { randomUUID } from 'node:crypto';
+import { MarAgentError } from '../error.js';
+import { toolCallers } from '../tools/callers.js';
+import { fromJSONSchema } from 'zod';
+import { ExtensionResourceScope } from './resources.js';
+/** Builds one immutable catalog from real sources; snapshots keep their captured handlers. */
+export class ExtensionTools {
+    trace;
+    callback;
+    #entries = [];
+    #sources = [];
+    #revision = 0;
+    constructor(trace = (binding) => binding, callback = async (call, run) => run(call)) {
+        this.trace = trace;
+        this.callback = callback;
+    }
+    get revision() {
+        return this.#revision;
+    }
+    /** Internal bridge for a real owner-bound backend, not an author-supplied handler authority. */
+    contributeSource(owner, source) {
+        const entry = {
+            owner,
+            binding: Object.freeze({
+                ...source,
+                definition: deepFreeze(copyDefinition(source.definition)),
+                source: Object.freeze({ ...source.source }),
+                ...(source.mcp === undefined ? {} : { mcp: deepFreeze(structuredClone(source.mcp)) })
+            })
+        };
+        const registration = owner.effect(() => () => {
+            const index = this.#sources.indexOf(entry);
+            if (index !== -1) {
+                this.#sources.splice(index, 1);
+                this.#revision++;
+            }
+        });
+        this.#sources.push(entry);
+        this.#revision++;
+        return registration;
+    }
+    register(owner, id, spec) {
+        if (typeof spec.name !== 'string' ||
+            !spec.name.trim() ||
+            typeof spec.description !== 'string' ||
+            typeof spec.execute !== 'function' ||
+            !spec.inputSchema ||
+            typeof spec.inputSchema !== 'object' ||
+            Array.isArray(spec.inputSchema) ||
+            (spec.override !== undefined && spec.override !== 'replace' && spec.override !== 'wrap'))
+            throw new MarAgentError('MAR_AGENT_EXTENSION_TOOL_INVALID', 'Extension tool definition or handler is invalid.');
+        const definition = copyDefinition(spec);
+        const parse = spec.parseInput ?? schemaValidator(spec.inputSchema, 'MAR_AGENT_TOOL_INPUT_INVALID');
+        const validateOutput = spec.validateOutput ??
+            (spec.outputSchema
+                ? schemaValidator(spec.outputSchema, 'MAR_AGENT_TOOL_OUTPUT_INVALID')
+                : undefined);
+        toolCallers({
+            ...definition,
+            allowedCallers: spec.allowedCallers ?? ['direct', 'programmatic']
+        });
+        const entry = {
+            owner,
+            id,
+            revision: randomUUID(),
+            parse,
+            ...(validateOutput ? { validateOutput } : {}),
+            spec: Object.freeze({
+                ...definition,
+                ...(spec.override ? { override: spec.override } : {}),
+                execute: spec.execute
+            })
+        };
+        const registration = owner.effect(() => () => {
+            const index = this.#entries.indexOf(entry);
+            if (index !== -1) {
+                this.#entries.splice(index, 1);
+                this.#revision++;
+            }
+        });
+        this.#entries.push(entry);
+        this.#revision++;
+        return registration;
+    }
+    capture(base = [], includeStaged = false) {
+        const bindings = new Map();
+        const sources = this.#sources
+            .filter(({ owner }) => owner.state === 'ACTIVE' || (includeStaged && owner.state === 'STAGED'))
+            .filter(({ binding }) => binding.registered?.() !== false)
+            .map(({ binding }) => binding);
+        for (const original of [...base, ...sources]) {
+            const binding = Object.freeze({
+                ...original,
+                definition: deepFreeze(copyDefinition(original.definition)),
+                source: Object.freeze({ ...original.source }),
+                ...(original.mcp === undefined ? {} : { mcp: deepFreeze(structuredClone(original.mcp)) })
+            });
+            if (bindings.has(binding.definition.name))
+                throw new MarAgentError('MAR_AGENT_EXTENSION_TOOL_CONFLICT', 'Tool sources conflict.');
+            bindings.set(binding.definition.name, this.trace(binding, 'leaf'));
+        }
+        for (const entry of this.#entries) {
+            if (entry.owner.state !== 'ACTIVE' && !(includeStaged && entry.owner.state === 'STAGED'))
+                continue;
+            if (this.#entries
+                .slice(this.#entries.indexOf(entry) + 1)
+                .some((later) => later.owner === entry.owner && later.spec.name === entry.spec.name))
+                continue;
+            const lower = bindings.get(entry.spec.name);
+            if (lower && !entry.spec.override)
+                throw new MarAgentError('MAR_AGENT_EXTENSION_TOOL_CONFLICT', 'Tool replacement must be explicit.');
+            if (!lower && entry.spec.override === 'wrap') {
+                if (entry.owner.state === 'ACTIVE')
+                    continue;
+                throw new MarAgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Tool wrapper has no lower implementation.');
+            }
+            const definition = copyDefinition(entry.spec);
+            definition.allowedCallers ??= lower
+                ? (lower.definition.allowedCallers ??
+                    (lower.source.kind === 'mcp' ? ['direct', 'programmatic'] : ['direct']))
+                : ['direct', 'programmatic'];
+            if (entry.spec.override === 'wrap' && lower?.definition.agentScope !== undefined)
+                definition.agentScope ??= lower.definition.agentScope;
+            const binding = Object.freeze({
+                definition: deepFreeze(definition),
+                ...(entry.spec.override === 'wrap' && lower?.mcp ? { mcp: lower.mcp } : {}),
+                source: Object.freeze({
+                    kind: 'extension',
+                    id: entry.id,
+                    revision: entry.revision,
+                    instanceId: entry.owner.instanceId
+                }),
+                available: () => entry.owner.state === 'ACTIVE' ||
+                    (entry.owner.state === 'STAGED' && ExtensionResourceScope.initializing),
+                invoke: async (call, context) => entry.owner.run((signal) => this.callback(Object.freeze({ ...context, signal, ownerInstanceId: entry.owner.instanceId }), async (context) => {
+                    const signal = context.signal;
+                    const input = await entry.parse(call.arguments);
+                    signal.throwIfAborted();
+                    const controller = new AbortController();
+                    const effective = AbortSignal.any([signal, controller.signal]);
+                    const pending = new Set();
+                    let open = true;
+                    let output;
+                    try {
+                        output = await entry.spec.execute(input, Object.freeze({
+                            ...context,
+                            signal: effective,
+                            ownerInstanceId: entry.owner.instanceId
+                        }), (input) => {
+                            const result = Promise.resolve().then(() => {
+                                effective.throwIfAborted();
+                                if (!open)
+                                    throw new MarAgentError('MAR_AGENT_TOOL_NOT_AVAILABLE', 'Tool continuation has finished.');
+                                if (!lower || entry.spec.override !== 'wrap')
+                                    throw new MarAgentError('MAR_AGENT_EXTENSION_DEPENDENCY_MISSING', 'Tool has no wrapper continuation.');
+                                return lower.invoke({ ...call, arguments: input }, Object.freeze({ ...context, signal: effective }));
+                            });
+                            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]);
+                        open = false;
+                    }
+                    if (!output || typeof output.content !== 'string')
+                        throw new MarAgentError('MAR_AGENT_TOOL_OUTPUT_INVALID', 'Tool result must contain string content.');
+                    await entry.validateOutput?.(output.data);
+                    return output;
+                }), context.signal)
+            });
+            bindings.set(definition.name, this.trace(binding, entry.spec.override === 'wrap' ? 'wrapper' : 'leaf'));
+        }
+        const view = Object.freeze({
+            get size() {
+                return bindings.size;
+            },
+            get: (name) => bindings.get(name),
+            has: (name) => bindings.has(name),
+            entries: () => bindings.entries(),
+            keys: () => bindings.keys(),
+            values: () => bindings.values(),
+            [Symbol.iterator]: () => bindings[Symbol.iterator](),
+            forEach: (callback, thisArg) => {
+                for (const [key, value] of bindings)
+                    callback.call(thisArg, value, key, view);
+            }
+        });
+        return view;
+    }
+}
+function schemaValidator(schema, code) {
+    let validator;
+    try {
+        validator = fromJSONSchema(withoutDefaults(schema));
+    }
+    catch {
+        throw new MarAgentError('MAR_AGENT_EXTENSION_TOOL_SCHEMA_UNSUPPORTED', 'Schema requires an explicit native parser.');
+    }
+    return (input) => {
+        if (!validator.safeParse(input).success)
+            throw new MarAgentError(code, 'Tool value does not match its declared schema.');
+        return input;
+    };
+}
+/** JSON Schema defaults are annotations, not permission to insert missing input values. */
+function withoutDefaults(schema) {
+    if (typeof schema === 'boolean')
+        return schema;
+    const copied = structuredClone(schema);
+    delete copied.default;
+    for (const key of ['properties', 'patternProperties', '$defs', 'definitions']) {
+        const children = copied[key];
+        if (children && typeof children === 'object')
+            for (const [name, child] of Object.entries(children)) {
+                if (child && typeof child === 'object' && !Array.isArray(child))
+                    children[name] = withoutDefaults(child);
+            }
+    }
+    for (const key of ['anyOf', 'allOf', 'oneOf', 'prefixItems', 'items']) {
+        const children = copied[key];
+        if (Array.isArray(children))
+            copied[key] = children.map((child) => withoutDefaults(child));
+    }
+    for (const key of [
+        'items',
+        'additionalItems',
+        'additionalProperties',
+        'contains',
+        'not',
+        'propertyNames'
+    ]) {
+        const child = copied[key];
+        if (child && typeof child === 'object' && !Array.isArray(child))
+            copied[key] = withoutDefaults(child);
+    }
+    return copied;
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function copyDefinition(spec) {
+    return {
+        name: spec.name,
+        description: spec.description,
+        inputSchema: structuredClone(spec.inputSchema),
+        ...(spec.nativeType ? { nativeType: spec.nativeType } : {}),
+        ...(spec.outputSchema ? { outputSchema: structuredClone(spec.outputSchema) } : {}),
+        ...(spec.allowedCallers ? { allowedCallers: [...spec.allowedCallers] } : {}),
+        ...(spec.inputMode ? { inputMode: spec.inputMode } : {}),
+        ...(spec.parallelSafety ? { parallelSafety: spec.parallelSafety } : {}),
+        ...(spec.agentScope ? { agentScope: spec.agentScope } : {})
+    };
+}

package/dist/agent-core/host/contracts.d.ts

@@ -1,5 +1,11 @@
 import type { MarAgentEvent } from '../runtime/events.js';
 import type { ClientToolDefinition, McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
+import type { CoreFilesBackend } from '../extensions/files.js';
+import type { CoreNetworkBackend } from '../extensions/network.js';
+import type { CoreProcessesBackend } from '../extensions/processes.js';
+import type { CoreEnvironmentBackend } from '../extensions/environment.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
+import type { CoreToolRef } from '../extensions/tools.js';
 export declare const MAR_AGENT_HOST_API_VERSION = "1.0";
 export type MarAgentHostCapability = 'workspace.read' | 'workspace.patch' | 'process.manage' | 'code.execute' | 'user-input.request' | 'event.publish' | 'session.store' | 'mcp.tools' | 'image.read';
 export interface HostDescription {
@@ -47,9 +53,11 @@ export interface HostSessionResourceSnapshot {
 }
 /** The Host owns workspace/tool effects; the SDK owns JSONL storage beneath its supplied HOME. */
 export interface MarAgentHost {
+    readonly extensionPorts?: CoreHostExtensionPorts;
     describe(): Promise<HostDescription>;
     executeTool(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
     listExecutionExtensions?(context: McpToolCatalogContext): Promise<HostExecutionExtensions>;
+    listSessionSkills?(context: Pick<McpToolCatalogContext, 'sessionId' | 'modelId'>): Promise<readonly HostSkill[]>;
     emit(event: MarAgentEvent): Promise<void> | void;
     requestUserInput?(input: {
         requestId: string;
@@ -62,3 +70,20 @@ export interface MarAgentHost {
     disposeSessionResources?(sessionId: string): Promise<void>;
     dispose(): Promise<void>;
 }
+export interface CoreHostExtensionPorts {
+    readonly tools?: CoreHostToolsBackend;
+    readonly mcp?: import('../extensions/mcp.js').CoreMcpBackend;
+    readonly environment?: CoreEnvironmentBackend;
+    readonly processes?: CoreProcessesBackend;
+    readonly network?: CoreNetworkBackend;
+    readonly files?: CoreFilesBackend;
+}
+/** A captured application-owned handler, never author-supplied invocation authority. */
+export interface CoreHostToolSource extends CoreToolRef {
+    readonly mcp?: import('../tools/contracts.js').McpCatalogTool;
+    available?(call: CoreOperationContext): boolean;
+    execute(input: ToolCall, call: CoreOperationContext): Promise<ToolExecutionResult>;
+}
+export interface CoreHostToolsBackend {
+    catalog(sessionId: string, executionId?: string): readonly CoreHostToolSource[];
+}

package/dist/agent-core/host/local-agent-host.d.ts

@@ -2,8 +2,10 @@ import type { MarAgentEvent } from '../runtime/events.js';
 import type { CodeModeEngineFactory } from '../tools/code-mode/engine.js';
 import type { McpToolCallContext, McpToolCatalog, McpToolCatalogContext, ToolCall, ToolExecutionContext, ToolExecutionResult } from '../tools/contracts.js';
 import type { WorkspacePathMount } from '../tools/shared/path-resolver.js';
-import type { HostDescription, HostExecutionExtensions, MarAgentHost } from './contracts.js';
+import type { HostDescription, HostExecutionExtensions, HostSkill, MarAgentHost, CoreHostToolsBackend } from './contracts.js';
+import type { CoreNetworkBackend } from '../extensions/network.js';
 import { type LocalProcessExecutor } from './local-process-executor.js';
+import type { CoreOperationContext } from '../extensions/operation.js';
 export interface LocalAgentMcpBinding {
     readonly tools: readonly import('../model/contracts.js').ClientToolDefinition[];
     readonly catalog?: () => McpToolCatalog;
@@ -21,8 +23,14 @@ export interface LocalAgentExecutionExtensions extends HostExecutionExtensions {
 }
 export declare class LocalAgentHost implements MarAgentHost {
     #private;
+    readonly extensionPorts: import('./contracts.js').CoreHostExtensionPorts;
     readonly events: MarAgentEvent[];
     constructor(input: {
+        mcp?: import('../extensions/mcp.js').CoreMcpBackend;
+        operationTools?: CoreHostToolsBackend;
+        beforeOperationToolExecute?: (input: ToolCall, call: CoreOperationContext) => Promise<void> | void;
+        callMcpOperation?: (input: ToolCall, call: CoreOperationContext, expected: NonNullable<McpToolCallContext['expectedTool']>) => Promise<ToolExecutionResult>;
+        network?: CoreNetworkBackend | false;
         homeDirectory: string;
         workspace: string;
         mode?: 'normal' | 'node';
@@ -48,6 +56,7 @@ export declare class LocalAgentHost implements MarAgentHost {
     executeTool(call: ToolCall, context: ToolExecutionContext): Promise<ToolExecutionResult>;
     bindExecutionExtensions(extensions: LocalAgentExecutionExtensions, mcp?: LocalAgentMcpBinding): LocalAgentExecutionMcpBinding;
     listExecutionExtensions(context: McpToolCatalogContext): Promise<HostExecutionExtensions>;
+    listSessionSkills(_context: Pick<McpToolCatalogContext, 'sessionId' | 'modelId'>): Promise<readonly HostSkill[]>;
     emit(event: MarAgentEvent): void;
     requestUserInput(input: {
         requestId: string;