@noetic-tools/core 5.4.0 → 5.4.2

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.js

@@ -2,9 +2,9 @@ import { frameworkCast, NoeticErrorImpl } from '@noetic-tools/types';
 import { emitFrameworkEvent, getBroadcaster, shouldEmit } from '../runtime/broadcaster-utils.js';
 import { ContextImpl } from '../runtime/context-impl.js';
 import { DetachedHandleImpl } from '../util/detached-handle.js';
+import { executeAcpAgent } from './execute-acp-agent.js';
 import { executeCallModel, executeInvokeTool, executeRunCode, executeSpawn, executeWithContext, } from './execute-action.js';
 import { executeConditional, executeInParallel, executeLoop, executeSchedule, } from './execute-control.js';
-import { executeSubHarness } from './execute-sub-harness.js';
 import { isMutableContext } from './typeguards.js';
 //#region Constants
 const MAX_DEPTH = 64;
@@ -35,11 +35,7 @@ function buildSpawnOpts(ctx) {
  * step kinds carry an `emit` field; every other kind defaults to enabled.
  */
 function resolveStepEmit(step) {
-    if (step.kind === 'callModel' ||
-        step.kind === 'claude-code' ||
-        step.kind === 'codex' ||
-        step.kind === 'opencode' ||
-        step.kind === 'pi') {
+    if (step.kind === 'callModel' || step.kind === 'acp-agent') {
         return step.emit;
     }
     return undefined;
@@ -258,11 +254,8 @@ export async function execute(step, input, ctx) {
             case 'callModel':
                 result = await executeCallModel(step, input, ctx, baseCtx.layers);
                 break;
-            case 'claude-code':
-            case 'codex':
-            case 'opencode':
-            case 'pi':
-                result = await executeSubHarness(step, input, ctx);
+            case 'acp-agent':
+                result = await executeAcpAgent(step, input, ctx, baseCtx.layers);
                 break;
             case 'invokeTool':
                 result = await executeInvokeTool(step, input, ctx, baseCtx.harness);

package/dist/interpreter/structured-output.d.ts

@@ -1,7 +1,7 @@
 import type { StandardSchemaV1 } from '@noetic-tools/types';
 /**
  * JSON-parse + validate assistant text against a Standard Schema, raising
- * `model_parse_error`. Shared by the LLM step and sub-harness step handlers.
+ * `model_parse_error`. Shared by the LLM step and ACP agent step handlers.
  *
  * Zod schemas keep the original `safeParse` error; other vendors' Standard
  * Schema issues are adapted into a synthetic `ZodError` of `custom` issues so

package/dist/interpreter/structured-output.js

@@ -1,7 +1,7 @@
 import { frameworkCast, NoeticErrorImpl, standardIssuesToZodError, validateSchema, } from '@noetic-tools/types';
 /**
  * JSON-parse + validate assistant text against a Standard Schema, raising
- * `model_parse_error`. Shared by the LLM step and sub-harness step handlers.
+ * `model_parse_error`. Shared by the LLM step and ACP agent step handlers.
  *
  * Zod schemas keep the original `safeParse` error; other vendors' Standard
  * Schema issues are adapted into a synthetic `ZodError` of `custom` issues so

package/dist/portable/builders.d.ts

@@ -1,4 +1,6 @@
 /** @public */
+/** @public */
+export { acpAgentTool } from '../builders/acp-agent-tool.js';
 export { conditional, inParallel } from '../builders/control-flow-builders.js';
 /** @public */
 export { layerData, layerFunction } from '../builders/layer-provides-builders.js';

package/dist/portable/builders.js

@@ -1,4 +1,6 @@
 /** @public */
+/** @public */
+export { acpAgentTool } from '../builders/acp-agent-tool.js';
 export { conditional, inParallel } from '../builders/control-flow-builders.js';
 /** @public */
 export { layerData, layerFunction } from '../builders/layer-provides-builders.js';
@@ -6,7 +8,7 @@ export { layerData, layerFunction } from '../builders/layer-provides-builders.js
 export { loop } from '../builders/loop-builder.js';
 /** @public */
 export { spawn } from '../builders/spawn-builder.js';
-// The base builders plus the sub-harness `step` namespace, without
+// The base builders plus the ACP `step` namespace, without
 // `workflow` — the portable surface stays free of the hydrator so
 // restricted runtimes don't pull it in.
 /** @public */

package/dist/runtime/acp-session-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The harness's registry of live ACP connections.
+ *
+ * Three properties this has to get right, each of which was previously wrong:
+ *
+ * 1. **Everything kept is registered.** A session whose `keepAlive` outlives
+ *    its step is only closable if something holds it. Registering only when the
+ *    step named a `reuse` key meant `keepAlive: 'run'` without a key was held
+ *    by nobody — not closed at the end of the run, and out of reach of
+ *    `closeAcpSessions()`. With the stdio transport that is a child process
+ *    whose stdio keeps the host alive forever.
+ *
+ * 2. **Ownership is tracked.** A `'run'`-scoped session belongs to the root run
+ *    that opened it. Sweeping every entry when *any* root run finished let a
+ *    short request kill a concurrent long one's agent mid-turn, and let two
+ *    unrelated runs silently share one agent's conversation. `'harness'` scope
+ *    is deliberately global — surviving runs is its entire purpose.
+ *
+ * 3. **Opening is atomic per key.** `get` → `await connect()` → `set` leaves a
+ *    window in which two parallel steps sharing a key both miss, both connect,
+ *    and the second registration orphans the first — unreachable and never
+ *    closed. Registering the in-flight promise before awaiting closes it.
+ */
+import type { AcpKeepAlive, AcpLiveSession, AcpSessionInfo } from '@noetic-tools/types';
+/** @internal Identifies a session for reuse and for scoped teardown. */
+export interface AcpSessionKeyParts {
+    keepAlive: AcpKeepAlive;
+    /** Root context of the run taking the turn. */
+    rootId: string;
+    /** The step's `session.reuse`, when set. */
+    reuseKey?: string;
+}
+/** @internal Live ACP connections held by one `AgentHarness`. */
+export declare class AcpSessionStore {
+    private readonly settled;
+    /** Openers still connecting, so a concurrent step waits rather than racing. */
+    private readonly pending;
+    private nextAnonymous;
+    /**
+     * The handle a session is filed under.
+     *
+     * `'harness'` scope is keyed globally because outliving the run is the point.
+     * `'run'` scope is keyed per root so concurrent runs cannot see, share, or
+     * tear down each other's agents. A session with no `reuse` key gets a unique
+     * one, so it is still registered — and therefore still closable.
+     */
+    keyFor(parts: AcpSessionKeyParts): string;
+    /**
+     * Get the session under `key`, opening it if nobody has yet.
+     *
+     * Deliberately **not** `async`: the lookup and the registration of the
+     * in-flight promise must happen in one synchronous turn. An `await` between
+     * them — even one resolving immediately — lets a second caller check before
+     * the first registers, so both open a connection and one is orphaned,
+     * unreachable and never closed.
+     */
+    acquire(key: string, parts: AcpSessionKeyParts, open: () => Promise<AcpLiveSession>): Promise<{
+        live: AcpLiveSession;
+        fresh: boolean;
+    }>;
+    /** Forget a session without closing it — the caller already did. */
+    forget(key: string): void;
+    /** What is live right now, for a UI or a caller deciding what to cancel. */
+    list(): AcpSessionInfo[];
+    /** Look up by the handle {@link list} reports, or by a step's reuse key. */
+    get(key: string): AcpLiveSession | undefined;
+    /**
+     * Close every session a finishing root run owns. `'harness'` scope opted out
+     * of this collection, and another run's sessions are none of its business.
+     */
+    closeOwnedBy(rootId: string): Promise<void>;
+    /** Close everything, whatever its scope. */
+    closeAll(): Promise<void>;
+    private closeWhere;
+}

package/dist/schemas/workflow.d.ts

@@ -3,5 +3,5 @@
  * consumers can validate workflow documents without importing core.
  * This barrel keeps core's public and intra-core import paths unchanged.
  */
-export type { CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, OutputCodecRef, RunCodeWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, SubHarnessWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowGraph, WorkflowNode, } from '@noetic-tools/types';
+export type { AcpAgentWorkflowNode, CallModelWorkflowNode, ConditionalRoute, ConditionalWorkflowNode, InParallelWorkflowNode, InvokeToolWorkflowNode, LoopWorkflowNode, OutputCodecRef, RunCodeWorkflowNode, ScheduleWorkflowNode, SequenceWorkflowNode, SpawnWorkflowNode, SubflowWorkflowNode, UntilPredicate, WithContextWorkflowNode, WorkflowDocument, WorkflowGraph, WorkflowNode, } from '@noetic-tools/types';
 export { MergeStrategy, MergeStrategySchema, UntilPredicateSchema, validateWorkflow, WorkflowDocumentSchema, WorkflowNodeSchema, walkWorkflow, workflowDepth, workflowGraph, } from '@noetic-tools/types';