@noetic-tools/core 5.3.0 → 5.4.1

package/dist/interpreter/collect-tools.js

@@ -27,7 +27,7 @@ export function deduplicateTools(tools) {
 }
 function walkStep(step, out) {
     switch (step.kind) {
-        case 'llm':
+        case 'callModel':
             // Skip function-form tools: they're resolved per execution from `ctx`
             // and cannot contribute to the pre-computed unified set. Consumers that
             // need those tools in the pool should register them via
@@ -41,30 +41,27 @@ function walkStep(step, out) {
                 }
             }
             return;
-        case 'run':
-        case 'tool':
-        // SubHarness steps run their own built-in tools inside the external agent;
-        // they contribute nothing to the host unified tool set.
-        case 'claude-code':
-        case 'codex':
-        case 'opencode':
-        case 'pi':
+        case 'runCode':
+        case 'invokeTool':
+        // An ACP agent runs its own tools inside the external agent process; it
+        // contributes nothing to the host unified tool set.
+        case 'acp-agent':
             return;
-        case 'branch':
+        case 'conditional':
             if (step._optimizable) {
                 for (const child of step._optimizable) {
                     walkStep(child, out);
                 }
             }
             return;
-        case 'fork':
+        case 'inParallel':
             if (step._optimizable) {
                 for (const child of step._optimizable) {
                     walkStep(child, out);
                 }
             }
             return;
-        case 'provide':
+        case 'withContext':
             walkStep(step.child, out);
             return;
         case 'spawn':
@@ -75,7 +72,7 @@ function walkStep(step, out) {
                 walkStep(child, out);
             }
             return;
-        case 'every':
+        case 'schedule':
             walkStep(step.step, out);
             return;
         default:

package/dist/interpreter/execute-acp-agent.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ACP step handler: drives an external coding agent over the Agent Client
+ * Protocol for one prompt turn and folds its output back into the Noetic
+ * execution context — the ACP analogue of `executeCallModel`.
+ *
+ * Core reaches the agent only through the `@noetic-tools/types` contract, so no
+ * protocol library or agent SDK enters its dependency graph.
+ */
+import type { Context, ContextLayer, StepAcpAgent } from '@noetic-tools/types';
+export declare function executeAcpAgent<TContext, I, O>(step: StepAcpAgent<TContext, I, O>, input: I, ctx: Context<TContext>, layers?: ContextLayer[]): Promise<O>;

package/dist/interpreter/execute-acp-agent.js

@@ -0,0 +1,505 @@
+/**
+ * ACP step handler: drives an external coding agent over the Agent Client
+ * Protocol for one prompt turn and folds its output back into the Noetic
+ * execution context — the ACP analogue of `executeCallModel`.
+ *
+ * Core reaches the agent only through the `@noetic-tools/types` contract, so no
+ * protocol library or agent SDK enters its dependency graph.
+ */
+import { createMessage, extractAssistantText, frameworkCast, NoeticConfigError, NoeticErrorImpl, SteeringAction, } from '@noetic-tools/types';
+import { AcpEventBridge } from './acp-events.js';
+import { withHistoryPrompt } from './acp-history.js';
+import { resolveLazy } from './execute-action.js';
+import { trackUsage } from './message-helpers.js';
+import { parseStructuredOutput } from './structured-output.js';
+import { isContextImpl, isFunctionCall, isMutableContext } from './typeguards.js';
+//#region Helpers
+/**
+ * The cross-step session store, hung off the concrete `AgentHarness` and
+ * reached via `frameworkCast`, mirroring how the interpreter reaches
+ * `layerStateStore`.
+ */
+function sessionStore(ctx) {
+    return frameworkCast(ctx.harness).acpSessions;
+}
+/**
+ * The root of the context chain. Run-scoped sessions are filed under it so
+ * concurrent runs on one harness cannot see or tear down each other's agents.
+ */
+function rootContextId(ctx) {
+    let current = ctx;
+    while (current.parent) {
+        current = frameworkCast(current.parent);
+    }
+    return current.id;
+}
+function abortSignalOf(ctx) {
+    return isContextImpl(ctx) ? ctx.abortSignal : undefined;
+}
+async function resolveAgent(step, ctx) {
+    const resolved = await resolveLazy(step.agent, ctx);
+    if (!resolved) {
+        throw new NoeticConfigError({
+            code: 'MISSING_ACP_AGENT',
+            message: `step.acpAgent(${JSON.stringify(step.id)}) resolved no agent adapter.`,
+            hint: 'Pass an agent factory result, e.g. agent: claudeCode() from @noetic-tools/acp.',
+        });
+    }
+    return resolved;
+}
+/**
+ * Build the turn's prompt content. Plain text comes first (seeded with the
+ * conversation so far on a fresh session), then any explicit content blocks.
+ */
+function buildContent(opts) {
+    const content = [];
+    if (opts.text.length > 0) {
+        content.push({
+            type: 'text',
+            text: opts.text,
+        });
+    }
+    if (opts.blocks) {
+        content.push(...opts.blocks);
+    }
+    return content;
+}
+function toLlmResponse(result) {
+    return {
+        items: result.items,
+        usage: {
+            inputTokens: result.usage?.input ?? 0,
+            outputTokens: result.usage?.output ?? 0,
+            cachedTokens: result.usage?.cached,
+        },
+        cost: result.cost,
+    };
+}
+function applyTurnResult(ctx, result) {
+    const toolCalls = [];
+    for (const item of result.items) {
+        ctx.itemLog.append(item);
+        if (isFunctionCall(item)) {
+            toolCalls.push(item);
+        }
+    }
+    const llmResponse = toLlmResponse(result);
+    trackUsage(ctx, llmResponse);
+    const meta = {
+        toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+        usage: result.usage ? llmResponse.usage : undefined,
+        cost: result.cost,
+        responseItems: result.items,
+        acpStopReason: result.stopReason,
+    };
+    if (isMutableContext(ctx)) {
+        ctx.lastStepMeta = meta;
+    }
+}
+/**
+ * Turn a stop reason into the step's outcome. A refusal and a cancellation are
+ * genuine failures with dedicated error kinds; a token or turn cap is a normal
+ * return whose reason is recorded on `lastStepMeta` for the caller to inspect.
+ */
+function assertTurnSucceeded(stepId, result, ctx) {
+    if (result.stopReason === 'cancelled') {
+        throw new NoeticErrorImpl({
+            kind: 'cancelled',
+            reason: ctx.abortReason ?? 'the ACP agent reported a cancelled turn',
+        });
+    }
+    if (result.stopReason === 'refusal') {
+        throw new NoeticErrorImpl({
+            kind: 'model_refused',
+            stepId,
+            refusal: result.text.length > 0 ? result.text : 'the ACP agent refused to continue',
+        });
+    }
+}
+//#endregion
+//#region Client host
+/**
+ * Bridge the agent's permission requests into the steering pipeline.
+ *
+ * Steering is a **veto** tier: `beforeToolCall` returns `allow` both when a rule
+ * explicitly permits the call *and* when no steering hook exists at all, so
+ * treating `allow` as decisive would silently grant every permission. Only a
+ * non-allow decision is acted on; anything else abstains and the next tier
+ * (the step's handler, then the policy default) decides.
+ */
+function buildSteerer(ctx, layers) {
+    if (!layers || layers.length === 0) {
+        return undefined;
+    }
+    return async (request) => {
+        const decision = await ctx.harness.beforeToolCall(layers, request.toolCall.title ?? request.toolCall.toolCallId, request.toolCall.rawInput, ctx);
+        if (decision.action === SteeringAction.Allow) {
+            return undefined;
+        }
+        return {
+            decision: 'deny',
+            reason: decision.guidance ?? `steering ${decision.action}`,
+        };
+    };
+}
+/**
+ * Point an existing host at the step that is about to take a turn.
+ *
+ * A connection outlives the step that opened it, so everything per-turn —
+ * permissions, steering, the async handler, the event sink — must be rebound
+ * before each turn. Without this, a session shared by several steps answers
+ * every later step with the FIRST step's policy and streams its output to the
+ * first step's (already finalized) event bridge.
+ */
+function bindHostToStep(host, opts) {
+    host.permissions = opts.step.permissions;
+    host.steerPermission = buildSteerer(opts.ctx, opts.layers);
+    // Bind the executing context into the handler so the protocol client never
+    // has to know about `Context` — it just asks a question and gets an answer.
+    const handler = opts.step.onPermissionRequest;
+    host.onPermissionRequest = handler
+        ? (request) => handler(request, opts.ctx, {
+            agentId: opts.agentId,
+            stepId: opts.step.id,
+        })
+        : undefined;
+    host.onSessionUpdate = opts.onUpdate;
+    host.onClientActivity = opts.onActivity;
+}
+function buildHost(opts) {
+    const host = {
+        cwd: opts.cwd,
+        fs: opts.ctx.fs,
+        shell: opts.ctx.shell,
+        threadId: opts.ctx.threadId,
+        signal: abortSignalOf(opts.ctx),
+        // Connection-level: ACP negotiates the capability set once, in `initialize`.
+        capabilities: opts.step.clientCapabilities,
+        onSessionUpdate: opts.onUpdate,
+        onClientActivity: opts.onActivity,
+    };
+    bindHostToStep(host, opts);
+    return host;
+}
+/**
+ * The capability set as the wire sees it, so two spellings of the same policy
+ * compare equal. Matches the defaults `clientCapabilitiesFor` applies in the
+ * protocol client — an omitted field and an explicitly-`true` one are the same
+ * request, and field order is not a difference at all.
+ */
+function normalizedCapabilities(config) {
+    return JSON.stringify({
+        readTextFile: config?.readTextFile !== false,
+        writeTextFile: config?.writeTextFile !== false,
+        terminal: config?.terminal !== false,
+        allowAnyPath: config?.allowAnyPath === true,
+        additionalDirectories: [
+            ...(config?.additionalDirectories ?? []),
+        ].sort(),
+    });
+}
+/**
+ * `cwd` and `mcpServers` are fixed when the session is created, so a step
+ * joining an existing one cannot change them either.
+ *
+ * These used to be dropped in silence while a mismatched `clientCapabilities`
+ * threw — so a step that named different MCP servers simply got none of them,
+ * with no diagnostic. Connection-scoped settings should all fail the same way.
+ */
+function assertSessionScopedSettingsMatch(step, live, cwd, servers) {
+    const conflict = (setting, hint) => new NoeticConfigError({
+        code: 'ACP_SESSION_SETTING_CONFLICT',
+        message: `step.acpAgent(${JSON.stringify(step.id)}) reuses session '${step.session?.reuse}' but requests a different ${setting} than the session was created with.`,
+        hint,
+    });
+    if (cwd !== live.cwd) {
+        throw conflict('cwd', 'A session is created in one working directory. Give every step sharing a `session.reuse` key the same `cwd`, or use a separate session.');
+    }
+    // Only a step that asks for servers can conflict; omitting them means
+    // "whatever the session already has".
+    if (servers && JSON.stringify(servers) !== JSON.stringify(live.mcpServers ?? [])) {
+        throw conflict('set of MCP servers', 'MCP servers are attached when the session is created. Give every step sharing a `session.reuse` key the same `mcpServers`, or use a separate session.');
+    }
+}
+/**
+ * `clientCapabilities` is negotiated once per connection, so a step joining an
+ * existing session cannot change it. Silently ignoring the request would hand
+ * back a session with different permissions than the step asked for, so this
+ * is a configuration error instead.
+ *
+ * Compared field by field after normalisation: comparing raw JSON made
+ * `{a,b}` conflict with `{b,a}`, and an omitted capability conflict with the
+ * default it resolves to — telling an author to make two identical policies
+ * identical.
+ */
+function assertCapabilitiesCompatible(step, live) {
+    const requested = step.clientCapabilities;
+    if (requested === undefined) {
+        return;
+    }
+    if (normalizedCapabilities(requested) === normalizedCapabilities(live.host.capabilities)) {
+        return;
+    }
+    throw new NoeticConfigError({
+        code: 'ACP_SESSION_CAPABILITY_CONFLICT',
+        message: `step.acpAgent(${JSON.stringify(step.id)}) reuses session '${step.session?.reuse}' but requests different clientCapabilities than the connection was opened with.`,
+        hint: 'ACP negotiates client capabilities once per connection. Give every step sharing a `session.reuse` key the same `clientCapabilities`, or use a separate session.',
+    });
+}
+/** Keeping a connection is always explicit; the default closes it with the step. */
+function keepAliveOf(policy) {
+    return policy?.keepAlive ?? 'step';
+}
+/**
+ * Sharing a connection only means something if the connection outlives the
+ * step. Rather than silently upgrading the scope, say so — the step is asking
+ * for two different things and has only named one.
+ */
+function assertReuseIsKeptAlive(step) {
+    const policy = step.session;
+    if (!policy?.reuse || keepAliveOf(policy) !== 'step') {
+        return;
+    }
+    throw new NoeticConfigError({
+        code: 'ACP_REUSE_WITHOUT_KEEPALIVE',
+        message: `step.acpAgent(${JSON.stringify(step.id)}) sets session.reuse '${policy.reuse}' but leaves keepAlive at 'step', so the connection closes before any other step can share it.`,
+        hint: "Add `keepAlive: 'run'` to share the connection for the rest of the run, or `keepAlive: 'harness'` to keep it past the run and close it yourself with `harness.closeAcpSessions()`.",
+    });
+}
+async function openSession(opts) {
+    const store = sessionStore(opts.baseCtx);
+    const keepAlive = keepAliveOf(opts.step.session);
+    const reuseKey = opts.step.session?.reuse;
+    const parts = {
+        keepAlive,
+        rootId: rootContextId(opts.baseCtx),
+        reuseKey,
+    };
+    // Registered under a key even without `session.reuse`: anything kept past
+    // its step has to be reachable, or nothing can ever close it.
+    const key = store.keyFor(parts);
+    const { live, fresh } = await store.acquire(key, parts, async () => {
+        const connection = await opts.agent.connect({
+            host: opts.host,
+            signal: abortSignalOf(opts.baseCtx),
+        });
+        // From here on the connection owns a live agent (usually a child process).
+        // Anything that throws before the caller can take responsibility for it
+        // must close it first — otherwise the agent outlives the step and, because
+        // its stdio keeps the event loop alive, the host never exits.
+        try {
+            const loadId = opts.step.session?.load;
+            const session = loadId
+                ? await connection.loadSession({
+                    sessionId: loadId,
+                    cwd: opts.cwd,
+                    mcpServers: opts.servers,
+                })
+                : await connection.newSession({
+                    cwd: opts.cwd,
+                    mcpServers: opts.servers,
+                });
+            return {
+                connection,
+                session,
+                host: opts.host,
+                agentId: opts.agent.agentId,
+                keepAlive,
+                cwd: opts.cwd,
+                mcpServers: opts.servers,
+            };
+        }
+        catch (e) {
+            await connection.close().catch(() => undefined);
+            throw e;
+        }
+    });
+    if (!fresh) {
+        assertSessionScopedSettingsMatch(opts.step, live, opts.cwd, opts.servers);
+        if (live.agentId !== opts.agent.agentId) {
+            throw new NoeticConfigError({
+                code: 'ACP_SESSION_AGENT_CONFLICT',
+                message: `step.acpAgent(${JSON.stringify(opts.step.id)}) reuses session '${reuseKey}', which was opened by the '${live.agentId}' agent, with a '${opts.agent.agentId}' agent.`,
+                hint: 'A reused session is one live connection to one agent. Give every step sharing a `session.reuse` key the same agent, or use separate keys.',
+            });
+        }
+        assertCapabilitiesCompatible(opts.step, live);
+        // Point the existing connection at THIS step before it takes a turn.
+        bindHostToStep(live.host, opts.binding);
+    }
+    return {
+        live,
+        key,
+        keepAlive,
+        fresh,
+    };
+}
+/**
+ * Tear the connection down per policy. Nothing is kept unless the step asked
+ * for it: only `keepAlive: 'run' | 'harness'` survives the step, and the run
+ * scope is collected by the harness when the root run finishes.
+ */
+async function finalizeSession(resolution, baseCtx) {
+    if (resolution.keepAlive !== 'step') {
+        return;
+    }
+    // Teardown must not fail a turn whose work already landed in the item log —
+    // the stdio transport throws from `close()` if the child ever errored.
+    await resolution.live.connection.close().catch(() => undefined);
+    sessionStore(baseCtx).forget(resolution.key);
+}
+//#endregion
+/**
+ * Release a connection this step opened, before surfacing a failure. A reused
+ * one is left intact for a later step to retry against.
+ */
+async function discardIfFresh(resolution, baseCtx) {
+    if (!resolution.fresh) {
+        return;
+    }
+    await resolution.live.connection.close().catch(() => undefined);
+    sessionStore(baseCtx).forget(resolution.key);
+}
+/**
+ * Apply the step's mode and model before its turn. Part of setting the turn up,
+ * so a failure tears down exactly like a failed turn rather than leaving a
+ * fresh connection holding a live agent.
+ */
+async function applySessionSelection(step, ctx, resolution, baseCtx) {
+    try {
+        const mode = await resolveLazy(step.mode, ctx);
+        if (mode) {
+            await resolution.live.session.setMode(mode);
+        }
+        const model = await resolveLazy(step.model, ctx);
+        if (model) {
+            await resolution.live.session.setModel(model);
+        }
+    }
+    catch (e) {
+        await discardIfFresh(resolution, baseCtx);
+        throw e;
+    }
+}
+/** Turn a failed turn into the step's typed error, after closing the bracket. */
+function turnFailure(step, cause, baseCtx) {
+    if (cause instanceof NoeticErrorImpl) {
+        return cause;
+    }
+    if (baseCtx.aborted) {
+        return new NoeticErrorImpl({
+            kind: 'cancelled',
+            reason: baseCtx.abortReason ?? 'context aborted',
+        });
+    }
+    return new NoeticErrorImpl({
+        kind: 'step_failed',
+        stepId: step.id,
+        cause: cause instanceof Error ? cause : new Error(String(cause)),
+        retriesExhausted: false,
+    });
+}
+//#region Public API
+export async function executeAcpAgent(step, input, ctx, layers) {
+    const baseCtx = frameworkCast(ctx);
+    assertReuseIsKeptAlive(step);
+    const agent = await resolveAgent(step, ctx);
+    const resolvedPrompt = await resolveLazy(step.prompt, ctx);
+    const blocks = await resolveLazy(step.content, ctx);
+    const promptText = resolvedPrompt && resolvedPrompt.length > 0
+        ? resolvedPrompt
+        : typeof input === 'string'
+            ? input
+            : '';
+    if (promptText.trim() === '' && (!blocks || blocks.length === 0)) {
+        throw new NoeticConfigError({
+            code: 'MISSING_PROMPT',
+            message: `step.acpAgent(${JSON.stringify(step.id)}) resolved an empty prompt.`,
+            hint: 'Provide a non-empty `prompt` or `content`, or pass a string input to the step.',
+        });
+    }
+    const cwd = (await resolveLazy(step.cwd, ctx)) ?? baseCtx.cwdState.cwd;
+    const servers = await resolveLazy(step.mcpServers, ctx);
+    // Capture the conversation so far BEFORE appending this turn's prompt, so a
+    // fresh session can be seeded with it and the agent is not left guessing at
+    // what earlier steps established.
+    const priorHistory = [
+        ...baseCtx.itemLog.items,
+    ];
+    if (promptText.length > 0) {
+        baseCtx.itemLog.append(createMessage(promptText, 'user'));
+    }
+    const bridge = new AcpEventBridge(step, agent.agentId, baseCtx);
+    const binding = {
+        step,
+        ctx: baseCtx,
+        agentId: agent.agentId,
+        layers,
+        onUpdate: (notification) => {
+            bridge.forward(notification);
+        },
+        onActivity: (activity) => {
+            bridge.forwardActivity(activity);
+        },
+    };
+    const host = buildHost({
+        ...binding,
+        cwd,
+    });
+    const resolution = await openSession({
+        step,
+        agent,
+        baseCtx,
+        cwd,
+        host,
+        binding,
+        servers: servers
+            ? [
+                ...servers,
+            ]
+            : undefined,
+    });
+    await applySessionSelection(step, ctx, resolution, baseCtx);
+    bridge.begin();
+    let result;
+    try {
+        result = await resolution.live.session.prompt({
+            content: buildContent({
+                // History seeds only a freshly opened session; a reused one already
+                // owns its conversation on the agent side.
+                text: resolution.fresh
+                    ? withHistoryPrompt({
+                        prompt: promptText,
+                        history: priorHistory,
+                    })
+                    : promptText,
+                blocks,
+            }),
+            // Per-turn signal, so a session reused across turns is cancelled by the
+            // context running the CURRENT turn rather than the one that opened it.
+            signal: abortSignalOf(baseCtx),
+        });
+    }
+    catch (e) {
+        // Close the turn on the event surface before rethrowing. A consumer driving
+        // a UI off `getFullStream()` saw `response.created` and would otherwise
+        // wait forever for a completion that never comes — the stream just stops.
+        bridge.abort(e);
+        await discardIfFresh(resolution, baseCtx);
+        throw turnFailure(step, e, baseCtx);
+    }
+    bridge.finalize(result);
+    applyTurnResult(baseCtx, result);
+    await finalizeSession(resolution, baseCtx);
+    assertTurnSucceeded(step.id, result, baseCtx);
+    const lastText = result.text.length > 0 ? result.text : extractAssistantText(result.items);
+    if (step.output) {
+        return parseStructuredOutput({
+            schema: step.output,
+            rawText: lastText,
+            stepId: step.id,
+        });
+    }
+    return frameworkCast(lastText);
+}
+//#endregion

package/dist/interpreter/execute-action.d.ts

@@ -2,8 +2,8 @@
  * Action step handlers: run, llm, spawn, provide, tool.
  */
 import type { ItemSchemaRegistry, LayerStateStore } from './action-deps.js';
-import type { AgentHarnessContract, Context, ContextLayer, ExecuteStepFn, StepLLM, StepProvide, StepRun, StepSpawn, StepTool } from './action-types.js';
-export declare function executeRun<TContext, I, O>(step: StepRun<TContext, I, O>, input: I, ctx: Context<TContext>): Promise<O>;
+import type { AgentHarnessContract, Context, ContextLayer, ExecuteStepFn, StepCallModel, StepInvokeTool, StepRunCode, StepSpawn, StepWithContext } from './action-types.js';
+export declare function executeRunCode<TContext, I, O>(step: StepRunCode<TContext, I, O>, input: I, ctx: Context<TContext>): Promise<O>;
 /**
  * Resolves a `Lazy<T>` step field. If the value is a function, it is invoked
  * with the current context; otherwise the value is returned as-is. Supports
@@ -14,7 +14,7 @@ export declare function executeRun<TContext, I, O>(step: StepRun<TContext, I, O>
  * tools) without baking them in at build time.
  */
 export declare function resolveLazy<T, TContext>(value: T | ((ctx: Context<TContext>) => T | Promise<T>), ctx: Context<TContext>): Promise<T>;
-export declare function executeLLM<TContext, I, O>(step: StepLLM<TContext, I, O>, input: I, ctx: Context<TContext>, layers?: ContextLayer[]): Promise<O>;
+export declare function executeCallModel<TContext, I, O>(step: StepCallModel<TContext, I, O>, input: I, ctx: Context<TContext>, layers?: ContextLayer[]): Promise<O>;
 export interface ExecuteSpawnOpts {
     layerStore?: LayerStateStore;
     parentLayers?: ContextLayer[];
@@ -28,5 +28,5 @@ export declare function executeSpawn<TContext, I, O>(step: StepSpawn<TContext, I
  * Unlike spawn, provide does not create a new itemLog or clone state.
  * Events flow through to the parent in real-time.
  */
-export declare function executeProvide<TContext, I, O>(step: StepProvide<TContext, I, O>, input: I, ctx: Context<TContext>, executeStep: ExecuteStepFn): Promise<O>;
-export declare function executeTool<TContext, I, O>(step: StepTool<TContext, I, O>, input: I, ctx: Context<TContext>, harness: AgentHarnessContract, layers?: ContextLayer[]): Promise<O>;
+export declare function executeWithContext<TContext, I, O>(step: StepWithContext<TContext, I, O>, input: I, ctx: Context<TContext>, executeStep: ExecuteStepFn): Promise<O>;
+export declare function executeInvokeTool<TContext, I, O>(step: StepInvokeTool<TContext, I, O>, input: I, ctx: Context<TContext>, harness: AgentHarnessContract, layers?: ContextLayer[]): Promise<O>;