@zq-silk/yui 0.13.9 → 0.14.0

package/skills/yui-runtime/SKILL.md

@@ -1,25 +1,25 @@
 ---
 name: yui-runtime
-description: Load and use the authorized context for every Yui-managed Leader, Worker, Reviewer, Operator, or custom Role Run, and complete that Run through its bounded control-plane protocol.
+description: Load and use the authorized context for every Yui-managed Leader, Worker, Reviewer, Operator, or custom Role Turn, and complete that Turn through its bounded control-plane protocol.
 ---
 
 # Yui Runtime
 
-Treat the Session Manifest and Run Bootstrap Envelope as pointers, never as the
+Treat the Session Manifest and Turn Bootstrap Envelope as pointers, never as the
 Task brief. Do not infer Task facts from the launch command, process list,
-workspace layout, native transcript, or an earlier Run.
+workspace layout, native transcript, or an earlier Turn.
 
-For every managed Task Run:
+For every managed Task Turn:
 
-1. Read the exact Run identity from the newest Bootstrap Envelope.
+1. Read the exact Turn identity from the newest Bootstrap Envelope.
 2. Before acting, load its authorized pack with the Session CLI named by the
    current Session Manifest:
 
    ```sh
-   "$YUI_SESSION_CLI" task run context "$YUI_TASK_ID/<run-id>" --json
+   "$YUI_SESSION_CLI" task turn context "$YUI_TASK_ID/<turn-id>" --json
    ```
 
-3. Verify that the returned Task, Run, Role, purpose, Snapshot digest, workspace,
+3. Verify that the returned Task, Turn, Role, purpose, Snapshot digest, workspace,
    and Adapter match the Envelope and Session Manifest. Stop and report a
    context-load failure if the pack is missing, stale, unauthorized, malformed,
    or mismatched. Never request an inline/full-prompt fallback.
@@ -28,7 +28,7 @@ For every managed Task Run:
    `refId`:
 
    ```sh
-   "$YUI_SESSION_CLI" task run context expand "$YUI_TASK_ID/<run-id>" <ref-id> --store <store> --mode full --json
+   "$YUI_SESSION_CLI" task turn context expand "$YUI_TASK_ID/<turn-id>" <ref-id> --store <store> --mode full --json
    ```
 
    A bare `<ref-id>` remains supported only when it identifies exactly one
@@ -40,8 +40,8 @@ For every managed Task Run:
    from transcript memory.
 
 The pack's authority view and writable Project IDs are hard boundaries. A
-native subagent inherits the parent Run's refs and authority; it does not gain a
-new Yui actor, Run, Session, or cross-Task read permission.
+native subagent inherits the parent Turn's refs and authority; it does not gain a
+new Yui actor, Turn, Session, or cross-Task read permission.
 
 For a global Operator or custom GlobalRole Session, load the stable authorized view
 before routing or acting:
@@ -52,18 +52,17 @@ before routing or acting:
 
 Global context grants no Task implementation workspace. Read a Task only after
 the Operator has routed to its public/task-authorized context command; never
-invent a Task Run identity for a GlobalRole.
+invent a Task Turn identity for a GlobalRole.
 
-Provider acceptance, Context load, and workflow completion are separate facts.
-Do not treat a live pane, process output, final response, or completed Provider
-Turn as a Yui yield. For a managed Task Run, use the exact current Run's
-supported checkpoint/yield command as the final control-plane action, then stop
-immediately. If that direct command is denied or stale, report the blocker once
-and stop; do not wrap, retry, broaden permissions, or target another Run.
+Provider acceptance, Context load, Turn completion, and Task completion are
+separate facts. For a managed Task Turn, end the Provider Turn with one truthful
+final report. Yui automatically correlates that native terminal with the exact
+current Turn and persists the report; no completion command is required. The
+Leader alone decides whether the WorkItem or Task is complete.
 
 After a failed Provider Turn, read the referenced `runtime.agent-error` fact.
 The failed Turn is immutable; a recovery is always a new Turn. Continue on the
-same native Session when it remains recoverable, and load only the current Run
+same native Session when it remains recoverable, and load only the current Turn
 delta instead of replaying its original Assignment. A new Host process does not
 imply a new Session, and a new Session must never be substituted silently for
 the persisted native Session id.

package/skills/yui-worker/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: yui-worker
-description: Complete one bounded WorkItem as a native subagent or Task Role AgentRun, then return honest evidence through the assigned protocol.
+description: Complete one bounded WorkItem as a native subagent or Task Role Turn, then return honest evidence through the assigned protocol.
 ---
 
 # Yui Worker
 
-Follow `yui-runtime` first. For a managed Run, load its exact Context Pack and
+Follow `yui-runtime` first. For a managed Turn, load its exact Context Pack and
 use only the returned WorkItem, refs, workspace, writable Project IDs, and
 completion actions. The launch Envelope is a pointer, not an execution brief.
 
 Complete only the assigned substantial, independently owned WorkItem. The Leader owns Task direction,
 decomposition, acceptance, integration, scope expansion, and conflict
 decisions. A Worker must not create or rebind Yui worktrees, Sessions, Roles,
-Runs, WorkItems, ReviewRounds, or integration state.
+Turns, WorkItems, ReviewRounds, or integration state.
 
 Keep the layers distinct:
 
@@ -21,7 +21,7 @@ Keep the layers distinct:
 - This Skill supplies portable Worker behavior.
 - Agent-native Project Skills plus Project Policy and Knowledge supply build,
   test, migration, release, and review rules.
-- The exact WorkItem and Context Snapshot supply this Run's objective, scope,
+- The exact WorkItem and Context Snapshot supply this Turn's objective, scope,
   acceptance, dependencies, and evidence contract.
 
 Do not promote a Project convention into generic Worker policy or infer Task
@@ -30,8 +30,8 @@ pack.
 
 ## Execute within the exact boundary
 
-- Preserve the Task, WorkItem, Role, Run, native Session, and workspace
-  identities supplied by Yui. A new Run is another attempt or continuation of
+- Preserve the Task, WorkItem, Role, Turn, native Session, and workspace
+  identities supplied by Yui. A new Turn is another attempt or continuation of
   the same delivery unit; do not request a fresh Role or Session merely because
   implementation entered another step or repair round.
 - Follow the configured Profile's responsibilities, constraints, access
@@ -76,27 +76,25 @@ the Leader consumes it, the child may need to rerun. Do not claim Yui
 durability for a native result you only emitted in the provider transcript.
 When the child brief requires a durable, independently recoverable result,
 the Leader must dispatch the work as a Yui WorkItem/ExecutionGroup instead —
-native subagents never own a Yui Run, receipt, or workspace.
+native subagents never own a Yui Turn, receipt, or workspace.
 
-## Task Role AgentRun
+## Task Role Turn
 
 Summarize the outcome for the Leader's next judgment, not as a transcript or
 file-by-file log. Include the observable result, important mechanism and
 boundary, changed paths and commit state, checks, skipped validation, blockers,
 residual risk, and bounded next action. Use a checkpoint only for material
-semantic progress during a long Run; it does not replace the final handoff.
+semantic progress during a long Turn; it does not replace the final handoff.
 
 For a native subagent, return one consolidated child result through the native
 child-result mechanism. Do not run Yui lifecycle commands or invent a child
-Yui Session/Run.
-
-For a managed Task Role, use only the exact completion action returned by the
-Run Context Pack and follow `yui-runtime`'s direct-once/final-action rule. An
-execution yield creates immutable Candidate evidence but does not accept,
-capture, integrate, or complete the WorkItem. A review yield creates review
-evidence only; the Leader decides disposition. If the exact handoff is denied,
-stale, or mismatched, report that blocker once and stop without wrappers,
-permission broadening, or another Run target.
+Yui Session/Turn.
+
+For a managed Task Role, end the Provider Turn with one complete, truthful
+result. Yui persists it automatically on the exact Turn. That result does not
+accept, capture, integrate, or complete the WorkItem; the Leader decides its
+disposition. If context or scope is stale or mismatched, report that blocker
+once and stop without wrappers, permission broadening, or another Turn target.
 
 Leave managed workspaces intact after handoff. Their owner lifecycle and
 cleanup belong to the Leader and Yui Core.

package/dist/context/runContextContract.js

@@ -1,162 +0,0 @@
-import { normalizedUniqueIdentities, requireIdentity, requireText } from "../domain/validation.js";
-import { validateContextSnapshotRef } from "./contextSnapshot.js";
-export const RUN_CONTEXT_PROTOCOL_VERSION = 1;
-export const RUN_BOOTSTRAP_PROTOCOL = "yui-run/v1";
-export const RUN_BOOTSTRAP_MAX_BYTES = 4 * 1024;
-export const RUN_BOOTSTRAP_MAX_DELTAS = 16;
-export const RUN_ACTIONS = [
-    "lead-task",
-    "leader-wake",
-    "execute-work-item",
-    "repair-work-item",
-    "review-round",
-    "review-delta",
-    "global-request"
-];
-export function createRunAssignment(input) {
-    const common = normalizeCommon(input);
-    return Object.freeze({
-        schemaVersion: RUN_CONTEXT_PROTOCOL_VERSION,
-        ...common,
-        ...(input.directive === undefined
-            ? {}
-            : { directive: requireText(input.directive, "Run assignment directive") })
-    });
-}
-export function validateRunAssignment(value) {
-    if (value.schemaVersion !== RUN_CONTEXT_PROTOCOL_VERSION) {
-        throw new Error("Run assignment must use schemaVersion 1.");
-    }
-    const normalized = createRunAssignment(value);
-    if (JSON.stringify(normalized) !== JSON.stringify(value)) {
-        throw new Error("Run assignment is not canonical.");
-    }
-    return value;
-}
-export function createRunBootstrapEnvelope(assignment) {
-    validateRunAssignment(assignment);
-    return Object.freeze({
-        protocol: RUN_BOOTSTRAP_PROTOCOL,
-        runId: assignment.runId,
-        roleName: assignment.roleName,
-        purpose: assignment.purpose,
-        action: assignment.action,
-        subject: assignment.subject,
-        ...(assignment.contextSnapshotRef === undefined
-            ? {}
-            : { contextSnapshotRef: assignment.contextSnapshotRef }),
-        deltaRefIds: assignment.deltaRefIds
-    });
-}
-export function validateRunBootstrapEnvelope(value) {
-    if (value.protocol !== RUN_BOOTSTRAP_PROTOCOL) {
-        throw new Error("Run bootstrap protocol is unsupported.");
-    }
-    normalizeCommon(value);
-    const serialized = serializeRunBootstrapEnvelope(value);
-    if (Buffer.byteLength(serialized, "utf8") > RUN_BOOTSTRAP_MAX_BYTES) {
-        throw new Error("Run bootstrap envelope exceeds its protocol byte limit.");
-    }
-    return value;
-}
-export function serializeRunBootstrapEnvelope(value) {
-    if (value.protocol !== RUN_BOOTSTRAP_PROTOCOL) {
-        throw new Error("Run bootstrap protocol is unsupported.");
-    }
-    const normalized = normalizeCommon(value);
-    const subject = Object.entries(normalized.subject)
-        .map(([key, id]) => `${key}:${id}`)
-        .join(",");
-    const snapshot = normalized.contextSnapshotRef;
-    const lines = [
-        "Yui managed Run. Follow the Session Manifest and injected Skills.",
-        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}run=${normalized.runId} role=${normalized.roleName} action=${normalized.action}`,
-        `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 Run context before acting; fail closed if it is unavailable or mismatched."
-    ];
-    const serialized = lines.join("\n");
-    if (Buffer.byteLength(serialized, "utf8") > RUN_BOOTSTRAP_MAX_BYTES) {
-        throw new Error("Run bootstrap envelope exceeds its protocol byte limit.");
-    }
-    return serialized;
-}
-/**
- * Bounded infrastructure-recovery input for an already-pushed Run. It resumes
- * the provider-native transcript after Host/child replacement and never
- * replays the Assignment or its directive.
- */
-export function serializeRunHostRecoveryEnvelope(value) {
-    const normalized = normalizeCommon(value);
-    const serialized = [
-        "Yui managed Host recovery for an existing Run.",
-        `${normalized.subject.taskId === undefined ? "" : `task=${normalized.subject.taskId} `}run=${normalized.runId} role=${normalized.roleName}`,
-        "Resume the same native conversation from its latest durable state. Do not repeat completed work or replay the original Assignment.",
-        "Load the exact Run context or delta only if needed, then continue toward the existing workflow outcome."
-    ].join("\n");
-    if (Buffer.byteLength(serialized, "utf8") > RUN_BOOTSTRAP_MAX_BYTES) {
-        throw new Error("Run Host recovery envelope exceeds its protocol byte limit.");
-    }
-    return serialized;
-}
-function normalizeCommon(input) {
-    if (!["execution", "review", "global"].includes(input.purpose)) {
-        throw new Error("Run assignment purpose is invalid.");
-    }
-    if (!RUN_ACTIONS.includes(input.action)) {
-        throw new Error("Run assignment action is invalid.");
-    }
-    const subject = normalizeSubject(input.subject);
-    const snapshot = input.contextSnapshotRef === undefined
-        ? undefined
-        : validateContextSnapshotRef(input.contextSnapshotRef);
-    if (snapshot !== undefined && snapshot.taskId !== subject.taskId) {
-        throw new Error("Run assignment Context Snapshot belongs to another Task.");
-    }
-    if (input.purpose !== "global" && subject.taskId === undefined) {
-        throw new Error("A Task Run assignment requires a Task subject.");
-    }
-    if (input.purpose === "review" && subject.reviewRoundId === undefined) {
-        throw new Error("A review Run assignment requires a ReviewRound subject.");
-    }
-    const deltaRefIds = normalizedUniqueIdentities(input.deltaRefIds, "Run assignment delta ref");
-    if (deltaRefIds.length > RUN_BOOTSTRAP_MAX_DELTAS) {
-        throw new Error(`Run assignment supports at most ${RUN_BOOTSTRAP_MAX_DELTAS} delta refs.`);
-    }
-    return {
-        runId: requireIdentity(input.runId, "Run assignment Run id"),
-        roleName: requireIdentity(input.roleName, "Run assignment Role name"),
-        purpose: input.purpose,
-        action: input.action,
-        subject,
-        ...(snapshot === undefined ? {} : { contextSnapshotRef: snapshot }),
-        deltaRefIds
-    };
-}
-function normalizeSubject(subject) {
-    const normalized = Object.fromEntries(Object.entries(subject).map(([key, value]) => [
-        key,
-        requireIdentity(value, `Run assignment ${key}`)
-    ]));
-    const allowed = [
-        "taskId",
-        "workItemId",
-        "reviewRoundId",
-        "executionGroupId",
-        "executionLaneId"
-    ];
-    if (Object.keys(normalized).some((key) => !allowed.includes(key))) {
-        throw new Error("Run assignment subject contains an unknown field.");
-    }
-    if ((normalized.executionGroupId === undefined) !== (normalized.executionLaneId === undefined)) {
-        throw new Error("Run assignment execution lineage is incomplete.");
-    }
-    if (normalized.taskId === undefined
-        && (normalized.workItemId !== undefined || normalized.reviewRoundId !== undefined
-            || normalized.executionGroupId !== undefined)) {
-        throw new Error("Run assignment child subject requires a Task id.");
-    }
-    return Object.freeze(normalized);
-}

package/dist/executor/turnCompletion.js

@@ -1,126 +0,0 @@
-import { requireSafeIdentity, requireText, requireTimestamp } from "../runtime/validation.js";
-export const DEFAULT_RECENT_TURN_ID_LIMIT = 32;
-const PENDING_TURN_COMPLETION_FIELDS = [
-    "schemaVersion",
-    "taskId",
-    "roleName",
-    "agentId",
-    "nativeSessionId",
-    "turnId",
-    "runId",
-    "summary",
-    "observedAt",
-    "dueAt"
-];
-export function createPendingTurnCompletion(input) {
-    const observedAt = requireTimestamp(input.observedAt, "Turn observedAt");
-    const dueAt = requireTimestamp(input.dueAt, "Turn dueAt");
-    requireOrderedTimestamps(observedAt, dueAt);
-    return {
-        schemaVersion: 1,
-        taskId: requireSafeIdentity(input.taskId, "Task id"),
-        roleName: requireSafeIdentity(input.roleName, "Role name"),
-        agentId: requireSafeIdentity(input.agentId, "Agent id"),
-        nativeSessionId: requireText(input.nativeSessionId, "Native session id"),
-        turnId: requireText(input.turnId, "Turn id"),
-        runId: requireSafeIdentity(input.runId, "Run id"),
-        summary: requireText(input.summary, "Turn summary"),
-        observedAt,
-        dueAt
-    };
-}
-export function validatePendingTurnCompletion(value) {
-    const input = requireRecord(value, "PendingTurnCompletion");
-    requireExactFields(input, PENDING_TURN_COMPLETION_FIELDS, "PendingTurnCompletion");
-    if (input.schemaVersion !== 1) {
-        throw new Error("PendingTurnCompletion must use schemaVersion 1.");
-    }
-    const observedAt = requirePersistedTimestamp(input.observedAt, "PendingTurnCompletion observedAt");
-    const dueAt = requirePersistedTimestamp(input.dueAt, "PendingTurnCompletion dueAt");
-    requireOrderedTimestamps(observedAt, dueAt);
-    return {
-        schemaVersion: 1,
-        taskId: requireSafeIdentityValue(input.taskId, "Task id"),
-        roleName: requireSafeIdentityValue(input.roleName, "Role name"),
-        agentId: requireSafeIdentityValue(input.agentId, "Agent id"),
-        nativeSessionId: requireTextValue(input.nativeSessionId, "Native session id"),
-        turnId: requireTextValue(input.turnId, "Turn id"),
-        runId: requireSafeIdentityValue(input.runId, "Run id"),
-        summary: requireTextValue(input.summary, "Turn summary"),
-        observedAt,
-        dueAt
-    };
-}
-export function validateRecentTurnIds(value, limit = DEFAULT_RECENT_TURN_ID_LIMIT) {
-    const normalizedLimit = requireLimit(limit);
-    if (!Array.isArray(value))
-        throw new Error("Recent Turn ids must be an array.");
-    if (value.length > normalizedLimit) {
-        throw new Error(`Recent Turn ids must not contain more than ${normalizedLimit} entries.`);
-    }
-    const result = value.map((turnId) => requireTextValue(turnId, "Recent Turn id"));
-    if (new Set(result).size !== result.length) {
-        throw new Error("Recent Turn ids must not contain duplicates.");
-    }
-    return result;
-}
-export function rememberRecentTurnId(recentTurnIds, turnId, limit = DEFAULT_RECENT_TURN_ID_LIMIT) {
-    const normalizedLimit = requireLimit(limit);
-    const existing = validateRecentTurnIds(recentTurnIds, normalizedLimit);
-    const normalizedTurnId = requireText(turnId, "Recent Turn id");
-    return [
-        ...existing.filter((candidate) => candidate !== normalizedTurnId),
-        normalizedTurnId
-    ].slice(-normalizedLimit);
-}
-export function hasRecentTurnId(recentTurnIds, turnId) {
-    const existing = validateRecentTurnIds(recentTurnIds);
-    return existing.includes(requireText(turnId, "Recent Turn id"));
-}
-function requireOrderedTimestamps(observedAt, dueAt) {
-    if (Date.parse(dueAt) < Date.parse(observedAt)) {
-        throw new Error("PendingTurnCompletion dueAt must not be earlier than observedAt.");
-    }
-}
-function requirePersistedTimestamp(value, label) {
-    if (typeof value !== "string")
-        throw new Error(`${label} must be a valid timestamp.`);
-    const timestamp = Date.parse(value);
-    if (!Number.isFinite(timestamp))
-        throw new Error(`${label} must be a valid timestamp.`);
-    const canonical = new Date(timestamp).toISOString();
-    if (value !== canonical)
-        throw new Error(`${label} must be a canonical timestamp.`);
-    return canonical;
-}
-function requireRecord(value, label) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`${label} must be an object.`);
-    }
-    return value;
-}
-function requireExactFields(value, fields, label) {
-    const expected = new Set(fields);
-    const unknown = Object.keys(value).find((field) => !expected.has(field));
-    if (unknown !== undefined)
-        throw new Error(`${label} has unknown field: ${unknown}.`);
-    const missing = fields.find((field) => !Object.hasOwn(value, field));
-    if (missing !== undefined)
-        throw new Error(`${label} is missing field: ${missing}.`);
-}
-function requireSafeIdentityValue(value, label) {
-    if (typeof value !== "string")
-        throw new Error(`${label} is invalid.`);
-    return requireSafeIdentity(value, label);
-}
-function requireTextValue(value, label) {
-    if (typeof value !== "string")
-        throw new Error(`${label} is invalid.`);
-    return requireText(value, label);
-}
-function requireLimit(value) {
-    if (!Number.isInteger(value) || value < 1) {
-        throw new Error("Recent Turn id limit must be a positive integer.");
-    }
-    return value;
-}

package/dist/review/taskFinalReviewContractEvent.js

@@ -1 +0,0 @@
-export const TASK_FINAL_REVIEW_CONTRACT_REBOUND_EVENT = "review.task-final-contract-rebound";