@zq-silk/yui 0.13.9 → 0.14.0

package/dist/runtime/structuredProviderHost.js

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { Duplex } from "node:stream";
 import WebSocket from "ws";
-import { CodexAppServerRequestError, CodexAppServerRuntime, codexAppServerErrorIsMissing } from "./codexAppServerRuntime.js";
+import { CodexAppServerRequestError, CodexAppServerRuntime, codexGoalNotification, codexAppServerErrorIsMissing, codexTurnInput, codexTurnSummary } from "./codexAppServerRuntime.js";
 import { serializeAgentErrorRaw } from "./agentError.js";
 import { PROVIDER_ACCEPT_TIMEOUT_MS } from "./runtimeDeadlines.js";
 import { YUI_VERSION } from "../version.js";
@@ -61,15 +61,16 @@ export async function startStructuredProviderSession(payload, input = {}) {
     const exit = childExit(child, processInstanceId);
     try {
         if (control.adapterId === "codex") {
-            const opened = await CodexStructuredProviderSession.open(child, exit, processInstanceId, payload, control, input.onTerminal, mirror);
+            const opened = await CodexStructuredProviderSession.open(child, exit, processInstanceId, payload, control, input.onStarted, input.onTerminal, input.onGoal, mirror);
             return Object.freeze({
                 session: opened.session,
                 ...(opened.recoveredTerminal === undefined
                     ? {}
-                    : { recoveredTerminal: opened.recoveredTerminal })
+                    : { recoveredTerminal: opened.recoveredTerminal }),
+                goal: opened.goal
             });
         }
-        const session = await ClaudeStructuredProviderSession.open(child, exit, processInstanceId, control, input.onTerminal, mirror);
+        const session = await ClaudeStructuredProviderSession.open(child, exit, processInstanceId, control, input.onTerminal, input.onGoal, mirror);
         return Object.freeze({ session });
     }
     catch (error) {
@@ -339,21 +340,26 @@ class CodexStructuredProviderSession {
     processInstanceId;
     conversationId;
     runtime;
+    onStarted;
     onTerminal;
+    onGoal;
     adapterId = "codex";
     #activeTurnId;
     #clientOwnedTurnId;
     #submissionPending = false;
+    #bufferedStarts = [];
     #bufferedTerminals = [];
-    constructor(child, exit, processInstanceId, conversationId, runtime, onTerminal) {
+    constructor(child, exit, processInstanceId, conversationId, runtime, onStarted, onTerminal, onGoal) {
         this.child = child;
         this.exit = exit;
         this.processInstanceId = processInstanceId;
         this.conversationId = conversationId;
         this.runtime = runtime;
+        this.onStarted = onStarted;
         this.onTerminal = onTerminal;
+        this.onGoal = onGoal;
     }
-    static async open(child, exit, processInstanceId, payload, control, onTerminal, mirror) {
+    static async open(child, exit, processInstanceId, payload, control, onStarted, onTerminal, onGoal, mirror) {
         const channel = await CodexProxyWebSocketChannel.connect(child, mirror);
         const openingMessages = [];
         const stopOpeningBuffer = channel.onMessage((message) => openingMessages.push(message));
@@ -398,7 +404,7 @@ class CodexStructuredProviderSession {
                 name: control.sessionTitle
             });
         }
-        const session = new CodexStructuredProviderSession(child, exit, processInstanceId, conversationId, runtime, onTerminal);
+        const session = new CodexStructuredProviderSession(child, exit, processInstanceId, conversationId, runtime, onStarted, onTerminal, onGoal);
         session.#activeTurnId = resumedActiveTurnId;
         const ownedTurn = control.kind === "restore" ? control.ownedTurn : undefined;
         session.#clientOwnedTurnId = ownedTurn?.turnId;
@@ -427,6 +433,7 @@ class CodexStructuredProviderSession {
                         ? "failed"
                         : recovered.status === "interrupted" ? "cancelled" : "completed",
                     observedAt: new Date().toISOString(),
+                    ...(recovered.summary === undefined ? {} : { summary: recovered.summary }),
                     ...(recovered.status !== "failed"
                         ? {}
                         : {
@@ -440,9 +447,11 @@ class CodexStructuredProviderSession {
                 throw new ProviderDeliveryUnknownError(`Codex resume could not recover the persisted Yui Turn ${ownedTurn.turnId}.`, ownedTurn.attemptId);
             }
         }
+        const goal = await runtime.readGoal(conversationId);
         return Object.freeze({
             session,
-            ...(recoveredTerminal === undefined ? {} : { recoveredTerminal })
+            ...(recoveredTerminal === undefined ? {} : { recoveredTerminal }),
+            goal
         });
     }
     #observeMessage(message, emit) {
@@ -450,10 +459,30 @@ class CodexStructuredProviderSession {
         const params = object(message.params) ?? {};
         if (optionalId(params.threadId) !== this.conversationId)
             return undefined;
+        const goal = codexGoalNotification({ method, params });
+        if (goal !== undefined) {
+            if (emit)
+                this.onGoal?.(goal);
+            return undefined;
+        }
         if (method === "turn/started") {
             const turnId = nestedId(params, "turn") ?? optionalId(params.turnId);
-            if (turnId !== undefined)
+            if (turnId !== undefined) {
                 this.#activeTurnId = turnId;
+                const turn = object(params.turn) ?? {};
+                const input = codexTurnInput(turn);
+                const started = {
+                    conversationId: this.conversationId,
+                    nativeSessionId: this.conversationId,
+                    nativeTurnId: turnId,
+                    observedAt: new Date().toISOString(),
+                    ...(input === undefined ? {} : { input })
+                };
+                if (this.#submissionPending && emit)
+                    this.#bufferedStarts.push(started);
+                else if (emit)
+                    this.#emitStarted(started);
+            }
             return undefined;
         }
         if (method !== "turn/completed")
@@ -468,12 +497,16 @@ class CodexStructuredProviderSession {
         const failure = status === "failed"
             ? providerErrorEvidence(turn.error)
             : undefined;
+        const summary = codexTurnSummary(turn);
+        const input = codexTurnInput(turn);
         const terminal = {
             conversationId: this.conversationId,
             nativeSessionId: this.conversationId,
             nativeTurnId,
             status,
             observedAt: new Date().toISOString(),
+            ...(input === undefined ? {} : { input }),
+            ...(summary === undefined ? {} : { summary }),
             ...(failure === undefined ? {} : failure)
         };
         if (this.#submissionPending && emit) {
@@ -521,14 +554,48 @@ class CodexStructuredProviderSession {
         }
         finally {
             this.#submissionPending = false;
+            const starts = this.#bufferedStarts.splice(0);
+            for (const started of starts)
+                this.#emitStarted(started);
             const buffered = this.#bufferedTerminals.splice(0);
             for (const terminal of buffered)
                 this.#emitTerminal(terminal);
         }
     }
+    async steerTurn(turn) {
+        const nativeTurnId = this.#activeTurnId;
+        if (nativeTurnId === undefined) {
+            throw new ProviderTurnRejectedError("Provider Conversation has no active Turn to steer.", turn.attemptId);
+        }
+        const acceptance = await this.runtime.steerTurn({
+            conversationId: this.conversationId,
+            expectedTurnId: nativeTurnId,
+            text: turn.boundedText,
+            clientUserMessageId: turn.attemptId
+        });
+        if (acceptance.status === "unknown") {
+            throw new ProviderDeliveryUnknownError(acceptance.reason, turn.attemptId);
+        }
+        if (acceptance.status !== "accepted") {
+            throw new ProviderTurnRejectedError(acceptance.reason, turn.attemptId);
+        }
+        return Object.freeze({
+            attemptId: turn.attemptId,
+            conversationId: this.conversationId,
+            nativeSessionId: this.conversationId,
+            nativeTurnId,
+            acceptedAt: new Date().toISOString()
+        });
+    }
     #emitTerminal(terminal) {
         this.#completeTerminal(terminal, true);
     }
+    #emitStarted(started) {
+        this.onStarted?.({
+            ...started,
+            clientOwned: started.nativeTurnId === this.#clientOwnedTurnId
+        });
+    }
     #completeTerminal(terminal, emit) {
         const clientOwned = terminal.nativeTurnId === this.#clientOwnedTurnId;
         if (terminal.nativeTurnId === this.#activeTurnId)
@@ -553,22 +620,25 @@ class ClaudeStructuredProviderSession {
     processInstanceId;
     conversationId;
     channel;
+    onGoal;
     adapterId = "claude";
     #activeTurnId;
-    constructor(child, exit, processInstanceId, conversationId, channel) {
+    #lastGoalKey;
+    constructor(child, exit, processInstanceId, conversationId, channel, onGoal) {
         this.child = child;
         this.exit = exit;
         this.processInstanceId = processInstanceId;
         this.conversationId = conversationId;
         this.channel = channel;
+        this.onGoal = onGoal;
     }
-    static async open(child, exit, processInstanceId, control, onTerminal, mirror) {
+    static async open(child, exit, processInstanceId, control, onTerminal, onGoal, mirror) {
         const channel = new JsonLineChannel(child, mirror);
         const nativeSessionId = control.nativeSessionId;
         if (nativeSessionId === undefined) {
             throw new Error("Managed Claude launch requires a preallocated native Session id.");
         }
-        const session = new ClaudeStructuredProviderSession(child, exit, processInstanceId, nativeSessionId, channel);
+        const session = new ClaudeStructuredProviderSession(child, exit, processInstanceId, nativeSessionId, channel, onGoal);
         channel.onMessage((message) => session.#receive(message, onTerminal));
         return session;
     }
@@ -609,6 +679,31 @@ class ClaudeStructuredProviderSession {
             acceptedAt: new Date().toISOString()
         });
     }
+    async steerTurn(turn) {
+        const nativeTurnId = this.#activeTurnId;
+        if (nativeTurnId === undefined) {
+            throw new ProviderTurnRejectedError("Provider Conversation has no active Turn to steer.", turn.attemptId);
+        }
+        try {
+            await this.channel.send({
+                type: "user",
+                message: {
+                    role: "user",
+                    content: [{ type: "text", text: turn.boundedText }]
+                }
+            });
+        }
+        catch (error) {
+            throw new ProviderDeliveryUnknownError(`Claude steer write did not complete: ${error instanceof Error ? error.message : String(error)}`, turn.attemptId);
+        }
+        return Object.freeze({
+            attemptId: turn.attemptId,
+            conversationId: this.conversationId,
+            nativeSessionId: this.conversationId,
+            nativeTurnId,
+            acceptedAt: new Date().toISOString()
+        });
+    }
     waitForExit() {
         return this.exit;
     }
@@ -616,6 +711,18 @@ class ClaudeStructuredProviderSession {
         terminateProcessGroup(this.child, signal);
     }
     #receive(message, onTerminal) {
+        const goal = claudeActiveGoal(message, this.conversationId);
+        if (goal !== undefined) {
+            const key = JSON.stringify(goal === null ? null : {
+                status: goal.status,
+                objective: goal.objective,
+                tokenBudget: goal.tokenBudget
+            });
+            if (key !== this.#lastGoalKey) {
+                this.#lastGoalKey = key;
+                this.onGoal?.(goal);
+            }
+        }
         if (message.type === "user")
             return;
         if (message.type !== "result" || this.#activeTurnId === undefined
@@ -642,6 +749,64 @@ class ClaudeStructuredProviderSession {
         });
     }
 }
+function claudeActiveGoal(message, conversationId) {
+    if (!Object.hasOwn(message, "active_goal"))
+        return undefined;
+    if (message.active_goal === null)
+        return null;
+    const raw = object(message.active_goal);
+    if (raw === null)
+        return undefined;
+    const objective = typeof raw.objective === "string" ? raw.objective.trim() : "";
+    if (objective.length === 0)
+        return undefined;
+    const status = providerGoalStatus(raw.status);
+    if (status === undefined)
+        return undefined;
+    const tokenBudget = positiveOptionalInteger(raw.token_budget ?? raw.tokenBudget);
+    return Object.freeze({
+        conversationId,
+        status,
+        objective,
+        updatedAt: providerTimestamp(raw.updated_at ?? raw.updatedAt),
+        ...(optionalId(raw.turn_id ?? raw.turnId) === undefined
+            ? {}
+            : { nativeTurnId: optionalId(raw.turn_id ?? raw.turnId) }),
+        ...(tokenBudget === undefined ? {} : { tokenBudget })
+    });
+}
+function providerGoalStatus(value) {
+    switch (value) {
+        case "active":
+        case "paused":
+        case "blocked":
+        case "complete":
+            return value;
+        case "usageLimited":
+        case "usage_limited":
+        case "usage-limited":
+            return "usage-limited";
+        case "budgetLimited":
+        case "budget_limited":
+        case "budget-limited":
+            return "budget-limited";
+        default:
+            return undefined;
+    }
+}
+function providerTimestamp(value) {
+    if (typeof value === "string" && Number.isFinite(Date.parse(value))) {
+        return new Date(value).toISOString();
+    }
+    if (Number.isSafeInteger(value) && value >= 0) {
+        const epoch = value;
+        return new Date(epoch < 1_000_000_000_000 ? epoch * 1_000 : epoch).toISOString();
+    }
+    return new Date().toISOString();
+}
+function positiveOptionalInteger(value) {
+    return Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
 function childExit(child, processInstanceId) {
     return new Promise((resolvePromise, reject) => {
         child.once("error", reject);

package/dist/runtime/tmuxAdapters.js

@@ -8,7 +8,7 @@ import { toRuntimeLaunchFailure } from "./launchDiagnostics.js";
 import { requireSafeIdentity } from "./validation.js";
 import { YUI_CONTROL_PLANE_DESCRIPTOR, YUI_TASK_RUNTIME_DESCRIPTOR } from "./exactControlPlane.js";
 import { launchBrokerForHome } from "./launchBroker.js";
-import { AGENT_HOST_CONTROL_PROTOCOL, sendAgentHostLaunchControl, sendAgentHostTurnControl, waitForAgentHostLaunchAck } from "./agentHost.js";
+import { AGENT_HOST_CONTROL_PROTOCOL, sendAgentHostLaunchControl, sendAgentHostTurnControl, sendAgentHostSteerControl, waitForAgentHostLaunchAck } from "./agentHost.js";
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 300_000;
 /**
  * Runtime lifecycle adapter for the current tmux host. The returned hostRef is
@@ -160,7 +160,7 @@ export class TmuxSessionHost {
         // Validate generated identity before starting an external process.
         const bindingId = requireSafeIdentity(this.#createBindingId(), "Runtime binding id");
         const writableHumanAttached = request.owner.scope === "task"
-            && request.runId !== undefined
+            && request.turnId !== undefined
             && (this.tmux.hasWritableClientAsync !== undefined
                 ? await this.tmux.hasWritableClientAsync(hostId, request.owner.roleName)
                 : this.tmux.hasWritableClient?.(hostId, request.owner.roleName) === true);
@@ -174,7 +174,7 @@ export class TmuxSessionHost {
             effective: request.effective,
             launchId: request.launchId,
             mode: request.mode,
-            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            ...(request.turnId === undefined ? {} : { turnId: request.turnId }),
             ...(request.runtimeIsolation === undefined
                 ? {}
                 : { runtimeIsolation: request.runtimeIsolation }),
@@ -221,7 +221,7 @@ export class TmuxSessionHost {
         beforeHostStart?.({
             owner: request.owner,
             launchId: request.launchId,
-            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            ...(request.turnId === undefined ? {} : { turnId: request.turnId }),
             agentId: request.agentId,
             adapterId: request.adapterId,
             effective: request.effective,
@@ -235,12 +235,12 @@ export class TmuxSessionHost {
         // Interactive/global Roles remain native TUIs even when their Driver
         // advertises a persistent child lifecycle. Provider control metadata is
         // the discriminator for the structured Agent Host path. A managed Task
-        // Run has no terminal-write fallback and must expose that contract.
+        // Turn has no terminal-write fallback and must expose that contract.
         if (yuiHome === undefined
             || childLifecycle === undefined
             || planned.launch.providerControl === undefined) {
-            if (request.owner.scope === "task" && request.runId !== undefined) {
-                throw new Error("Managed Task Run is missing its structured Agent Host contract.");
+            if (request.owner.scope === "task" && request.turnId !== undefined) {
+                throw new Error("Managed Task Turn is missing its structured Agent Host contract.");
             }
             let hostCreated;
             try {
@@ -270,7 +270,7 @@ export class TmuxSessionHost {
                 }
                 if (request.mode === "new"
                     && request.owner.scope === "task"
-                    && request.runId !== undefined
+                    && request.turnId !== undefined
                     && this.#waitForNativeSession !== undefined) {
                     binding = createRuntimeBinding({
                         ...binding,
@@ -286,7 +286,7 @@ export class TmuxSessionHost {
         const sessionManifest = planned.launch.env.YUI_SESSION_MANIFEST;
         const frozenControlPlane = planned.launch.env[YUI_CONTROL_PLANE_DESCRIPTOR];
         const frozenTaskRuntime = planned.launch.env[YUI_TASK_RUNTIME_DESCRIPTOR];
-        if (request.owner.scope === "task" && request.runId !== undefined
+        if (request.owner.scope === "task" && request.turnId !== undefined
             && (sessionManifest === undefined
                 || frozenControlPlane === undefined
                 || frozenTaskRuntime === undefined)) {
@@ -507,7 +507,7 @@ async function deadHostLaunchFailure(tmux, hostId, roleName, pane, context) {
         ...(stderrTail === undefined || stderrTail.length === 0 ? {} : { stderrTail })
     });
 }
-/** Structured managed-Run input; tmux remains presentation/liveness only. */
+/** Structured managed-Turn input; tmux remains presentation/liveness only. */
 export class AgentHostPromptPushAdapter {
     home;
     constructor(home) {
@@ -531,7 +531,7 @@ export class AgentHostPromptPushAdapter {
                     type: "submit-turn",
                     launchId: request.binding.launchId,
                     nativeSessionId: request.binding.nativeSessionId,
-                    runId: request.envelope.source.localId,
+                    turnId: request.envelope.source.localId,
                     authority: request.binding.providerAuthority,
                     turn: {
                         attemptId: request.envelope.id,
@@ -563,6 +563,41 @@ export class AgentHostPromptPushAdapter {
                 : "delivery-unknown";
         }
     }
+    async trySteer(request) {
+        try {
+            const result = await sendAgentHostSteerControl({
+                home: this.home,
+                scope: "task",
+                taskId: request.owner.taskId,
+                roleName: request.owner.roleName,
+                control: {
+                    protocol: AGENT_HOST_CONTROL_PROTOCOL,
+                    type: "steer-turn",
+                    launchId: request.launchId,
+                    nativeSessionId: request.nativeSessionId,
+                    nativeTurnId: request.nativeTurnId,
+                    authority: request.providerAuthority,
+                    turn: {
+                        attemptId: request.envelope.id,
+                        boundedText: request.envelope.text
+                    }
+                }
+            });
+            if (result.outcome === "accepted")
+                return "delivered";
+            if (result.snapshot.state === "delivery-unknown")
+                return "delivery-unknown";
+            if (result.snapshot.state === "busy")
+                return "busy";
+            return result.outcome === "rejected" ? "rejected" : "unavailable";
+        }
+        catch (error) {
+            const code = error.code;
+            return code === "ENOENT" || code === "ECONNREFUSED"
+                ? "unavailable"
+                : "delivery-unknown";
+        }
+    }
 }
 async function ensureRoleWindow(tmux, hostId, role, launch) {
     return tmux.ensureRoleWindowAsync === undefined