@zq-silk/yui 1.1.2 → 2.0.0

package/dist/commands/globalRoleCommands.js

@@ -1,4 +1,5 @@
 import { roleNotFound, usageError } from "../errors/cliError.js";
+import { boundedDocument, recordPage, readOptions, readDigest, messageReceipt } from "../output/boundedRead.js";
 import { controlProviderRetry, providerRetryProjection, renderProviderRetry } from "../runtime/providerRetry.js";
 import { settleGlobalRetryInput } from "../message/globalProviderRetry.js";
 import { createRoleSessionSet, recordRoleAgentSession } from "../executor/agentExecutor.js";
@@ -24,7 +25,15 @@ function inputOutput(output, data) {
     return { kind: "output", output, data };
 }
 function renderGlobalInput(result, options) {
-    return result.kind === "output" ? jsonOrText(options, result.output, result.data) : result;
+    if (result.kind === "output") {
+        const record = result.data;
+        const failure = record.steer?.code === undefined ? record.interrupt : record.steer;
+        if (failure?.code !== undefined)
+            options.onInputFailure?.({
+                code: failure.code, detail: failure.detail ?? failure.code, data: result.data
+            });
+    }
+    return result;
 }
 function assertGlobalInputAuthority(store, options, target) {
     const env = options.env ?? process.env;
@@ -71,7 +80,8 @@ export function runGlobalRoleCommand(args, store, options = {}) {
 function roleContext(args, store, options) {
     const [rawName, ...rest] = args;
     const name = roleName(rawName);
-    assertNoArguments(rest, "Session context usage: yui session context <role>");
+    const parsed = readOptions(rest, ["--cursor"]);
+    assertNoArguments(parsed.positionals, "Session context usage: yui session context <role> [--cursor <cursor>]");
     const environment = options.env ?? process.env;
     // Context reads expose durable input and runtime facts without delivering it.
     const selfRead = environment.YUI_SESSION_SCOPE !== undefined;
@@ -89,18 +99,12 @@ function roleContext(args, store, options) {
     const sessions = store.getGlobalRoleSessionSet(name);
     const session = sessions?.sessions[role.activeAgentId];
     // Only the controlled Endpoint's accepted receipt consumes a queued Message.
-    const queued = store.listGlobalRoleMessages(name).filter((message) => message.delivery === undefined
+    const messages = store.listGlobalRoleMessages(name);
+    const queued = messages.filter((message) => message.delivery === undefined
         && message.notDelivered === undefined
         && (message.interruptThen !== undefined || message.inputControl?.action === "queue"));
-    const pendingQueue = queued.map((message) => ({
-        id: message.id,
-        requestId: message.interruptThen?.requestId ?? message.inputControl?.requestId,
-        body: message.body,
-        ...(message.control === undefined ? {} : { control: message.control }),
-        ...(message.deliveryTarget === undefined ? {} : { deliveryTarget: message.deliveryTarget }),
-        ...(message.interruptThen === undefined ? {} : { interruptThen: true }),
-        ...(message.delivery === undefined ? {} : { deliveredAt: message.delivery.deliveredAt })
-    }));
+    const pending = recordPage(queued.map(globalMessageSummary), `global:${name}/messages/pending`, { limit: 8 });
+    const recent = recordPage([...messages].reverse().map(globalMessageSummary), `global:${name}/messages/all`, { limit: 8 });
     const context = Object.freeze({
         schemaVersion: 1,
         protocol: "yui-managed-context/v1",
@@ -136,28 +140,45 @@ function roleContext(args, store, options) {
                 : ["perform-global-role-request"]
         },
         // Reading pending input is neither delivery nor implementation.
-        pendingMessages: pendingQueue,
-        messages: store.listGlobalRoleMessages(name),
+        pending,
+        recent,
+        reads: {
+            messages: `role message list ${name}`,
+            pending: `role message list ${name} --pending`,
+            detail: `role message show ${name} <message-id>`
+        },
         nativeTurn: sessions?.providerBinding?.run ?? null,
         retry: providerRetryProjection(sessions?.providerBinding),
-        interrupts: sessions?.interrupts ?? {},
+        // Historical interrupt receipts are available through Session inspection;
+        // only this Turn's exact identity is required at entry.
         sessionManifestPath: environment.YUI_SESSION_MANIFEST,
         cliCommand: "yui"
     });
-    if (options.jsonOutput === true)
-        return `${JSON.stringify(context)}\n`;
-    return [
-        `Role Context: ${role.name}`,
-        `Scope: global (${context.identity.roleKind})`,
-        `Agent: ${binding.agentId}/${binding.adapterId}`,
-        `Workspace: ${role.workspace}`,
-        `Effective revision: ${role.launchRevision}`,
-        `Skills: ${context.profile.skillIds.join(", ") || "none"}`,
-        `Authority: ${context.authority.view}; Task implementation: no`,
-        `Pending messages: ${pendingQueue.length === 0 ? "none"
-            : pendingQueue.map((message) => message.id).join(", ")}`,
-        ""
-    ].join("\n");
+    const data = boundedDocument(context, `global:${name}/context`, parsed.cursor);
+    return { kind: "output", data, output: [
+            `Role Context: ${role.name}`,
+            `Scope: global (${context.identity.roleKind})`,
+            `Agent: ${binding.agentId}/${binding.adapterId}`,
+            `Workspace: ${role.workspace}`,
+            `Effective revision: ${role.launchRevision}`,
+            `Skills: ${context.profile.skillIds.join(", ") || "none"}`,
+            `Authority: ${context.authority.view}; Task implementation: no`,
+            `Pending messages: ${pending.total}; recent messages: ${recent.total}`,
+            JSON.stringify(data),
+            ""
+        ].join("\n") };
+}
+function globalMessageSummary(message) {
+    return {
+        id: message.id, createdAt: message.createdAt, kind: message.kind,
+        digest: readDigest(message), summary: message.body.slice(0, 240),
+        delivery: message.delivery === undefined ? undefined : { deliveredAt: message.delivery.deliveredAt },
+        notDelivered: message.notDelivered === undefined ? undefined : { summary: message.notDelivered.reason.slice(0, 240) },
+        control: message.control === undefined ? undefined : { outcome: message.control.outcome, observedAt: message.control.observedAt },
+        inputAction: message.inputControl?.action,
+        deliveryTarget: message.deliveryTarget,
+        interruptThen: message.interruptThen === undefined ? undefined : true
+    };
 }
 function addRole(args, store, options) {
     const [rawName, ...tail] = args;
@@ -542,6 +563,37 @@ export function sendGlobalRoleMessageCommand(store, roleName, body, author, inpu
  */
 function globalRoleMessage(args, store, options) {
     const [action, rawName, ...tail] = args;
+    if (action === "list" || action === "show") {
+        const name = roleName(rawName);
+        const env = options.env ?? process.env;
+        if (env.YUI_SESSION_SCOPE !== undefined
+            && (env.YUI_SESSION_SCOPE !== "global" || env.YUI_ROLE !== name)) {
+            throw usageError("Global Message read is outside the exact Session scope.");
+        }
+        requireRole(name, store);
+        const pending = tail.includes("--pending");
+        const parsed = readOptions(tail.filter(arg => arg !== "--pending"), action === "list"
+            ? ["--cursor", "--limit"] : ["--cursor"]);
+        const messages = store.listGlobalRoleMessages(name);
+        let data;
+        if (action === "show") {
+            if (parsed.positionals.length !== 1 || pending)
+                throw usageError("Role message show <role> <message-id> [--cursor <cursor>].");
+            const message = messages.find(m => m.id === parsed.positionals[0]);
+            if (message === undefined)
+                throw usageError("Global Message is unavailable in this scope.");
+            data = boundedDocument(message, `global:${name}/message/${message.id}`, parsed.cursor);
+        }
+        else {
+            if (parsed.positionals.length !== 0)
+                throw usageError("Role message list <role> [--pending] [--limit <n>] [--cursor <cursor>].");
+            const selected = pending ? messages.filter(message => message.delivery === undefined
+                && message.notDelivered === undefined
+                && (message.interruptThen !== undefined || message.inputControl?.action === "queue")) : [...messages].reverse();
+            data = recordPage(selected.map(globalMessageSummary), `global:${name}/messages/${pending ? "pending" : "all"}`, parsed);
+        }
+        return { kind: "output", output: `${JSON.stringify(data, null, 2)}\n`, data };
+    }
     if (action !== "queue" && action !== "steer") {
         throw usageError("Role message usage: yui role message queue|steer <role> (<body>|--body-file <path|->) --request-id <id> [--expected-target <turn>].");
     }
@@ -581,14 +633,14 @@ function messageGlobalInput(name, input, store, options) {
     });
     if (action === "queue") {
         const state = persisted.idempotentReplay ? "idempotent-replay" : "queued";
-        return inputOutput(`Queued Global message ${persisted.message.id} to ${name} (${state}).\n`, { roleName: name, message: persisted.message, delivery: { state } });
+        return inputOutput(`Queued Global message ${persisted.message.id} to ${name} (${state}).\n`, { roleName: name, message: messageReceipt(persisted.message), delivery: { state } });
     }
     if (persisted.idempotentReplay) {
-        return inputOutput(`Steer Global message ${persisted.message.id} already recorded (idempotent-replay).\n`, { roleName: name, message: persisted.message, steer: { state: "idempotent-replay" } });
+        return inputOutput(`Steer Global message ${persisted.message.id} already recorded (idempotent-replay).\n`, { roleName: name, message: messageReceipt(persisted.message), steer: { state: "idempotent-replay" } });
     }
     const resolution = resolveGlobalInputControl(store, name, "steer", expectedTarget);
     if (resolution.outcome !== "ready") {
-        return inputOutput(`Steer Global message ${persisted.message.id} saved but not delivered (${resolution.code}: ${resolution.detail}).\n`, { roleName: name, message: persisted.message,
+        return inputOutput(`Steer Global message ${persisted.message.id} saved but not delivered (${resolution.code}: ${resolution.detail}).\n`, { roleName: name, message: messageReceipt(persisted.message),
             steer: { state: "not-steered", code: resolution.code, detail: resolution.detail } });
     }
     store.updateGlobalRoleMessage({ ...persisted.message, control: {
@@ -752,17 +804,6 @@ function registerGlobalInterruptThen(store, roleName, thenMessageId, targetAttem
     }));
     return "claimed";
 }
-/** Emit a plain string or, under --json, a JSON envelope, matching the Global
- * Role command surface's existing string/JSON split. */
-function jsonOrText(options, text, data) {
-    const record = data;
-    const failure = record.steer?.code === undefined ? record.interrupt : record.steer;
-    if (failure?.code !== undefined)
-        options.onInputFailure?.({
-            code: failure.code, detail: failure.detail ?? failure.code, data
-        });
-    return options.jsonOutput === true ? JSON.stringify(data) : text;
-}
 function parseOptions(args, specs) {
     const values = new Map();
     const seen = new Set();

package/dist/commands/grantCommands.js

@@ -4,6 +4,9 @@ import { createCapabilityGrant, revokeGrant } from "../grant/capabilityGrant.js"
 import { defaultTableWidth, renderTable } from "../output/table.js";
 import { formatTimestamp } from "../output/timePresentation.js";
 import { isCurrentGlobalOperator } from "./taskInputCommands.js";
+import { assertLeaderGrantBounds, taskAuthorizationSource } from "../grant/taskAuthorization.js";
+import { currentManagedRuntime } from "../runtime/managedCaller.js";
+import { isDeepStrictEqual } from "node:util";
 const CEILINGS = new Set(["none", "reversible", "irreversible"]);
 export function runGrantCommand(args, store, options) {
     const [command, ...rest] = args;
@@ -20,7 +23,7 @@ export function runGrantCommand(args, store, options) {
 }
 function issueGrant(args, store, options) {
     const usage = "Task grant issue usage: yui task grant issue <task> --action <name> (repeatable) [--scope-project <id>...] [--scope-repo <owner/name>...] [--scope-package <name>...] [--scope-home <path>] [--param <name=v1,v2>...] [--expires-at <iso-8601>] [--max-uses <int>] [--irreversibility-ceiling <none|reversible|irreversible>].";
-    const parsed = parseMultiValueTail(args, new Set(["--scope-home", "--expires-at", "--max-uses", "--irreversibility-ceiling"]), new Set(["--action", "--scope-project", "--scope-repo", "--scope-package", "--param"]), usage);
+    const parsed = parseMultiValueTail(args, new Set(["--scope-home", "--expires-at", "--max-uses", "--irreversibility-ceiling", "--source-message", "--purpose", "--request-id"]), new Set(["--action", "--scope-project", "--scope-repo", "--scope-package", "--param"]), usage);
     exactPositionals(parsed.positionals, 1, usage);
     const taskId = parsed.positionals[0];
     requireTask(store, taskId);
@@ -32,29 +35,63 @@ function issueGrant(args, store, options) {
     const expiresAt = optionalOption(parsed.options, "--expires-at");
     const maxUses = parseMaxUses(parsed, usage);
     const ceiling = parseCeiling(parsed, usage);
-    // Grant issuance mints irreversible authority. The granter is bound to the
-    // authenticated global Operator Session, not to a caller-supplied label.
+    // Bind issuance to the authenticated Session, never a caller-supplied label.
     const env = options.environment ?? {};
-    const granter = authorizeGrantOrigin(store, env, usage);
+    const operator = isCurrentGlobalOperator(store, env);
+    const sourceMessage = optionalOption(parsed.options, "--source-message");
+    const purpose = optionalOption(parsed.options, "--purpose");
+    const requestId = optionalOption(parsed.options, "--request-id");
+    if (!operator && !requestId)
+        throw usageError("Leader grant issue requires a stable --request-id.");
+    const authorizationSource = operator ? undefined
+        : taskAuthorizationSource(store, taskId, env, sourceMessage, purpose);
+    const granter = operator ? authorizeGrantOrigin(store, env, usage)
+        : `leader:${taskId}:${authorizationSource.nativeSessionId}`;
     const now = clock(options);
     // The grant record and its audit event commit in one transaction: a failed
     // event save cannot leave a persisted grant without its audit trail.
     const grant = store.transaction((tx) => {
-        const issued = createCapabilityGrant(tx.nextCapabilityGrantId(taskId), taskId, {
+        if (operator)
+            authorizeGrantOrigin(tx, env, usage);
+        else if (!isDeepStrictEqual(authorizationSource, taskAuthorizationSource(tx, taskId, env, sourceMessage, purpose)))
+            throw usageError("Authorization source changed before grant issuance; inspect current context.");
+        const previous = requestId === undefined ? undefined : tx.listEvents(taskId).find(event => event.type === "capability-grant.issued" && event.payload.requestId === requestId
+            && event.payload.issuer === (operator ? "operator" : "leader"));
+        const existing = previous === undefined ? null : tx.getCapabilityGrant(taskId, previous.payload.grantId);
+        const issued = createCapabilityGrant(existing?.id ?? tx.nextCapabilityGrantId(taskId), taskId, {
             granter,
-            ...(scope === undefined ? {} : { scope }),
+            ...(authorizationSource === undefined ? {} : { authorizationSource }),
+            ...(operator ? (scope === undefined ? {} : { scope }) : { scope: { ...scope, taskId } }),
             actions,
             ...(parameterBounds === undefined ? {} : { parameterBounds }),
             ...(expiresAt === undefined ? {} : { expiresAt }),
             ...(maxUses === undefined ? {} : { maxUses }),
             ...(ceiling === undefined ? {} : { irreversibilityCeiling: ceiling })
         }, now);
+        if (previous !== undefined) {
+            const identity = (value) => ({
+                scope: value.scope, actions: value.actions, parameterBounds: value.parameterBounds,
+                expiresAt: value.expiresAt, maxUses: value.maxUses, irreversibilityCeiling: value.irreversibilityCeiling,
+                source: value.authorizationSource === undefined ? undefined : {
+                    messageId: value.authorizationSource.messageId, digest: value.authorizationSource.digest,
+                    purpose: value.authorizationSource.purpose
+                }
+            });
+            if (!existing || !isDeepStrictEqual(identity(existing), identity(issued))) {
+                throw usageError("Grant request id already names different authorization or bounds; inspect the original grant.");
+            }
+            return existing;
+        }
+        if (!operator)
+            assertLeaderGrantBounds(tx, issued, now);
         tx.saveCapabilityGrant(taskId, issued);
         recordTaskEvent(tx, taskId, "capability-grant.issued", {
             grantId: issued.id,
             granter: issued.granter,
             actions: issued.actions.join(","),
-            scope: scopeSummary(issued.scope)
+            scope: scopeSummary(issued.scope),
+            ...(requestId === undefined ? {} : { requestId, issuer: operator ? "operator" : "leader" }),
+            ...(authorizationSource === undefined ? {} : { authorizationSource: JSON.stringify(authorizationSource) })
         }, now);
         return issued;
     });
@@ -141,7 +178,10 @@ function revokeGrantCommand(args, store, options) {
     // Revoke is the same irreversible-authority operation as issue: it requires
     // the authenticated Operator Session, and the revoker is bound to it.
     const env = options.environment ?? {};
-    const by = authorizeGrantOrigin(store, env, usage);
+    const caller = currentManagedRuntime(store, env, taskId, "leader");
+    const leader = caller?.executionAuthority === "delivery"
+        && existing.authorizationSource !== undefined && existing.granter.startsWith(`leader:${taskId}:`);
+    const by = leader ? `leader:${taskId}:${caller.nativeSessionId}` : authorizeGrantOrigin(store, env, usage);
     const wasRevoked = existing.revokedAt !== undefined;
     const now = clock(options);
     const grant = revokeGrant(existing, by, now);