@zq-silk/yui 0.15.7 → 0.15.9

package/dist/executor/agentConfigurationProbe.js

@@ -5,11 +5,24 @@ import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { parse } from "smol-toml";
 import { configuredAgentLaunchEnvironment } from "../agent/launchEnvironment.js";
+import { codexClientInitialization } from "../runtime/codexAppServerRuntime.js";
+import { acpInitializeRequest, readAcpInitializeResult } from "../runtime/acpProtocol.js";
+import { handshakeObservationFrom } from "../runtime/agentRunConfiguration.js";
 import { YUI_VERSION } from "../version.js";
+/**
+ * Codex and Claude Code are configured by flags and their own files; neither
+ * plan exchanges capabilities on connect. Saying so explicitly keeps a caller
+ * from reading a missing handshake as an Agent that answered with nothing.
+ */
+const NO_HANDSHAKE = Object.freeze({
+    status: "unsupported",
+    reason: "This connection plan has no capability handshake; support is static."
+});
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const PROCESS_TERMINATION_GRACE_MS = 100;
 const CODEX_SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
 const CODEX_APPROVALS = ["untrusted", "on-request", "never"];
+const ACP_PROBE_REQUEST_ID = 1;
 export async function discoverCodexConfiguration(input) {
     const environment = configuredAgentLaunchEnvironment(input.agent, input.environment);
     const profile = input.config?.adapterId === "codex" ? input.config.profile : undefined;
@@ -22,10 +35,8 @@ export async function discoverCodexConfiguration(input) {
         const [version, help] = await Promise.all([
             runTextProcess(input.agent.command, [...input.agent.baseArgs, "--version"], input.cwd, environment, input.signal),
             runTextProcess(input.agent.command, [...input.agent.baseArgs, "--help"], input.cwd, environment, input.signal),
-            client.request("initialize", {
-                clientInfo: { name: "yui", title: "Yui", version: YUI_VERSION },
-                capabilities: { experimentalApi: true, requestAttestation: false }
-            }).then(() => { client.notify("initialized", {}); })
+            client.request("initialize", codexClientInitialization())
+                .then(() => { client.notify("initialized", {}); })
         ]);
         const [models, requirementsResult, providerCapabilities] = await Promise.all([
             listCodexModels(client),
@@ -48,6 +59,7 @@ export async function discoverCodexConfiguration(input) {
             agentId: input.agent.id,
             adapterId: "codex",
             ...(semanticVersion(version) === undefined ? {} : { cliVersion: semanticVersion(version) }),
+            handshake: NO_HANDSHAKE,
             models,
             fields: [
                 field("model", [], true),
@@ -101,6 +113,7 @@ export async function discoverClaudeConfiguration(input) {
         agentId: input.agent.id,
         adapterId: "claude",
         ...(semanticVersion(version) === undefined ? {} : { cliVersion: semanticVersion(version) }),
+        handshake: NO_HANDSHAKE,
         models,
         fields: [
             field("model", [], true),
@@ -259,6 +272,151 @@ async function requestClaudeInitialization(command, args, cwd, environment, sign
         })}\n`);
     });
 }
+/**
+ * Discover an ACP Agent's capabilities from the protocol itself.
+ *
+ * `initialize` is the only method used: it is the one exchange ACP guarantees
+ * before any Session exists, and it requires no authentication, so discovery
+ * never touches a model or spends quota. Everything reported here is what the
+ * Agent actually advertised — no field is inferred from which product it is.
+ */
+export async function discoverAcpConfiguration(input) {
+    const environment = configuredAgentLaunchEnvironment(input.agent, input.environment);
+    const negotiated = await requestAcpInitialization(input.agent.command, [...input.agent.baseArgs], input.cwd, environment, input.signal);
+    const warnings = [];
+    if (!negotiated.capabilities.loadSession) {
+        warnings.push("This ACP Agent does not support `session/load`, so a managed Yui Turn "
+            + "cannot survive a Provider restart.");
+    }
+    if (negotiated.authMethods.length > 0) {
+        // Authenticating is the operator's decision, made outside Yui with the
+        // product's own tooling. Reporting the requirement is the honest action.
+        warnings.push("This ACP Agent advertises authentication methods "
+            + `(${negotiated.authMethods.map((method) => method.id).join(", ")}); `
+            + "this handshake does not establish whether authentication is required "
+            + "or already satisfied.");
+    }
+    return {
+        schemaVersion: 1,
+        agentId: input.agent.id,
+        adapterId: "acp",
+        ...(negotiated.agentVersion === undefined
+            ? {}
+            : semanticVersion(negotiated.agentVersion) === undefined
+                ? {}
+                : { cliVersion: semanticVersion(negotiated.agentVersion) }),
+        // What this Agent actually agreed to, kept separate from what Yui's client
+        // statically supports. Projected by the same function a live Session uses,
+        // so this query and a Session inspect cannot describe one Agent's handshake
+        // differently. An Agent that reports no name stays `unknown` here and is
+        // never resolved into a product by its command line.
+        handshake: handshakeObservationFrom(negotiated),
+        // Deliberately empty, and not because ACP cannot select a model. ACP
+        // enumerates a Session's models in the `configOptions` returned by
+        // `session/new` — which means listing them requires creating a real Session
+        // on the Agent, and for a hosted product that is a billable remote effect
+        // triggered by what the user asked to be a capability query. So this probe
+        // stops at `initialize`: it reports that the axis is configurable and that
+        // its values are negotiated per Session, rather than opening a Session to
+        // populate a menu. The values are checked where they are actually known, at
+        // launch, against the option list that Session returns.
+        models: [],
+        fields: [
+            field("model", [], true, true, "ACP selects a model with session/set_config_option. The values one Agent "
+                + "accepts are enumerated per Session at session/new, so Yui does not list "
+                + "them here: creating a Session to populate the list would be a real, "
+                + "possibly billed remote effect for what is only a capability query. A "
+                + "configured model is checked against the Agent's own list at launch and "
+                + "the launch fails if it is not offered."),
+            field("effort", [], true, true, "ACP selects reasoning effort with session/set_config_option, under the "
+                + "`thought_level` category. As with the model, the accepted values are "
+                + "negotiated per Session and verified at launch rather than listed here."),
+            field("permission.strategy", [choice("default"), choice("bypass"), choice("configured")], false, true, "`default` sends no mode, so the Agent's own default stands. `configured` "
+                + "selects one exact mode the Agent offers. `bypass` applies the mode that "
+                + "grants unattended action, and only for an execution component Yui can "
+                + "identify — it is never guessed from a mode's name. None of these change "
+                + "how Yui answers session/request_permission: this client holds no "
+                + "interactive consent and always declines."),
+            field("permission.mode", [], true, true, "The mode ids belong to the Agent and are enumerated per Session, so Yui "
+                + "verifies a configured mode against that list at launch instead of "
+                + "listing candidates here."),
+            field("additionalDirectories", [], true, negotiated.capabilities.additionalDirectories, negotiated.capabilities.additionalDirectories
+                ? undefined
+                : "This ACP Agent does not advertise "
+                    + "`sessionCapabilities.additionalDirectories`, so extra workspace roots "
+                    + "cannot be sent to it and only the launch `cwd` is in scope.")
+        ],
+        warnings
+    };
+}
+/**
+ * Run one `initialize` exchange and stop. The Agent is spawned, asked what it
+ * supports, and terminated without creating a Session.
+ */
+async function requestAcpInitialization(command, args, cwd, environment, signal) {
+    const child = spawn(command, args, { cwd, env: environment, stdio: ["pipe", "pipe", "pipe"] });
+    return new Promise((resolvePromise, reject) => {
+        let settled = false;
+        let bytes = 0;
+        const output = createInterface({ input: child.stdout });
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            output.close();
+            terminateProcess(child);
+            signal.removeEventListener("abort", abort);
+            if (error !== undefined)
+                reject(error);
+            else
+                resolvePromise(value);
+        };
+        const abort = () => finish(abortError());
+        signal.addEventListener("abort", abort, { once: true });
+        child.on("error", (error) => finish(error));
+        child.on("exit", (code, exitSignal) => {
+            if (!settled)
+                finish(new Error(`ACP configuration probe exited before initialize (${code ?? exitSignal ?? "unknown"}).`));
+        });
+        output.on("line", (line) => {
+            bytes += Buffer.byteLength(line);
+            if (bytes > MAX_OUTPUT_BYTES) {
+                finish(new Error("ACP configuration probe exceeded the output limit."));
+                return;
+            }
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            const envelope = object(message);
+            if (envelope === undefined || envelope.id !== ACP_PROBE_REQUEST_ID)
+                return;
+            const failure = object(envelope.error);
+            if (failure !== undefined) {
+                finish(new Error(typeof failure.message === "string"
+                    ? `ACP initialize failed: ${failure.message}`
+                    : "ACP initialize failed."));
+                return;
+            }
+            try {
+                finish(undefined, readAcpInitializeResult(envelope.result));
+            }
+            catch (error) {
+                finish(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        child.stdin.on("error", (error) => finish(error));
+        child.stdin.end(`${JSON.stringify({
+            jsonrpc: "2.0",
+            id: ACP_PROBE_REQUEST_ID,
+            method: "initialize",
+            params: acpInitializeRequest(YUI_VERSION)
+        })}\n`);
+    });
+}
 async function runTextProcess(command, args, cwd, environment, signal) {
     const child = spawn(command, args, {
         cwd,

package/dist/executor/agentExecutor.js

@@ -1,8 +1,30 @@
 import { createHash } from "node:crypto";
 import { hasRecentTurnId, rememberRecentTurnId, validateRecentTurnIds } from "../runtime/recentTurnIds.js";
 import { roleSessionMayContinue, validateEffectiveLaunchSnapshot } from "./effectiveLaunch.js";
-import { currentProviderActivation, endProviderActivation, validateProviderRuntimeBinding } from "../runtime/providerRuntimeIdentity.js";
-import { builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
+import { validateProviderRuntimeBinding, currentProviderConversation } from "../runtime/providerRuntimeIdentity.js";
+import { builtinDriverIdForAdapter, builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
+import { builtinAgentEndpointImplementation, validateAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
+/** Recovery addresses retained execution identity, not a live Session grant.
+ * A released Session cache can be absent while its native binding still needs
+ * to be stopped. No active Session record is fabricated by this projection. */
+export function taskRoleControlTarget(set) {
+    if (set == null)
+        return undefined;
+    const current = set.sessions[set.activeAgentId];
+    const binding = set.providerBinding;
+    const fromBinding = binding !== null && (current === undefined
+        || (binding.run !== null && ["submitting", "accepted", "delivery-unknown"].includes(binding.run.status))
+        || (binding.goal !== null && binding.goal.status !== "complete"));
+    const nativeSessionId = fromBinding ? currentProviderConversation(binding).conversationId : current?.nativeSessionId;
+    const agentId = fromBinding ? binding.accountScope : current?.agentId;
+    if (nativeSessionId === undefined || agentId === undefined)
+        return undefined;
+    const session = [...Object.values(set.sessions), ...(set.history ?? [])]
+        .find(entry => entry.nativeSessionId === nativeSessionId && entry.agentId === agentId);
+    const adapterId = session?.adapterId ?? (binding === null ? undefined : builtinAgentDriverRegistry().find(binding.providerNamespace)?.adapterId);
+    return { nativeSessionId, agentId, adapterId, status: session?.status,
+        updatedAt: session?.updatedAt ?? set.updatedAt, fromBinding };
+}
 export function createRoleSessionSet(owner, activeAgentId, now) {
     const base = {
         owner: normalizeOwner(owner),
@@ -45,8 +67,7 @@ export function recordRoleAgentSession(set, input, now) {
     const adapterId = requireText(input.adapterId, "Agent adapter id");
     const nativeSessionId = requireText(input.nativeSessionId, "Native session id");
     if (set.owner.scope === "task") {
-        const historical = (set.history ?? []).find((entry) => (entry.nativeSessionId === nativeSessionId
-            || (input.runtimeGenerationId !== undefined && entry.runtimeGenerationId === input.runtimeGenerationId)));
+        const historical = (set.history ?? []).find((entry) => (entry.nativeSessionId === nativeSessionId));
         if (historical !== undefined) {
             throw new Error("A new Task Role Session cannot reuse a historical native identity.");
         }
@@ -68,7 +89,7 @@ export function recordRoleAgentSession(set, input, now) {
     if (existing !== undefined && existing.nativeSessionId === nativeSessionId
         && !roleSessionMayContinue(existing.effective, effective)) {
         throw new Error(`Role Agent session cannot continue under this launch: ${agentId}. `
-            + "Its Agent, adapter or physical workspace changed.");
+            + "Its Agent, execution component, connection plan or physical workspace changed.");
     }
     if (existing !== undefined && existing.nativeSessionId !== nativeSessionId
         && existing.status === "active") {
@@ -76,18 +97,25 @@ export function recordRoleAgentSession(set, input, now) {
     }
     const timestamp = now.toISOString();
     const continuing = existing?.nativeSessionId === nativeSessionId ? existing : undefined;
+    if (continuing !== undefined && input.endpointImplementation !== undefined
+        && (continuing.endpointImplementation.id !== input.endpointImplementation.id
+            || continuing.endpointImplementation.generation !== input.endpointImplementation.generation)) {
+        throw new Error("A native Session cannot change its Endpoint implementation in place.");
+    }
     const session = {
-        schemaVersion: 5,
+        schemaVersion: 6,
         agentId,
         adapterId,
         nativeSessionId,
-        ...(input.runtimeGenerationId === undefined
-            ? continuing?.runtimeGenerationId === undefined ? {} : { runtimeGenerationId: continuing.runtimeGenerationId }
-            : { runtimeGenerationId: requireText(input.runtimeGenerationId, "Runtime generation id") }),
         ...optionalSessionText("title", input.title ?? continuing?.title),
         ...optionalSessionText("preview", input.preview ?? continuing?.preview),
         policy: input.policy,
         effective: continuing?.effective ?? effective,
+        endpointImplementation: {
+            ...(continuing?.endpointImplementation
+                ?? input.endpointImplementation
+                ?? builtinAgentEndpointImplementation(adapterId))
+        },
         status: input.status,
         ...(input.status === "ended"
             ? { endReason: input.endReason ?? continuing?.endReason ?? "stopped" }
@@ -192,38 +220,34 @@ export function retireTaskRoleSessionsForWorkspace(set, now) {
         updatedAt: timestamp
     });
 }
-/**
- * Terminalizes only the aggregate-16 Claude placeholder shape after the
- * caller has fenced the Task store and proved that the exact Role has no live
- * native pane. All other nonterminal durable Sessions remain blockers for the
- * ordinary workspace-retirement path above.
- */
-export function retireConfirmedAbsentInactiveTaskRolePlaceholders(set, now) {
+/** Explicit fresh-session selection after physical stop. Keep every original
+ * Run/result and the old native identity as history; never invent a new ID. */
+export function selectNewTaskRoleSession(set, agentId, now) {
     validateRoleSessionSet(set);
-    const timestamp = now.toISOString();
-    let changed = false;
-    const sessions = Object.fromEntries(Object.entries(set.sessions).map(([agentId, session]) => {
-        const isNeverStartedInactiveClaude = agentId !== set.activeAgentId
-            && session.adapterId === "claude"
-            && session.status === "active"
-            && session.runtimeGenerationId === undefined
-            && session.recentCompletedTurnIds.length === 0;
-        if (!isNeverStartedInactiveClaude)
-            return [agentId, session];
-        changed = true;
-        return [agentId, {
-                ...session,
-                status: "ended",
-                endReason: "failed",
-                updatedAt: timestamp
-            }];
-    }));
-    if (!changed)
-        return set;
+    const session = set.sessions[requireSafeIdentity(agentId, "Agent id")];
+    if (session !== undefined && session.status !== "ended") {
+        throw new Error("Stop the current Session before selecting a new one.");
+    }
+    if (set.activeAgentId === agentId && set.providerBinding !== null) {
+        if (set.providerBinding.run !== null
+            && ["submitting", "accepted", "delivery-unknown"].includes(set.providerBinding.run.status)
+            || set.providerBinding.goal !== null && set.providerBinding.goal.status !== "complete") {
+            throw new Error("Settle the exact native input and Goal before selecting a new Session.");
+        }
+    }
+    if (session === undefined)
+        return validateRoleSessionSet({
+            ...set, ...(set.activeAgentId === agentId ? { providerBinding: null } : {}),
+            updatedAt: now.toISOString()
+        });
+    const sessions = { ...set.sessions };
+    delete sessions[agentId];
     return validateRoleSessionSet({
         ...set,
         sessions,
-        updatedAt: timestamp
+        history: [...(set.history ?? []), session],
+        ...(set.activeAgentId === agentId ? { providerBinding: null } : {}),
+        updatedAt: now.toISOString()
     });
 }
 export function rememberRoleAgentCompletedTurn(set, agentId, nativeSessionId, turnId, now) {
@@ -279,7 +303,10 @@ export function roleAgentSessionResumeMode(set, agentId, desired) {
         : undefined;
     if (conversation?.recoverability === "unrecoverable") {
         throw new Error(`Role Agent native Session is not recoverable: ${agentId}/${session.nativeSessionId}. `
-            + "Explicitly select a new Session to continue; existing input attempts are not replayed.");
+            + (set.owner.scope === "task"
+                ? `After stopping the exact idle Session, use yui task role session new ${set.owner.taskId} ${set.owner.roleName} --reason <evidence>, then retry the failed AgentRun. `
+                : "Explicitly select a new Session to continue. ")
+            + "Existing input attempts are not replayed.");
     }
     if (roleSessionMayContinue(session.effective, desired))
         return "resume";
@@ -317,7 +344,7 @@ export function updateTaskRoleProviderRuntime(set, binding, updatedAt) {
 }
 /**
  * Detaches a confirmed-dead local Host without ending its resumable native
- * Session. The Host launch and Provider Activation are disposable execution
+ * Session. Host connections are disposable execution
  * facts; the native Session remains the durable continuation identity.
  */
 export function detachRoleAgentSessionHost(set, now) {
@@ -326,7 +353,7 @@ export function detachRoleAgentSessionHost(set, now) {
     if (active === undefined || active.status === "ended")
         return set;
     const timestamp = requireDate(now, "Role Host detach timestamp");
-    const { runtimeGenerationId: _runtimeGenerationId, endReason: _endReason, ...session } = active;
+    const { endReason: _endReason, ...session } = active;
     const updated = validateRoleSessionSet({
         ...set,
         sessions: {
@@ -339,24 +366,10 @@ export function detachRoleAgentSessionHost(set, now) {
         },
         updatedAt: timestamp
     });
-    if (updated.owner.scope !== "task")
-        return updated;
-    let taskSet = updated;
-    const binding = taskSet.providerBinding;
     // Losing the attachment proves neither cancellation nor non-submission.
     // Preserve the exact input and its acceptance/unknown facts. Only a native
     // terminal or an explicit submission resolution may settle that attempt.
-    const activation = binding === null
-        ? null
-        : currentProviderActivation(binding);
-    if (activation !== null) {
-        taskSet = updateTaskRoleProviderRuntime(taskSet, endProviderActivation(binding, activation.activationId, {
-            status: "ended",
-            endedAt: now.toISOString(),
-            reason: "runtime-physical-exit"
-        }), now);
-    }
-    return taskSet;
+    return updated;
 }
 /**
  * Records a Provider activity boundary without changing the durable Yui Turn.
@@ -367,7 +380,7 @@ export function detachRoleAgentSessionHost(set, now) {
  * Turn fence; this transition merely makes the native Session available for a
  * subsequent input and remembers the provider Turn idempotently.
  */
-export function recordTaskRoleTurnBoundary(set, input, completedAt) {
+export function recordTaskRoleNativeTurnBoundary(set, input, completedAt) {
     validateRoleSessionSet(set);
     assertTaskRoleSessionSet(set);
     const agentId = requireSafeIdentity(input.agentId, "Agent id");
@@ -463,11 +476,12 @@ export function validateRoleSessionSet(set) {
             ? null
             : validateProviderRuntimeBinding(taskSet.providerBinding);
         if (providerBinding !== null) {
-            const session = taskSet.sessions[set.activeAgentId];
-            if (session === undefined) {
-                throw new Error("Provider Runtime Binding has no active Role Agent session.");
-            }
-            if (providerBinding.providerNamespace !== builtinDriverIdForAdapter(session.adapterId)) {
+            const conversationId = currentProviderConversation(providerBinding).conversationId;
+            const session = [...Object.values(taskSet.sessions), ...(taskSet.history ?? [])]
+                .find(entry => entry.agentId === providerBinding.accountScope && entry.nativeSessionId === conversationId);
+            // Execution control evidence may outlive the disposable Session cache.
+            // It is not a live Session grant; recovery still needs native/OS proof.
+            if (session !== undefined && providerBinding.providerNamespace !== builtinDriverIdForAdapter(session.adapterId)) {
                 throw new Error("Provider Runtime Binding namespace does not match the Agent adapter.");
             }
         }
@@ -476,7 +490,7 @@ export function validateRoleSessionSet(set) {
     return set;
 }
 export function validateRoleAgentSession(session, expectedAgentId = session.agentId) {
-    if (session.schemaVersion !== 5) {
+    if (session.schemaVersion !== 6) {
         throw new Error(`Role Agent session schema version is invalid: ${expectedAgentId}.`);
     }
     const agentId = requireSafeIdentity(session.agentId, "Agent id");
@@ -484,22 +498,12 @@ export function validateRoleAgentSession(session, expectedAgentId = session.agen
         throw new Error(`Role Agent session identity is inconsistent: ${expectedAgentId}.`);
     }
     requireText(session.adapterId, "Agent adapter id");
+    validateAgentEndpointImplementation(session.endpointImplementation);
     validateEffectiveLaunchSnapshot(session.effective);
     if (session.effective.agentId !== agentId || session.effective.adapterId !== session.adapterId) {
         throw new Error(`Role Agent session effective identity is inconsistent: ${agentId}.`);
     }
-    // A restored opaque host may have no provider-native identity; retain its
-    // launch fence so it can be inspected or stopped without inventing identity.
-    if (session.nativeSessionId === undefined) {
-        if (session.runtimeGenerationId === undefined) {
-            throw new Error("Role Agent session requires a native Session or runtime generation id.");
-        }
-    }
-    else {
-        requireText(session.nativeSessionId, "Native session id");
-    }
-    if (session.runtimeGenerationId !== undefined)
-        requireSafeIdentity(session.runtimeGenerationId, "Runtime generation id");
+    requireText(session.nativeSessionId, "Native session id");
     if (session.title !== undefined
         && optionalSessionText("title", session.title).title !== session.title) {
         throw new Error("Role Agent session title is invalid.");
@@ -531,10 +535,7 @@ function taskRoleSessionIdentity(session) {
     if (session.nativeSessionId !== undefined) {
         return `${session.agentId}\0native\0${session.nativeSessionId}`;
     }
-    if (session.runtimeGenerationId === undefined) {
-        throw new Error("Opaque Task Role session requires a runtime generation identity.");
-    }
-    return `${session.agentId}\0runtime-generation\0${session.runtimeGenerationId}`;
+    throw new Error("Task Role session requires a native session identity.");
 }
 function optionalSessionText(field, value) {
     if (value === undefined)