@zq-silk/yui 0.15.7 → 0.15.8

package/dist/context/{turnInputContract.js → runInputContract.js}

@@ -1,43 +1,44 @@
 import { normalizedUniqueText, requireIdentity, requireText } from "../domain/validation.js";
 import { validateContextSnapshotRef } from "./contextSnapshot.js";
-export const TURN_INPUT_PROTOCOL_VERSION = 1;
-export const TURN_INPUT_PROTOCOL = "yui-turn/v1";
-export const TURN_INPUT_MAX_BYTES = 4 * 1024;
-export const TURN_INPUT_MAX_DELTAS = 16;
-export const YUI_TURN_INPUT_CHANNELS = [
+export const RUN_INPUT_PROTOCOL_VERSION = 1;
+export const RUN_INPUT_PROTOCOL = "yui-run/v1";
+export const RUN_INPUT_MAX_BYTES = 4 * 1024;
+export const RUN_INPUT_MAX_DELTAS = 16;
+export const YUI_RUN_INPUT_CHANNELS = [
     "user-message",
     "input-response",
     "task-dispatch",
     "workitem-dispatch",
+    "message-continuation",
     "leader-wakeup",
     "leader-forced-wakeup"
 ];
-export function createTurnInput(input) {
+export function createRunInput(input) {
     const common = normalizeInput(input);
     return Object.freeze({
-        schemaVersion: TURN_INPUT_PROTOCOL_VERSION,
+        schemaVersion: RUN_INPUT_PROTOCOL_VERSION,
         ...common,
         ...(input.directive === undefined
             ? {}
-            : { directive: requireText(input.directive, "Turn input directive") })
+            : { directive: requireText(input.directive, "AgentRun input directive") })
     });
 }
-export function validateTurnInput(value) {
-    if (value.schemaVersion !== TURN_INPUT_PROTOCOL_VERSION) {
-        throw new Error("Turn input must use schemaVersion 1.");
+export function validateRunInput(value) {
+    if (value.schemaVersion !== RUN_INPUT_PROTOCOL_VERSION) {
+        throw new Error("AgentRun input must use schemaVersion 1.");
     }
-    const normalized = createTurnInput(value);
+    const normalized = createRunInput(value);
     if (JSON.stringify(normalized) !== JSON.stringify(value)) {
-        throw new Error("Turn input is not canonical.");
+        throw new Error("AgentRun input is not canonical.");
     }
     return value;
 }
-export function createTurnInputEnvelope(context, input) {
-    validateTurnInput(input);
+export function createRunInputEnvelope(context, input) {
+    validateRunInput(input);
     const normalized = normalizeEnvelopeContext(context, input);
     return Object.freeze({
-        protocol: TURN_INPUT_PROTOCOL,
-        turnId: normalized.turnId,
+        protocol: RUN_INPUT_PROTOCOL,
+        runId: normalized.runId,
         source: input.source,
         roleName: normalized.roleName,
         purpose: normalized.purpose,
@@ -48,20 +49,20 @@ export function createTurnInputEnvelope(context, input) {
         deltaRefIds: input.deltaRefIds
     });
 }
-export function validateTurnInputEnvelope(value) {
-    if (value.protocol !== TURN_INPUT_PROTOCOL) {
-        throw new Error("Turn input protocol is unsupported.");
+export function validateRunInputEnvelope(value) {
+    if (value.protocol !== RUN_INPUT_PROTOCOL) {
+        throw new Error("AgentRun input protocol is unsupported.");
     }
     normalizeEnvelope(value);
-    const serialized = serializeTurnInputEnvelope(value);
-    if (Buffer.byteLength(serialized, "utf8") > TURN_INPUT_MAX_BYTES) {
-        throw new Error("Turn input envelope exceeds its protocol byte limit.");
+    const serialized = serializeRunInputEnvelope(value);
+    if (Buffer.byteLength(serialized, "utf8") > RUN_INPUT_MAX_BYTES) {
+        throw new Error("AgentRun input envelope exceeds its protocol byte limit.");
     }
     return value;
 }
-export function serializeTurnInputEnvelope(value) {
-    if (value.protocol !== TURN_INPUT_PROTOCOL) {
-        throw new Error("Turn input protocol is unsupported.");
+export function serializeRunInputEnvelope(value) {
+    if (value.protocol !== RUN_INPUT_PROTOCOL) {
+        throw new Error("AgentRun input protocol is unsupported.");
     }
     const normalized = normalizeEnvelope(value);
     const subject = Object.entries(normalized.subject)
@@ -69,35 +70,40 @@ export function serializeTurnInputEnvelope(value) {
         .join(",");
     const snapshot = normalized.contextSnapshotRef;
     const lines = [
-        "Yui Turn input. Follow the Session Manifest and injected Skills.",
-        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}turn=${normalized.turnId} role=${normalized.roleName}`,
+        "Yui AgentRun input. Follow the Session Manifest and injected Skills.",
+        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}run=${normalized.runId} role=${normalized.roleName}`,
         `source=${normalized.source.type}/${normalized.source.channel} purpose=${normalized.purpose} subject=${subject || "global"} snapshot=${snapshot === undefined ? "none" : `${snapshot.id}@${snapshot.digest}`}`,
         normalized.deltaRefIds.length === 0
             ? "delta=none"
             : `delta=${normalized.deltaRefIds.join(",")}`,
-        "Load the exact Turn context before acting; fail closed if it is unavailable or mismatched."
+        ...(normalized.subject.taskId === undefined ? [] : [
+            `Load the exact AgentRun context: yui task run context ${normalized.subject.taskId}/${normalized.runId} --json.`
+        ]),
+        "Use the Session Manifest's CLI entry. Fail closed if the exact Context is unavailable or mismatched.",
+        "Then read the relevant referenced requirements and perform the assigned work. Context loading is not the deliverable.",
+        "During planning, fulfill the user's Draft discussion request without starting delivery before it is requested."
     ];
     const serialized = lines.join("\n");
-    if (Buffer.byteLength(serialized, "utf8") > TURN_INPUT_MAX_BYTES) {
-        throw new Error("Turn input envelope exceeds its protocol byte limit.");
+    if (Buffer.byteLength(serialized, "utf8") > RUN_INPUT_MAX_BYTES) {
+        throw new Error("AgentRun input envelope exceeds its protocol byte limit.");
     }
     return serialized;
 }
 /**
- * Bounded infrastructure-recovery input for an already-submitted Turn. It resumes
+ * Bounded infrastructure-recovery input for an already-submitted AgentRun. It resumes
  * the provider-native transcript after Host/child replacement and never
  * replays the Assignment or its directive.
  */
-export function serializeTurnHostRecoveryEnvelope(value) {
+export function serializeRunHostRecoveryEnvelope(value) {
     const normalized = normalizeEnvelope(value);
     const serialized = [
-        "Yui Host recovery for an existing Turn.",
-        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}turn=${normalized.turnId} role=${normalized.roleName}`,
+        "Yui Host recovery for an existing AgentRun.",
+        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}turn=${normalized.runId} role=${normalized.roleName}`,
         "Resume the same native conversation from its latest durable state. Do not repeat completed work or replay the original input.",
-        "Load the exact Turn context or delta only if needed, then continue the same Turn."
+        "Load the exact AgentRun context or delta only if needed, then continue the same AgentRun."
     ].join("\n");
-    if (Buffer.byteLength(serialized, "utf8") > TURN_INPUT_MAX_BYTES) {
-        throw new Error("Turn Host recovery envelope exceeds its protocol byte limit.");
+    if (Buffer.byteLength(serialized, "utf8") > RUN_INPUT_MAX_BYTES) {
+        throw new Error("AgentRun Host recovery envelope exceeds its protocol byte limit.");
     }
     return serialized;
 }
@@ -106,9 +112,9 @@ function normalizeInput(input) {
     const snapshot = input.contextSnapshotRef === undefined
         ? undefined
         : validateContextSnapshotRef(input.contextSnapshotRef);
-    const deltaRefIds = normalizedUniqueText(input.deltaRefIds, "Turn input delta ref");
-    if (deltaRefIds.length > TURN_INPUT_MAX_DELTAS) {
-        throw new Error(`Turn input supports at most ${TURN_INPUT_MAX_DELTAS} delta refs.`);
+    const deltaRefIds = normalizedUniqueText(input.deltaRefIds, "AgentRun input delta ref");
+    if (deltaRefIds.length > RUN_INPUT_MAX_DELTAS) {
+        throw new Error(`AgentRun input supports at most ${RUN_INPUT_MAX_DELTAS} delta refs.`);
     }
     return {
         source,
@@ -118,8 +124,8 @@ function normalizeInput(input) {
 }
 function normalizeEnvelopeContext(context, input) {
     const normalized = normalizeEnvelope({
-        protocol: TURN_INPUT_PROTOCOL,
-        turnId: context.turnId,
+        protocol: RUN_INPUT_PROTOCOL,
+        runId: context.runId,
         source: input.source,
         roleName: context.roleName,
         purpose: context.purpose,
@@ -130,33 +136,40 @@ function normalizeEnvelopeContext(context, input) {
         deltaRefIds: input.deltaRefIds
     });
     return {
-        turnId: normalized.turnId,
+        runId: normalized.runId,
         roleName: normalized.roleName,
         purpose: normalized.purpose,
         subject: normalized.subject
     };
 }
 function normalizeEnvelope(input) {
-    if (!["execution", "review", "global"].includes(input.purpose)) {
+    if (!["execution", "review", "global", "planning"].includes(input.purpose)) {
         throw new Error("Turn input purpose is invalid.");
     }
     const normalizedInput = normalizeInput(input);
     const subject = normalizeSubject(input.subject);
     if (normalizedInput.contextSnapshotRef !== undefined
         && normalizedInput.contextSnapshotRef.taskId !== subject.taskId) {
-        throw new Error("Turn input Context Snapshot belongs to another Task.");
+        throw new Error("AgentRun input Context Snapshot belongs to another Task.");
     }
     if (input.purpose !== "global" && subject.taskId === undefined) {
-        throw new Error("A Task Turn input requires a Task subject.");
+        throw new Error("A Task AgentRun input requires a Task subject.");
     }
     if (input.purpose === "review" && subject.reviewRoundId === undefined) {
-        throw new Error("A review Turn input requires a ReviewRound subject.");
+        throw new Error("A review AgentRun input requires a ReviewRound subject.");
+    }
+    if (input.purpose === "planning"
+        && (subject.workItemId !== undefined
+            || subject.reviewRoundId !== undefined
+            || subject.executionGroupId !== undefined
+            || subject.sourceExecutionGroupId !== undefined)) {
+        throw new Error("A planning Turn input carries only its Task subject.");
     }
     return {
-        protocol: TURN_INPUT_PROTOCOL,
-        turnId: requireIdentity(input.turnId, "Turn input Turn id"),
+        protocol: RUN_INPUT_PROTOCOL,
+        runId: requireIdentity(input.runId, "AgentRun input AgentRun id"),
         source: normalizedInput.source,
-        roleName: requireIdentity(input.roleName, "Turn input Role name"),
+        roleName: requireIdentity(input.roleName, "AgentRun input Role name"),
         purpose: input.purpose,
         subject,
         ...(normalizedInput.contextSnapshotRef === undefined
@@ -168,7 +181,7 @@ function normalizeEnvelope(input) {
 function normalizeSubject(subject) {
     const normalized = Object.fromEntries(Object.entries(subject).map(([key, value]) => [
         key,
-        requireIdentity(value, `Turn input ${key}`)
+        requireIdentity(value, `AgentRun input ${key}`)
     ]));
     const allowed = [
         "taskId",
@@ -179,33 +192,33 @@ function normalizeSubject(subject) {
         "sourceExecutionGroupId"
     ];
     if (Object.keys(normalized).some((key) => !allowed.includes(key))) {
-        throw new Error("Turn input subject contains an unknown field.");
+        throw new Error("AgentRun input subject contains an unknown field.");
     }
     if ((normalized.executionGroupId === undefined) !== (normalized.executionLaneId === undefined)) {
-        throw new Error("Turn input execution lineage is incomplete.");
+        throw new Error("AgentRun input execution lineage is incomplete.");
     }
     if (normalized.sourceExecutionGroupId !== undefined
         && ((normalized.workItemId === undefined && normalized.reviewRoundId === undefined)
             || normalized.executionGroupId !== undefined)) {
-        throw new Error("Turn input source ExecutionGroup requires a WorkItem or Review main subject.");
+        throw new Error("AgentRun input source ExecutionGroup requires a WorkItem or Review main subject.");
     }
     if (normalized.taskId === undefined
         && (normalized.workItemId !== undefined || normalized.reviewRoundId !== undefined
             || normalized.executionGroupId !== undefined
             || normalized.sourceExecutionGroupId !== undefined)) {
-        throw new Error("Turn input child subject requires a Task id.");
+        throw new Error("AgentRun input child subject requires a Task id.");
     }
     return Object.freeze(normalized);
 }
 function normalizeSource(source) {
-    if (source.type === "yui" && YUI_TURN_INPUT_CHANNELS.includes(source.channel)) {
+    if (source.type === "yui" && YUI_RUN_INPUT_CHANNELS.includes(source.channel)) {
         return Object.freeze({ type: "yui", channel: source.channel });
     }
     if (source.type === "user" && source.channel === "direct") {
         return Object.freeze({ type: "user", channel: "direct" });
     }
-    if (source.type === "provider" && source.channel === "goal-continuation") {
-        return Object.freeze({ type: "provider", channel: "goal-continuation" });
+    if (source.type === "provider" && (source.channel === "goal-continuation" || source.channel === "visible-input")) {
+        return Object.freeze({ type: "provider", channel: source.channel });
     }
-    throw new Error("Turn input source is invalid.");
+    throw new Error("AgentRun input source is invalid.");
 }

package/dist/context/sessionBootstrapManifest.js

@@ -5,6 +5,22 @@ import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 export { SESSION_BOOTSTRAP_MANIFEST_SCHEMA_VERSION, SESSION_CONTEXT_PROTOCOL, sessionManifestCompatibilityDigest } from "./sessionProtocolIdentity.js";
 const ordinarySessionCli = ["#!/bin/sh", "exec yui \"$@\"", ""].join("\n");
+/** Portable read pointers accompany every managed input, including the first
+ * notification on a fresh Session. No Task content or credentials are copied. */
+export function withSessionContextPointer(text, environment) {
+    const manifest = environment.YUI_SESSION_MANIFEST;
+    if (manifest === undefined)
+        return text;
+    return [
+        `Read the Yui Session Manifest at ${manifest}.`,
+        "Follow its referenced Role Skills and role profile. It gives the exact Context load command.",
+        ...(environment.YUI_SESSION_CLI === undefined ? [] : [
+            `Use this absolute CLI entry for Yui commands: ${environment.YUI_SESSION_CLI}`
+        ]),
+        "",
+        text
+    ].join("\n");
+}
 /**
  * A managed Session wrapper answers exactly one question: which installation
  * runs this command. It therefore carries only the resolved entry point, never
@@ -137,8 +153,11 @@ export function materializeSessionBootstrap(input) {
                 loadCommand: renderGlobalContextCommand(input.entryPoint, home, input.role.name)
             }
             : {
-                loadCommand: "\"$YUI_SESSION_CLI\" task turn context \"$YUI_TASK_ID/<turn-id>\" --json",
-                expandCommand: "\"$YUI_SESSION_CLI\" task turn context expand \"$YUI_TASK_ID/<turn-id>\" <ref-id> --store <store> --mode full --json"
+                loadCommand: "\"$YUI_SESSION_CLI\" task run context \"$YUI_TASK_ID/<run-id>\" --json",
+                expandCommand: "\"$YUI_SESSION_CLI\" task run context expand \"$YUI_TASK_ID/<run-id>\" <ref-id> --store <store> --mode full --json",
+                ...(input.role.name === "leader" ? {
+                    currentCommand: "\"$YUI_SESSION_CLI\" task context \"$YUI_TASK_ID\" --json"
+                } : {})
             }
     };
     const manifest = Object.freeze({ ...body, digest: digest(body) });

package/dist/context/sourceRunContext.js

@@ -0,0 +1,30 @@
+import { MAX_RUN_RESULT_OUTPUT_BYTES } from "../domain/agentResultTransport.js";
+export const MAX_SYNTHESIS_SOURCE_RUNS = 8;
+export const MAX_CONTEXT_SOURCE_RUNS = MAX_SYNTHESIS_SOURCE_RUNS + 1;
+export const MAX_CONTEXT_SOURCE_RUN_BYTES = MAX_CONTEXT_SOURCE_RUNS * (MAX_RUN_RESULT_OUTPUT_BYTES + 16 * 1024);
+/**
+ * Frozen input for synthesis. The main Agent needs the producer identity and
+ * exact result, not another copy of its prompt history, launch configuration,
+ * or workspace descriptor.
+ */
+export function sourceRunContextValue(run) {
+    if (run.result === undefined) {
+        throw new Error(`Source AgentRun has no result: ${run.id}.`);
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        id: run.id,
+        taskId: run.taskId,
+        roleName: run.roleName,
+        purpose: run.purpose,
+        ...(run.workItemId === undefined ? {} : { workItemId: run.workItemId }),
+        ...(run.reviewRoundId === undefined ? {} : { reviewRoundId: run.reviewRoundId }),
+        ...(run.executionGroupId === undefined
+            ? {}
+            : { executionGroupId: run.executionGroupId }),
+        ...(run.executionLaneId === undefined ? {} : { executionLaneId: run.executionLaneId }),
+        result: run.result,
+        createdAt: run.createdAt,
+        updatedAt: run.updatedAt
+    });
+}