@zq-silk/yui 0.2.0 → 0.4.2

package/dist/role/role.js

@@ -1,29 +1,39 @@
+import { isDeepStrictEqual } from "node:util";
+import { defaultRoleAgentConfig, resolveAgentAdapter } from "../executor/agentAdapter.js";
+import { validateRoleSessionSet } from "../executor/agentExecutor.js";
 export function createRoleAgentBinding(agent, config) {
     const agentId = requireSafeIdentity(agent.id, "Role Agent id");
     const adapterId = requireSupportedAdapterId(agent.adapterId);
-    const effectiveConfig = config ?? { adapterId };
+    const defaults = defaultRoleAgentConfig(adapterId);
+    const effectiveConfig = config === undefined
+        ? defaults
+        : config.permission === undefined
+            ? { ...config, permission: defaults.permission }
+            : config;
     if (effectiveConfig.adapterId !== adapterId) {
         throw new Error(`Role Agent config adapter does not match Agent: ${agentId}.`);
     }
     return cloneBinding({ agentId, adapterId, config: effectiveConfig });
 }
-export function createRole(taskId, name, bindings, activeAgentId, workspace, now, profile = {}) {
-    const owner = createRoleOwner(name, bindings, activeAgentId, workspace, now, profile);
+export function createRole(taskId, name, bindings, activeAgentId, workspace, now, profile = {}, defaultAccess = "write") {
+    const owner = createRoleOwner(name, bindings, activeAgentId, workspace, now, profile, defaultAccess);
     return validateTaskRole({
         ...owner,
         taskId: requireSafeIdentity(taskId, "Task id"),
         status: "idle"
     });
 }
-export function createGlobalRole(name, bindings, activeAgentId, workspace, now, profile = {}) {
-    return createRoleOwner(name, bindings, activeAgentId, workspace, now, profile);
+export function createGlobalRole(name, bindings, activeAgentId, workspace, now, profile = {}, defaultAccess = "write") {
+    return createRoleOwner(name, bindings, activeAgentId, workspace, now, profile, defaultAccess);
 }
 export function copyGlobalRoleToTaskRole(globalRole, taskId, now, name = globalRole.name) {
     validateGlobalRole(globalRole);
     const timestamp = now.toISOString();
     return validateTaskRole({
         ...cloneProfile(globalRole),
-        schemaVersion: 2,
+        schemaVersion: 3,
+        launchRevision: 1,
+        defaultAccess: globalRole.defaultAccess,
         taskId: requireSafeIdentity(taskId, "Task id"),
         name: requireSafeIdentity(name, "Role name"),
         activeAgentId: globalRole.activeAgentId,
@@ -40,22 +50,30 @@ export function activeRoleAgentBinding(role) {
 }
 export function updateGlobalRole(role, patch, now) {
     validateGlobalRole(role);
+    const desiredBefore = desiredLaunchProjection(role);
     const updated = {
         ...role,
         ...cloneRolePatch(patch),
         updatedAt: now.toISOString()
     };
     clearProfileFields(updated, patch);
+    updated.launchRevision = isDeepStrictEqual(desiredBefore, desiredLaunchProjection(updated))
+        ? role.launchRevision
+        : role.launchRevision + 1;
     return validateGlobalRole(updated);
 }
 export function updateRole(role, patch, now) {
     validateTaskRole(role);
+    const desiredBefore = desiredLaunchProjection(role);
     const updated = {
         ...role,
         ...cloneRolePatch(patch),
         updatedAt: now.toISOString()
     };
     clearProfileFields(updated, patch);
+    updated.launchRevision = isDeepStrictEqual(desiredBefore, desiredLaunchProjection(updated))
+        ? role.launchRevision
+        : role.launchRevision + 1;
     return validateTaskRole(updated);
 }
 export function updateRoleStatus(role, status, now) {
@@ -66,31 +84,26 @@ export function updateRoleStatus(role, status, now) {
 }
 export function switchActiveRoleAgent(role, sessions, targetAgentId, runtime, now) {
     validateRoleOwner(role);
-    if (runtime.activeRun) {
-        throw new Error("Cannot switch Role Agent while an active AgentRun exists.");
-    }
-    if (runtime.nativeProcessRunning) {
-        throw new Error("Cannot switch Role Agent while the native Agent process is running.");
-    }
     const normalizedTarget = requireSafeIdentity(targetAgentId, "Target Agent id");
     if (!Object.hasOwn(role.agentBindings, normalizedTarget)) {
         throw new Error(`Role Agent is not bound: ${normalizedTarget}.`);
     }
     assertSessionOwnerMatchesRole(role, sessions);
-    if (sessions.activeAgentId !== role.activeAgentId) {
-        throw new Error(`Role session active Agent does not match Role: ${role.name}.`);
-    }
     const fromAgentId = role.activeAgentId;
     const mode = sessions.sessions[normalizedTarget] === undefined ? "new" : "resume";
     const timestamp = now.toISOString();
     const updatedRole = "taskId" in role
         ? updateRole(role, { activeAgentId: normalizedTarget }, now)
         : updateGlobalRole(role, { activeAgentId: normalizedTarget }, now);
-    const updatedSessions = {
-        ...sessions,
-        activeAgentId: normalizedTarget,
-        updatedAt: timestamp
-    };
+    // A running process keeps its immutable effective identity. The desired
+    // switch becomes visible only when the next launch is planned.
+    const updatedSessions = runtime.activeRun || runtime.nativeProcessRunning
+        ? sessions
+        : {
+            ...sessions,
+            activeAgentId: normalizedTarget,
+            updatedAt: timestamp
+        };
     return {
         role: updatedRole,
         sessions: updatedSessions,
@@ -101,6 +114,62 @@ export function switchActiveRoleAgent(role, sessions, targetAgentId, runtime, no
         }
     };
 }
+export function unbindRoleAgent(role, sessions, agentId, now) {
+    validateRoleOwner(role);
+    const normalizedAgentId = requireSafeIdentity(agentId, "Role Agent id");
+    if (normalizedAgentId === role.activeAgentId) {
+        throw new Error(`Cannot unbind active Role Agent: ${normalizedAgentId}.`);
+    }
+    if (!Object.hasOwn(role.agentBindings, normalizedAgentId)) {
+        throw new Error(`Role Agent is not bound: ${normalizedAgentId}.`);
+    }
+    let updatedSessions = sessions;
+    if (sessions !== null) {
+        validateRoleSessionSet(sessions);
+        assertSessionOwnerMatchesRole(role, sessions);
+        const taskSessions = sessions.owner.scope === "task"
+            ? sessions
+            : null;
+        if (taskSessions?.inFlight?.agentId === normalizedAgentId) {
+            throw new Error(`Cannot unbind Role Agent with an active Run: ${normalizedAgentId}.`);
+        }
+        const targetSession = sessions.sessions[normalizedAgentId];
+        if (targetSession !== undefined && targetSession.status !== "stopped") {
+            throw new Error(`Cannot unbind Role Agent while its native session is ${targetSession.status}: `
+                + `${normalizedAgentId}.`);
+        }
+        const globalSessions = sessions.owner.scope === "global"
+            ? sessions
+            : null;
+        const targetHistory = globalSessions === null
+            ? []
+            : Object.entries(globalSessions.history ?? {}).filter(([, session]) => (session.agentId === normalizedAgentId));
+        const targetTaskHistory = (taskSessions?.history ?? []).filter((session) => (session.agentId === normalizedAgentId));
+        if (targetSession !== undefined || targetHistory.length > 0 || targetTaskHistory.length > 0) {
+            const remainingSessions = { ...sessions.sessions };
+            delete remainingSessions[normalizedAgentId];
+            const remainingHistory = globalSessions === null
+                ? undefined
+                : Object.fromEntries(Object.entries(globalSessions.history ?? {}).filter(([, session]) => (session.agentId !== normalizedAgentId)));
+            const remainingTaskHistory = taskSessions === null
+                ? undefined
+                : (taskSessions.history ?? []).filter((session) => (session.agentId !== normalizedAgentId));
+            updatedSessions = validateRoleSessionSet({
+                ...sessions,
+                sessions: remainingSessions,
+                ...(remainingHistory === undefined ? {} : { history: remainingHistory }),
+                ...(remainingTaskHistory === undefined ? {} : { history: remainingTaskHistory }),
+                updatedAt: now.toISOString()
+            });
+        }
+    }
+    const remainingBindings = { ...role.agentBindings };
+    delete remainingBindings[normalizedAgentId];
+    const updatedRole = "taskId" in role
+        ? updateRole(role, { agentBindings: remainingBindings }, now)
+        : updateGlobalRole(role, { agentBindings: remainingBindings }, now);
+    return { role: updatedRole, sessions: updatedSessions };
+}
 export function validateGlobalRole(role) {
     return validateRoleOwner(role);
 }
@@ -110,7 +179,7 @@ export function validateTaskRole(role) {
         throw new Error(`Role status is invalid: ${role.status}.`);
     return validateRoleOwner(role);
 }
-function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile) {
+function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile, defaultAccess) {
     const mappedBindings = {};
     for (const sourceBinding of bindings) {
         const binding = validateRoleAgentBinding(cloneBinding(sourceBinding));
@@ -122,7 +191,9 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile)
     const timestamp = now.toISOString();
     return validateGlobalRole({
         ...cloneProfile(profile),
-        schemaVersion: 2,
+        schemaVersion: 3,
+        launchRevision: 1,
+        defaultAccess,
         name: requireSafeIdentity(name, "Role name"),
         activeAgentId: requireSafeIdentity(activeAgentId, "Role active Agent id"),
         agentBindings: mappedBindings,
@@ -132,19 +203,34 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile)
     });
 }
 function validateRoleOwner(role) {
-    if (role.schemaVersion !== 2)
+    if (role.schemaVersion !== 3)
         throw new Error("Role schema version is invalid.");
+    if (!Number.isSafeInteger(role.launchRevision) || role.launchRevision < 1) {
+        throw new Error("Role launch revision must be a positive integer.");
+    }
+    if (role.defaultAccess !== "read" && role.defaultAccess !== "write") {
+        throw new Error("Role default access is invalid.");
+    }
     requireSafeIdentity(role.name, "Role name");
     requireSafeIdentity(role.activeAgentId, "Role active Agent id");
     requireText(role.workspace, "Role workspace");
     const entries = Object.entries(role.agentBindings);
     if (entries.length === 0)
         throw new Error("Role requires at least one Agent binding.");
+    const operatorAdapters = new Map();
     for (const [agentId, binding] of entries) {
         validateRoleAgentBinding(binding);
         if (agentId !== binding.agentId) {
             throw new Error(`Role Agent binding identity is inconsistent: ${agentId}.`);
         }
+        if (!("taskId" in role) && role.name === "operator") {
+            const existingAgentId = operatorAdapters.get(binding.adapterId);
+            if (existingAgentId !== undefined) {
+                throw new Error("Operator supports one Agent per adapter; "
+                    + `${binding.adapterId} is bound to both ${existingAgentId} and ${agentId}.`);
+            }
+            operatorAdapters.set(binding.adapterId, agentId);
+        }
     }
     if (!Object.hasOwn(role.agentBindings, role.activeAgentId)) {
         throw new Error(`Role active Agent is not bound: ${role.activeAgentId}.`);
@@ -160,6 +246,10 @@ function validateRoleAgentBinding(binding) {
     if (binding.config.adapterId !== adapterId) {
         throw new Error(`Role Agent binding adapter is inconsistent: ${agentId}.`);
     }
+    if (binding.config.permission === undefined) {
+        throw new Error(`Role Agent binding requires an explicit permission strategy: ${agentId}.`);
+    }
+    resolveAgentAdapter(adapterId).canonicalizeConfig(binding.config);
     return binding;
 }
 function assertSessionOwnerMatchesRole(role, sessions) {
@@ -178,10 +268,21 @@ function cloneRolePatch(patch) {
             ? {}
             : { activeAgentId: requireSafeIdentity(patch.activeAgentId, "Role active Agent id") }),
         ...(patch.workspace === undefined ? {} : { workspace: requireText(patch.workspace, "Role workspace") }),
+        ...(patch.defaultAccess === undefined ? {} : { defaultAccess: patch.defaultAccess }),
         ...(patch.agentBindings === undefined ? {} : { agentBindings: cloneBindings(patch.agentBindings) }),
         ...cloneProfile(patch)
     };
 }
+function desiredLaunchProjection(role) {
+    return {
+        name: role.name,
+        activeAgentId: role.activeAgentId,
+        agentBindings: role.agentBindings,
+        workspace: role.workspace,
+        defaultAccess: role.defaultAccess,
+        ...cloneProfile(role)
+    };
+}
 function cloneBindings(bindings) {
     return Object.fromEntries(Object.entries(bindings).map(([agentId, binding]) => [agentId, cloneBinding(binding)]));
 }

package/dist/run/agentRun.js

@@ -1,18 +1,35 @@
-export function createAgentRun(id, taskId, roleName, mode, input, now, context = {}) {
+import { validateEffectiveLaunchSnapshot } from "../executor/effectiveLaunch.js";
+import { validateTaskRecordReference } from "../task/taskRecordReference.js";
+import { validateManagedWorkspace } from "../worktree/managedWorkspace.js";
+export function createAgentRun(id, taskId, roleName, mode, input, now, context) {
     if (mode !== "new" && mode !== "resume") {
         throw new Error(`Agent run dispatch mode is invalid: ${mode}.`);
     }
     const timestamp = now.toISOString();
     return {
-        schemaVersion: 1,
+        schemaVersion: 6,
         id: requireSafeIdentity(id, "Agent run id"),
         taskId: requireSafeIdentity(taskId, "Task id"),
         roleName: requireSafeIdentity(roleName, "Role name"),
         mode,
         input: requireText(input, "Agent run input"),
+        purpose: context.purpose ?? "execution",
         ...(context.workItemId === undefined
             ? {}
             : { workItemId: requireSafeIdentity(context.workItemId, "Work item id") }),
+        ...(context.reviewRoundId === undefined
+            ? {}
+            : { reviewRoundId: requireSafeIdentity(context.reviewRoundId, "ReviewRound id") }),
+        ...(context.executionGroupId === undefined
+            ? {}
+            : { executionGroupId: requireSafeIdentity(context.executionGroupId, "ExecutionGroup id") }),
+        ...(context.executionLaneId === undefined
+            ? {}
+            : { executionLaneId: requireSafeIdentity(context.executionLaneId, "ExecutionLane id") }),
+        ...(context.workspace === undefined
+            ? {}
+            : { workspace: validateManagedWorkspace(context.workspace) }),
+        effective: validateEffectiveLaunchSnapshot(context.effective),
         status: "active",
         createdAt: timestamp,
         updatedAt: timestamp
@@ -21,6 +38,15 @@ export function createAgentRun(id, taskId, roleName, mode, input, now, context =
 export function isActiveAgentRun(run) {
     return run.status === "active";
 }
+export function markAgentRunPushed(run, now) {
+    if (run.status !== "active") {
+        throw new Error(`Cannot push a terminal Agent run: ${run.id}.`);
+    }
+    if (run.pushedAt !== undefined)
+        return run;
+    const timestamp = now.toISOString();
+    return { ...run, pushedAt: timestamp, updatedAt: timestamp };
+}
 export function markAgentRunDelivered(run, now) {
     if (run.status !== "active") {
         throw new Error(`Cannot deliver a terminal Agent run: ${run.id}.`);
@@ -28,27 +54,136 @@ export function markAgentRunDelivered(run, now) {
     if (run.deliveredAt !== undefined)
         return run;
     const timestamp = now.toISOString();
-    return { ...run, deliveredAt: timestamp, updatedAt: timestamp };
+    // Acceptance implies the prompt was pushed first; record both so a consumer
+    // never sees delivered-without-pushed.
+    return {
+        ...run,
+        ...(run.pushedAt === undefined ? { pushedAt: timestamp } : {}),
+        deliveredAt: timestamp,
+        updatedAt: timestamp
+    };
 }
 export function validateAgentRun(run) {
-    if (run.schemaVersion !== 1)
-        throw new Error("Agent run must use schemaVersion 1.");
-    requireSafeIdentity(run.id, "Agent run id");
-    requireSafeIdentity(run.taskId, "Task id");
+    if (run.schemaVersion !== 6)
+        throw new Error("Agent run must use schemaVersion 6.");
+    validateTaskRecordReference({ taskId: run.taskId, localId: run.id }, "agentRun");
     requireSafeIdentity(run.roleName, "Role name");
     if (run.mode !== "new" && run.mode !== "resume") {
         throw new Error(`Agent run dispatch mode is invalid: ${String(run.mode)}.`);
     }
     requireText(run.input, "Agent run input");
-    if (run.workItemId !== undefined)
-        requireSafeIdentity(run.workItemId, "Work item id");
+    if (!["execution", "review"].includes(run.purpose)) {
+        throw new Error(`Agent run purpose is invalid: ${String(run.purpose)}.`);
+    }
+    if (run.workItemId !== undefined) {
+        validateTaskRecordReference({ taskId: run.taskId, localId: run.workItemId }, "workItem");
+    }
+    if (run.reviewRoundId !== undefined) {
+        validateTaskRecordReference({ taskId: run.taskId, localId: run.reviewRoundId }, "reviewRound");
+    }
+    if ((run.executionGroupId === undefined) !== (run.executionLaneId === undefined)) {
+        throw new Error("Agent run execution lineage is incomplete.");
+    }
+    if (run.executionGroupId !== undefined) {
+        requireSafeIdentity(run.executionGroupId, "ExecutionGroup id");
+        requireSafeIdentity(run.executionLaneId, "ExecutionLane id");
+    }
+    if (run.workspace !== undefined) {
+        validateManagedWorkspace(run.workspace);
+        if (run.workspace.owner.taskId !== run.taskId) {
+            throw new Error("Agent run workspace belongs to another Task.");
+        }
+        if (run.workspace.owner.type === "work-item"
+            && run.workspace.owner.workItemId !== run.workItemId) {
+            throw new Error("Agent run workspace belongs to another Work Item.");
+        }
+        if (run.workspace.owner.type === "work-item" && run.workItemId === undefined) {
+            throw new Error("A WorkItem workspace requires a WorkItem Agent run reference.");
+        }
+        if (run.workspace.owner.type === "review-round" && run.purpose !== "review") {
+            throw new Error("A ReviewRound workspace requires a review Agent run.");
+        }
+        if (run.workspace.owner.type === "integration-attempt") {
+            throw new Error("An IntegrationAttempt workspace cannot be used by an Agent run.");
+        }
+        if (run.workspace.owner.type === "execution-lane") {
+            if (run.workspace.owner.executionGroupId !== run.executionGroupId
+                || run.workspace.owner.executionLaneId !== run.executionLaneId) {
+                throw new Error("Agent run Execution Lane workspace lineage does not match the Run.");
+            }
+            if (run.workspace.owner.purpose === "execution"
+                && run.workspace.owner.workItemId !== run.workItemId) {
+                throw new Error("Agent run Execution Lane workspace WorkItem does not match the Run.");
+            }
+            if (run.workspace.owner.purpose === "review"
+                && run.workspace.owner.reviewRoundId !== run.reviewRoundId) {
+                throw new Error("Agent run review Lane workspace ReviewRound does not match the Run.");
+            }
+        }
+        if (run.workspace.owner.type === "review-round"
+            && run.workspace.owner.reviewRoundId !== run.reviewRoundId) {
+            throw new Error(`Agent run ReviewRound workspace owner does not match ${run.reviewRoundId ?? "none"}.`);
+        }
+    }
+    if (run.purpose === "review") {
+        if (run.workItemId === undefined || run.reviewRoundId === undefined) {
+            throw new Error("A review Agent run requires WorkItem and ReviewRound references.");
+        }
+        if (run.workspace === undefined
+            || !((run.workspace.owner.type === "review-round"
+                && run.workspace.owner.reviewRoundId === run.reviewRoundId)
+                || (run.workspace.owner.type === "execution-lane"
+                    && run.workspace.owner.purpose === "review"
+                    && run.workspace.owner.reviewRoundId === run.reviewRoundId))) {
+            throw new Error(`A review Agent run requires its exact ReviewRound workspace owner: ${run.reviewRoundId}.`);
+        }
+        if (run.workspace.entries.length === 0
+            || run.workspace.entries.some(({ access }) => access !== "write")) {
+            throw new Error("A review Agent run requires only isolated writable workspace entries.");
+        }
+    }
+    else {
+        if (run.reviewRoundId !== undefined) {
+            throw new Error("An execution Agent run cannot reference a ReviewRound.");
+        }
+        if (run.workspace?.owner.type === "review-round") {
+            throw new Error("An execution Agent run cannot use a ReviewRound-owned workspace.");
+        }
+        if (run.workspace?.owner.type === "execution-lane" && run.workspace.owner.purpose !== "execution") {
+            throw new Error("An execution Agent run cannot use a review Lane workspace.");
+        }
+    }
+    validateEffectiveLaunchSnapshot(run.effective);
+    if (run.workspace !== undefined
+        && (run.effective.workspace.root !== run.workspace.root
+            || JSON.stringify(run.effective.workspace.entries) !== JSON.stringify(run.workspace.entries))) {
+        throw new Error("Agent run effective workspace does not match its managed workspace.");
+    }
+    if (run.purpose === "review") {
+        if (run.effective.reviewRoundId !== run.reviewRoundId) {
+            throw new Error("Review Agent run effective provenance does not match its ReviewRound.");
+        }
+        if (!run.workspace.entries.some(({ baseCommit }) => baseCommit === run.effective.reviewBaseCommit)) {
+            throw new Error("Review Agent run effective base does not match its workspace.");
+        }
+    }
+    else if (run.effective.reviewRoundId !== undefined) {
+        throw new Error("Execution Agent run cannot carry Review effective provenance.");
+    }
     if (!["active", "yielded", "failed"].includes(run.status)) {
         throw new Error(`Agent run status is invalid: ${String(run.status)}.`);
     }
     requireTimestamp(run.createdAt, "Agent run createdAt");
     requireTimestamp(run.updatedAt, "Agent run updatedAt");
-    if (run.deliveredAt !== undefined)
+    if (run.pushedAt !== undefined)
+        requireTimestamp(run.pushedAt, "Agent run pushedAt");
+    if (run.deliveredAt !== undefined) {
         requireTimestamp(run.deliveredAt, "Agent run deliveredAt");
+        // Acceptance can never precede its transport push.
+        if (run.pushedAt === undefined) {
+            throw new Error("Agent run deliveredAt requires a prior pushedAt.");
+        }
+    }
     if (run.status === "active") {
         if (run.summary !== undefined || run.endedAt !== undefined) {
             throw new Error("An active Agent run cannot have terminal metadata.");
@@ -61,10 +196,10 @@ export function validateAgentRun(run) {
     return run;
 }
 export function yieldAgentRun(run, summary, now) {
-    return finishAgentRun(run, "yielded", requireText(summary, "Agent run summary"), now);
+    return finishAgentRun(run, "yielded", requireResultText(summary, "Agent run summary"), now);
 }
 export function failAgentRun(run, summary, now) {
-    return finishAgentRun(run, "failed", requireText(summary, "Agent run summary"), now);
+    return finishAgentRun(run, "failed", requireResultText(summary, "Agent run summary"), now);
 }
 function finishAgentRun(run, status, summary, now) {
     if (run.status !== "active") {
@@ -95,6 +230,14 @@ function requireText(value, label) {
         throw new Error(`${label} is required.`);
     return normalized;
 }
+/** Result transport preserves the provider's complete text, including outer whitespace. */
+function requireResultText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    if (value.trim().length === 0)
+        throw new Error(`${label} is required.`);
+    return value;
+}
 function requireTimestamp(value, label) {
     if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
         throw new Error(`${label} must be an ISO timestamp.`);

package/dist/run/runIdentity.js

@@ -0,0 +1,82 @@
+import { MAX_SESSION_TITLE_LENGTH } from "../runtime/sessionTitle.js";
+const TITLED_RUN_SEPARATOR = " · Run ";
+/** Adds the causal token consumed by the native Turn-complete Hook. */
+export function markYuiRunInput(input, runId, title) {
+    const text = input.replace(/\r/g, "").trim();
+    return managedRunInput(text, runId, title);
+}
+/** Replaces the causal token on an input already owned by a persisted Yui Run. */
+export function retagYuiRunInput(input, runId, title) {
+    const lines = input.replace(/\r/g, "").split("\n");
+    if (lines.length < 3
+        || lines[1] !== ""
+        || runIdFromHeader(lines[0]) === undefined) {
+        throw new Error("Managed Run input header is required.");
+    }
+    return managedRunInput(lines.slice(2).join("\n").trim(), runId, title);
+}
+function managedRunInput(text, runId, title) {
+    const id = requireRunId(runId);
+    if (text.length === 0)
+        throw new Error("Run input is required.");
+    return `${requireRunTitle(title)}${TITLED_RUN_SEPARATOR}${id}\n\n${text}`;
+}
+/** Reads the last managed Yui header from Codex's structured input-messages. */
+export function yuiRunIdFromInputMessages(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    let found;
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            continue;
+        const lines = entry.replace(/\r/g, "").split("\n");
+        if (lines.length < 3 || lines[1] !== "")
+            continue;
+        const runId = runIdFromHeader(lines[0]);
+        if (runId !== undefined)
+            found = runId;
+    }
+    return found;
+}
+/** Removes only a valid managed Run header, preserving user-authored lookalikes. */
+export function yuiRunBodyFromInputMessage(value) {
+    const lines = value.replace(/\r/g, "").trim().split("\n");
+    return lines.length >= 3
+        && lines[1] === ""
+        && runIdFromHeader(lines[0]) !== undefined
+        ? lines.slice(2).join("\n")
+        : lines.join("\n");
+}
+function runIdFromHeader(line) {
+    const separator = line.lastIndexOf(TITLED_RUN_SEPARATOR);
+    if (separator > 0) {
+        try {
+            requireRunTitle(line.slice(0, separator));
+            return requireRunId(line.slice(separator + TITLED_RUN_SEPARATOR.length));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function requireRunTitle(value) {
+    const title = value.trim();
+    if (title.length === 0
+        || title.length > MAX_SESSION_TITLE_LENGTH
+        || !title.startsWith("Yui · ")
+        || /[\r\n\0]/u.test(title)) {
+        throw new Error("Run title is invalid.");
+    }
+    return title;
+}
+function requireRunId(value) {
+    const id = value.trim();
+    if (id.length === 0
+        || id.length > 1_024
+        || ["__proto__", "prototype", "constructor", ".", ".."].includes(id)
+        || /[\/\\\0\s]/.test(id)) {
+        throw new Error("Run id is invalid.");
+    }
+    return id;
+}