@zq-silk/yui 0.15.7 → 0.15.8

package/dist/commands/roleRuntimeGuard.js

@@ -2,7 +2,7 @@ import { usageError } from "../errors/cliError.js";
 import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
 import { hasRuntimeLifecycleWork, runtimeLifecycleTarget } from "../runtime/lifecycleReservation.js";
 /**
- * Runtime launch reservation and cleanup are ownership obligations for a Role
+ * Explicit runtime cleanup is an ownership obligation for a Role
  * identity. Mutating or recreating that identity while either obligation is
  * queued can make the controller act on a different launch configuration.
  */
@@ -17,7 +17,7 @@ export const LIVE_SESSION_ACKNOWLEDGEMENT_OPTION = "--yes";
  * the desired configuration is therefore a decision about the next Host
  * activation, and the Agent making the change is the one that knows whether the
  * running Session should keep going or be replaced. Report that fact once, here,
- * instead of refusing the Turn that later resumes the Session.
+ * instead of refusing the AgentRun that later resumes the Session.
  */
 export function assertLiveRoleSessionAcknowledged(input) {
     if (input.acknowledged)
@@ -28,12 +28,11 @@ export function assertLiveRoleSessionAcknowledged(input) {
     throw usageError([
         input.endsSession === true
             ? `Role ${input.roleName} has a live native Session that cannot continue after this `
-                + "change; its next Turn will need a new Session."
+                + "change; its next AgentRun will need a new Session."
             : `Role ${input.roleName} has a live native Session, so this change applies to its `
-                + "next Host activation instead of the running one.",
+                + "next Host process instead of the running one.",
         `  Agent: ${session.agentId} (${session.adapterId})`,
         `  Native Session: ${session.nativeSessionId}`,
-        `  Host activation: ${session.runtimeGenerationId ?? "not recorded"}`,
         `  Session launched from desired revision r${session.effective.sourceDesiredRevision}; `
             + `current desired revision r${input.desiredRevision}`,
         `Re-run with ${LIVE_SESSION_ACKNOWLEDGEMENT_OPTION} to record the change and keep the Session.`,

package/dist/commands/sessionCommands.js

@@ -28,7 +28,7 @@ export async function runSessionStopCommand(input) {
         // lifecycle work that may exist without a current Session candidate.
         await input.runtime.drainController();
         await input.runtime.stopController();
-        // Re-read the authoritative facts after the drain because a Turn that was
+        // Re-read the authoritative facts after the drain because a AgentRun that was
         // already inside a pass may have changed state meanwhile.
         const settled = input.runtime.snapshot();
         const blockedAfterDrain = blockedSessions(settled);
@@ -80,7 +80,7 @@ function blockedSessions(input) {
     });
 }
 function blockedStopResult(blocked) {
-    const details = blocked.map(({ session }) => (`- ${renderSessionOwner(session)} (an active Turn or lifecycle operation is still pending)`));
+    const details = blocked.map(({ session }) => (`- ${renderSessionOwner(session)} (an active AgentRun or lifecycle operation is still pending)`));
     return {
         output: [
             `Cannot stop managed Sessions: ${blocked.length} Session(s) are still busy.`,
@@ -101,11 +101,7 @@ function sameStopCandidate(session, candidate) {
         && session.owner.taskId !== candidate.owner.taskId) {
         return false;
     }
-    return session.agentId === candidate.agentId
-        && session.adapterId === candidate.adapterId
-        && session.nativeSessionId === candidate.nativeSessionId
-        && session.runtimeGenerationId === candidate.runtimeGenerationId
-        && session.sessionUpdatedAt === candidate.sessionUpdatedAt;
+    return session.agentId === candidate.agentId && session.adapterId === candidate.adapterId && session.nativeSessionId === candidate.nativeSessionId && session.sessionUpdatedAt === candidate.sessionUpdatedAt;
 }
 function renderSessionOwner(session) {
     return session.owner.scope === "task"

package/dist/commands/taskActivationCommands.js

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import { usageError } from "../errors/cliError.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
+import { enqueueWork } from "../coordination/workMailboxQueue.js";
+import { SYSTEM_LEADER_ROLE } from "../role/systemRoles.js";
+import { describeEnvironmentPlan } from "../task/taskActivation.js";
+import { cancelTaskActivation, requestTaskActivation, taskActivationOperationRef } from "../task/taskActivationService.js";
+import { taskLocalActor } from "./taskActor.js";
+/**
+ * Explicit Activation requests.
+ *
+ * Requesting is not activating: this family only records durable intent and
+ * returns its operation reference. Adoption stays at the single activation
+ * boundary (`yui task activate`, or the Controller once a deferred request is
+ * released), where the Task status change and the resource facts commit
+ * together.
+ */
+export function runTaskActivationCommand(args, store, options) {
+    const [command, ...rest] = args;
+    switch (command) {
+        case "request": return requestActivation(rest, store, options);
+        case "cancel": return cancelActivation(rest, store, options);
+        case "show": return showActivation(rest, store);
+        default:
+            throw usageError(command === undefined
+                ? "Task activation command is required."
+                : `Unknown command: task activation ${command}`);
+    }
+}
+const REQUEST_USAGE = "Task activation request usage: yui task activation request <task> "
+    + "--request-id <id> --environment <empty|scratch|local:<resource>:<read|write>>.";
+/**
+ * Records the request and returns its reference immediately.
+ *
+ * When the caller is the Leader's own running planning Turn the request is
+ * stored as deferred and this command still returns right away: a synchronous
+ * tool must never wait for the Turn it is running inside. The Turn keeps going
+ * and the request is adopted after it terminates, against the facts that are
+ * current then.
+ */
+function requestActivation(args, store, options) {
+    const parsed = parseTail(args, new Set(["--request-id", "--environment"]), REQUEST_USAGE);
+    exactPositionals(parsed.positionals, 1, REQUEST_USAGE);
+    const taskId = parsed.positionals[0];
+    const requestId = requiredOption(parsed.options, "--request-id", REQUEST_USAGE);
+    const environmentPlan = parseEnvironmentPlan(requiredOption(parsed.options, "--environment", REQUEST_USAGE), REQUEST_USAGE);
+    const now = options.now?.() ?? new Date();
+    const caller = activationCaller(store, options, taskId);
+    const result = attempt(REQUEST_USAGE, () => requestTaskActivation(store, {
+        taskId,
+        requestId,
+        actorId: caller.actorId,
+        authorityRef: caller.authorityRef,
+        environmentPlan,
+        ...(caller.planningRunId === undefined ? {} : { callerRunId: caller.planningRunId })
+    }, now));
+    // An immediate request has nothing left to wait for, so ask the Controller to
+    // pick it up. A deferred one is released by its planning Turn's termination.
+    // The signal is only promptness: the durable request is what is authoritative.
+    if (result.created && result.startMode === "immediate") {
+        store.transaction((tx) => {
+            enqueueWork(tx, { kind: "task", taskId }, "activation-requested", now, [{ type: "task", id: taskId }]);
+        });
+        void options.runtime?.notifyMailboxChanged?.({ kind: "task", taskId });
+    }
+    const request = result.request;
+    const lines = [
+        `${result.created ? "Requested" : "Existing"} activation ${result.operationRef}`,
+        `Task: ${taskId} (draft)`,
+        `Start: ${result.startMode}${result.afterPlanningRun === undefined ? "" : ` after ${taskId}/${result.afterPlanningRun}`}`,
+        `Environment: ${describeEnvironmentPlan(request.environmentPlan)}`,
+        `Disposition: ${request.disposition}`,
+        result.startMode === "after-planning-turn"
+            ? "This reference is returned now; the request is adopted after the planning Turn ends."
+            : `Adopt it with: yui task activate ${taskId}`
+    ];
+    return output(`${lines.join("\n")}\n`, {
+        operationRef: result.operationRef,
+        created: result.created,
+        startMode: result.startMode,
+        ...(result.afterPlanningRun === undefined
+            ? {}
+            : { afterPlanningRun: result.afterPlanningRun }),
+        request
+    });
+}
+/** A cancelled request is never adopted, even if the same id is retried. */
+function cancelActivation(args, store, options) {
+    const usage = "Task activation cancel usage: yui task activation cancel <task> "
+        + "--request-id <id> --reason <text>.";
+    const parsed = parseTail(args, new Set(["--request-id", "--reason"]), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const taskId = parsed.positionals[0];
+    const requestId = requiredOption(parsed.options, "--request-id", usage);
+    const reason = requiredOption(parsed.options, "--reason", usage);
+    // Cancelling is a Task-local decision: the same authority that may request
+    // activation may withdraw it, and withdrawal is always the safe direction.
+    taskLocalActor(store, options.environment, taskId);
+    const now = options.now?.() ?? new Date();
+    const request = attempt(usage, () => cancelTaskActivation(store, taskId, requestId, reason, now));
+    return output(`Cancelled activation ${taskActivationOperationRef(taskId, requestId)}\n`
+        + `Reason: ${request.outcome ?? reason}\n`, { request });
+}
+function showActivation(args, store) {
+    const usage = "Task activation show usage: yui task activation show <task>.";
+    const parsed = parseTail(args, new Set(), usage);
+    exactPositionals(parsed.positionals, 1, usage);
+    const task = requireTask(store, parsed.positionals[0]);
+    const request = task.activationRequest;
+    // The recent terminal requests the Task still displays. The refusal itself is
+    // enforced from the durable activation event ledger, not this bounded list;
+    // showing it just lets an Operator diagnosing a refusal see the recent
+    // outcomes at a glance instead of only the latest request. An id can be
+    // refused without appearing here once it has aged out of the display bound.
+    const settled = task.settledActivationRequests ?? [];
+    const settledLines = settled.length === 0 ? [] : [
+        "",
+        `Earlier requests (${settled.length}, oldest first):`,
+        ...settled.map((entry) => (`  ${entry.operation.requestId}: ${entry.disposition}`
+            + ` / effect ${entry.operation.effect}`
+            + ` / ${describeEnvironmentPlan(entry.environmentPlan)}`
+            + `${entry.outcome === undefined ? "" : ` — ${entry.outcome}`}`))
+    ];
+    if (request === undefined) {
+        return output(`No activation request exists for ${task.id} (${task.status}).\n`
+            + (settledLines.length === 0 ? "" : `${settledLines.join("\n")}\n`), { task, request: null, settledRequests: settled });
+    }
+    const lines = [
+        `Activation ${taskActivationOperationRef(task.id, request.operation.requestId)}`,
+        `Task: ${task.id} (${task.status})`,
+        `Start: ${request.startMode}${request.afterPlanningRun === undefined ? "" : ` after ${task.id}/${request.afterPlanningRun}`}`,
+        `Environment: ${describeEnvironmentPlan(request.environmentPlan)}`,
+        `Disposition: ${request.disposition}`,
+        `Effect: ${request.operation.effect}`,
+        ...(request.preparationId === undefined
+            ? []
+            : [`Adopted environment: ${request.preparationId}`]),
+        ...(request.outcome === undefined ? [] : [`Outcome: ${request.outcome}`]),
+        `Requested at: ${request.requestedAt}`,
+        ...settledLines
+    ];
+    return output(`${lines.join("\n")}\n`, { task, request, settledRequests: settled });
+}
+/**
+ * Resolves who is requesting, and whether they are running inside this Task's
+ * own planning Turn.
+ *
+ * The start mode is derived from that fact rather than accepted from the
+ * caller: a request can only defer to a Turn the caller is actually in, and a
+ * Turn that is not an active planning Turn is simply not a deferral target.
+ */
+function activationCaller(store, options, taskId) {
+    const actor = taskLocalActor(store, options.environment, taskId);
+    if (actor === "leader") {
+        const runtime = currentManagedRuntime(store, options.environment, taskId, SYSTEM_LEADER_ROLE);
+        if (runtime === undefined) {
+            throw usageError(`Task-local Leader authority requires the current Provider AgentRun: ${taskId}.`);
+        }
+        const current = runtime.currentRunId === undefined
+            ? null
+            : store.getRun(taskId, runtime.currentRunId);
+        return {
+            actorId: `task:${taskId}/role:${SYSTEM_LEADER_ROLE}`,
+            // Non-secret binding fingerprint of the live Session, matching the Job
+            // boundary: reattaching the same Session keeps it, replacing it does not.
+            authorityRef: fingerprint([
+                runtime.agentId,
+                runtime.adapterId,
+                runtime.nativeSessionId
+            ]),
+            ...(current?.status === "active" && current.purpose === "planning"
+                ? { planningRunId: current.id }
+                : {})
+        };
+    }
+    if (actor === "operator") {
+        return {
+            actorId: "global:operator",
+            authorityRef: fingerprint([
+                "operator",
+                store.getGlobalRole("operator")?.activeAgentId ?? "operator"
+            ])
+        };
+    }
+    return { actorId: "user:local", authorityRef: fingerprint(["user", "local-terminal"]) };
+}
+function parseEnvironmentPlan(value, usage) {
+    if (value === "empty")
+        return { kind: "empty" };
+    if (value === "scratch")
+        return { kind: "scratch" };
+    const local = /^local:(?<resourceId>[^:]+):(?<access>read|write)$/u.exec(value);
+    if (local?.groups !== undefined) {
+        return {
+            kind: "local",
+            resourceId: local.groups.resourceId,
+            access: local.groups.access
+        };
+    }
+    throw usageError(`Environment plan is invalid: ${value}. Use empty, scratch, or local:<resource>:<read|write>.`, usage);
+}
+function fingerprint(parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/** Domain rejections are caller mistakes here, so they carry the usage text. */
+function attempt(usage, action) {
+    try {
+        return action();
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error), usage);
+    }
+}
+function requireTask(store, taskId) {
+    const task = store.getTask(taskId);
+    if (task === null)
+        throw usageError(`Task not found: ${taskId}.`);
+    return task;
+}
+function parseTail(args, valueOptions, usage) {
+    const positionals = [];
+    const options = new Map();
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        if (!valueOptions.has(value))
+            throw usageError(`Unsupported option: ${value}.`, usage);
+        if (options.has(value)) {
+            throw usageError(`Option may only be specified once: ${value}.`, usage);
+        }
+        const optionValue = args[index + 1];
+        if (optionValue === undefined || optionValue.startsWith("--")) {
+            throw usageError(`${value} is required.`, usage);
+        }
+        options.set(value, optionValue);
+        index += 1;
+    }
+    return { positionals, options };
+}
+function exactPositionals(values, count, usage) {
+    if (values.length !== count || values.some((value) => value.trim().length === 0)) {
+        throw usageError(usage);
+    }
+}
+function requiredOption(options, name, usage) {
+    const value = options.get(name)?.trim();
+    if (value === undefined || value.length === 0) {
+        throw usageError(`${name} is required.`, usage);
+    }
+    return value;
+}
+function output(value, data) {
+    return data === undefined
+        ? { kind: "output", output: value }
+        : { kind: "output", output: value, data };
+}

package/dist/commands/taskActor.js

@@ -1,5 +1,5 @@
 import { usageError } from "../errors/cliError.js";
-import { MANAGED_CALLER_KEY_ENV, currentManagedRuntime } from "../runtime/managedCaller.js";
+import { MANAGED_NATIVE_SESSION_ENV, currentManagedRuntime } from "../runtime/managedCaller.js";
 const LEADER_ROLE = "leader";
 export function taskActor(environment, taskId) {
     const env = environment ?? {};
@@ -18,7 +18,7 @@ export function taskActor(environment, taskId) {
     }
     if (env.YUI_ROLE !== undefined
         || env.YUI_AGENT_ID !== undefined
-        || env[MANAGED_CALLER_KEY_ENV] !== undefined) {
+        || env[MANAGED_NATIVE_SESSION_ENV] !== undefined) {
         throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
     }
     return "user";
@@ -27,15 +27,28 @@ export function taskActor(environment, taskId) {
  * Resolve authority for a recoverable Task-local mutation. A managed Leader
  * does not gain that authority from long-lived process environment alone. Its
  * process proves only that Yui launched it for this Task Role; whether it is
- * still the current runtime, and which Turn is current, are read from durable
- * state at command time. Plain-user and global-Operator behavior is unchanged.
+ * still the current Session is read from durable state at command time.
+ * Execution occupancy is not management authority.
  */
 export function taskLocalActor(store, environment, taskId) {
     const actor = taskActor(environment, taskId);
     if (actor !== "leader")
         return actor;
-    if (taskLeaderActionTurnId(store, taskId, environment) === undefined) {
-        throw usageError(`Task-local Leader authority requires the current Provider Turn: ${taskId}.`);
+    if (currentManagedRuntime(store, environment, taskId, LEADER_ROLE) === undefined) {
+        throw usageError(`Task-local Leader authority requires the current native Session: ${taskId}.`);
+    }
+    return actor;
+}
+/** Planning conversations may save facts; delivery checks the immutable
+ * native Session authority, not the Task's newly activated status.
+ */
+export function assertTaskDeliveryAuthority(store, environment, taskId) {
+    const actor = taskLocalActor(store, environment, taskId);
+    if (actor !== "leader")
+        return actor;
+    const caller = currentManagedRuntime(store, environment, taskId, LEADER_ROLE);
+    if (caller?.executionAuthority !== "delivery") {
+        throw usageError("This native Session has planning authority, not delivery authority. Use a delivery Session for this operation.");
     }
     return actor;
 }
@@ -50,31 +63,15 @@ export function projectActor(environment) {
     }
     if (env.YUI_ROLE !== undefined
         || env.YUI_AGENT_ID !== undefined
-        || env[MANAGED_CALLER_KEY_ENV] !== undefined) {
+        || env[MANAGED_NATIVE_SESSION_ENV] !== undefined) {
         throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
     }
     return "user";
 }
 /**
- * rr8: Resolve the caller identity for a `job.start`/`job.cancel` request from
- * the managed Session environment. The Controller verifies the Agent Session
- * and its scope; Role does not narrow Task control authority.
- *
- * The identity is Controller-verified rather than self-reported. A managed
- * Task Session reports only its immutable self-identity (Task, Role, caller
- * key); the Controller resolves the current Turn from durable state, so no
- * Turn is ever carried across Turns in a long-lived process environment.
- *
- * rr13: A managed Task Session also carries `callerKey` — the
- * `YUI_JOB_CALLER_KEY` injected at its native Session launch. The Controller
- * hashes it and compares against the durable `jobCallerKeyHashes` map, so a
- * client that reads durable state cannot replay the caller. A `user`-scope
- * caller is rejected outright for job.start/job.cancel (fail-closed); a
- * managed global Agent carries its own durable Session identity.
- *
- * A managed Task Session may only start jobs for its own Task. An incomplete
- * managed identity (role/agent/caller-key vars without a scope) is rejected
- * rather than silently downgraded to user authority.
+ * Resolve the caller's Task, Role and native Session identity. The Controller
+ * verifies it against durable state and supplies the current AgentRun. A Task
+ * caller cannot control another Task; an incomplete identity is not a user.
  */
 export function resolveJobCaller(environment, taskId) {
     const env = environment ?? {};
@@ -83,17 +80,14 @@ export function resolveJobCaller(environment, taskId) {
             throw usageError("A managed Task Session may not start Jobs for a different Task.");
         }
         const role = env.YUI_ROLE;
-        // rr13: Carry the per-Session caller key so the Controller can verify the
-        // channel binding. Absent on a managed Session = fail-closed at the
-        // Controller boundary.
-        const callerKey = env[MANAGED_CALLER_KEY_ENV];
-        // The Turn is deliberately absent: the Controller reads the current Turn
+        const nativeSessionId = env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID;
+        // The AgentRun is deliberately absent: the Controller reads the current AgentRun
         // for this Task Role from durable state when it authorizes the request.
         return {
             scope: "task",
             taskId,
             role,
-            ...(callerKey === undefined ? {} : { callerKey })
+            ...(nativeSessionId === undefined ? {} : { nativeSessionId })
         };
     }
     if (env.YUI_SESSION_SCOPE === "global") {
@@ -102,28 +96,13 @@ export function resolveJobCaller(environment, taskId) {
             role: env.YUI_ROLE,
             agentId: env.YUI_AGENT_ID,
             adapterId: env.YUI_ADAPTER_ID,
-            runtimeGenerationId: env.YUI_RUNTIME_GENERATION_ID,
-            nativeSessionId: env.YUI_NATIVE_SESSION_ID
+            nativeSessionId: env.CODEX_THREAD_ID ?? env.YUI_NATIVE_SESSION_ID
         };
     }
     if (env.YUI_ROLE !== undefined
         || env.YUI_AGENT_ID !== undefined
-        || env[MANAGED_CALLER_KEY_ENV] !== undefined) {
+        || env[MANAGED_NATIVE_SESSION_ENV] !== undefined) {
         throw usageError("Managed Agent identity is incomplete; refusing to infer user authority.");
     }
     return { scope: "user" };
 }
-/**
- * Resolve the current Task Leader Turn for event attribution and Task-local
- * Leader authority.
- *
- * A long-lived managed process cannot carry this: its environment is frozen at
- * launch, so any Turn it holds is stale the moment Yui advances the Task. The
- * Turn is therefore read from durable state, and the process only has to prove
- * that it is still the current runtime of the Leader Role through its
- * per-Session caller key. When the Role has no active Turn, or the process has
- * been superseded, there is simply no Leader action window.
- */
-export function taskLeaderActionTurnId(store, taskId, environment) {
-    return currentManagedRuntime(store, environment, taskId, LEADER_ROLE)?.currentTurnId;
-}