@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/tenant/auth.js

@@ -0,0 +1,169 @@
+import { SCOPES_HEADER, SUBJECT_HEADER, } from "@nylorun/core/compatibility";
+import { parseSubjectHeaders, } from "@nylorun/core/contracts";
+import { hashToken } from "../core/executors.js";
+import { fail, failOpaque } from "./http.js";
+const SUBJECT_INVALID = { code: "subject_invalid" };
+/** One header's value, or `undefined`; a header sent twice is refused. */
+function singleHeader(request, name) {
+    const values = request.headersDistinct?.[name.toLowerCase()];
+    if (!values) {
+        const raw = request.headers[name.toLowerCase()];
+        return Array.isArray(raw) ? fail(400, `${name} must be sent once`, SUBJECT_INVALID) : raw;
+    }
+    if (values.length > 1)
+        return fail(400, `${name} must be sent once`, SUBJECT_INVALID);
+    return values[0];
+}
+export async function authenticate(ctx, request) {
+    const header = request.headers.authorization;
+    const token = header?.startsWith("Bearer ") ? header.slice(7) : "";
+    if (!token || !header?.startsWith("Bearer ")) {
+        ctx.config.logger.warn("credential rejected", {
+            reason: "missing_bearer",
+        });
+        return failOpaque();
+    }
+    const tokenHash = hashToken(token);
+    const principal = await ctx.store.tx((t) => t.principalByTokenHash(tokenHash));
+    const executor = principal ? undefined : ctx.registry.find(tokenHash);
+    if (!principal && !executor) {
+        ctx.config.logger.warn("credential rejected", {
+            reason: "unknown_token",
+        });
+        return failOpaque();
+    }
+    // Read only after authentication, so an unknown caller sees the opaque 404 either way.
+    const subject = singleHeader(request, SUBJECT_HEADER);
+    const scopes = singleHeader(request, SCOPES_HEADER);
+    if (executor) {
+        if (subject !== undefined || scopes !== undefined)
+            fail(403, "An executor credential cannot act for a subject");
+        return { kind: "executor", executor };
+    }
+    if (subject === undefined) {
+        if (scopes !== undefined)
+            fail(400, `${SCOPES_HEADER} requires ${SUBJECT_HEADER}`, SUBJECT_INVALID);
+        return { kind: "application", principalId: principal.id };
+    }
+    const parsed = parseSubjectHeaders(subject, scopes);
+    if (!parsed.ok)
+        return fail(400, parsed.message, SUBJECT_INVALID);
+    return {
+        kind: "subject",
+        principalId: principal.id,
+        subject: parsed.subject,
+        scopes: parsed.scopes,
+    };
+}
+const SESSIONS = ["sessions:own"];
+const VAULTS = ["vaults:own"];
+const SETTINGS = ["tenant:settings"];
+/**
+ * The scopes a subject needs for `method path` (`path` starts with `v1`). `undefined` for a
+ * route that does not exist. Operator and executor routes are `never`: reset, config seed,
+ * executors, actions and the sandbox tool routes.
+ */
+export function routeAccess(method, path) {
+    const [v1, resource, id, sub] = path;
+    const n = path.length;
+    if (v1 !== "v1" || !resource)
+        return undefined;
+    switch (resource) {
+        case "executors":
+        case "actions":
+            return "never";
+        case "agents":
+            if (n === 2 && method === "GET")
+                return ["agents:read", "agents:write"];
+            if (n === 3 && method === "PUT")
+                return ["agents:write"];
+            return undefined;
+        case "sessions":
+            if (n === 2 && method === "GET")
+                return SESSIONS;
+            if (n === 3 && (method === "GET" || method === "PUT"))
+                return SESSIONS;
+            if (n === 4 && method === "GET" && (sub === "items" || sub === "events"))
+                return SESSIONS;
+            if (n === 4 && method === "POST" && sub === "commands")
+                return SESSIONS;
+            if (n === 5 && method === "POST" && sub === "sandbox")
+                return "never";
+            return undefined;
+        case "vaults":
+            if (n === 2)
+                return method === "GET" || method === "POST" ? VAULTS : undefined;
+            if (n === 3)
+                return method === "GET" || method === "DELETE" ? VAULTS : undefined;
+            if (sub !== "credentials")
+                return undefined;
+            if (n === 4)
+                return method === "GET" || method === "POST" ? VAULTS : undefined;
+            if (n === 5)
+                return method === "GET" || method === "POST" || method === "DELETE"
+                    ? VAULTS
+                    : undefined;
+            return undefined;
+        case "tenant":
+            if (n === 2 && method === "GET")
+                return SETTINGS;
+            if (n === 3 && id === "reset" && method === "POST")
+                return "never";
+            if (n === 4 && id === "config" && sub === "seed" && method === "PUT")
+                return "never";
+            if (n === 3 && method === "GET" && (id === "models" || id === "providers"))
+                return ["tenant:settings", "agents:write"];
+            if (n === 3 && method === "GET" && id === "sandbox")
+                return SETTINGS;
+            if (n === 3 && id === "model" && (method === "GET" || method === "PUT"))
+                return SETTINGS;
+            if (n === 4 && id === "model" && sub === "selection" && method === "PUT")
+                return SETTINGS;
+            return undefined;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Limits a subject to the routes its scopes allow. Decided from the route alone, before any
+ * lookup, so a refusal reveals nothing about which resources exist. A route the table does not
+ * know is a 404 for a subject: new routes stay closed until they are added here. Application
+ * and executor scopes pass through to the checks each route makes today.
+ */
+export function authorize(scope, method, path) {
+    if (scope.kind !== "subject")
+        return;
+    const access = routeAccess(method, path);
+    if (access === undefined)
+        fail(404, "Route not found");
+    if (access === "never")
+        fail(403, "This route is not available when acting for a subject", {
+            code: "scope_required",
+            details: { scopes: [] },
+        });
+    if (!access.some((name) => scope.scopes.has(name)))
+        fail(403, `Scope ${access.join(" or ")} required`, {
+            code: "scope_required",
+            details: { scopes: access },
+        });
+}
+/** The subject whose sessions and vaults the request is limited to, if it acts for one. */
+export function ownerOf(scope) {
+    return scope.kind === "subject" ? scope.subject : undefined;
+}
+/** The application principal behind the request, acting for a subject or not. */
+export function requirePrincipal(scope) {
+    if (scope.kind !== "executor")
+        return scope.principalId;
+    return fail(403, "Application credential required");
+}
+/** The executor scope must belong to the Action's agent. */
+export function scoped(scope, action) {
+    if (scope.kind !== "executor" || scope.executor.agentId !== action.agentId)
+        fail(403, "Executor scope does not authorize this action");
+}
+export function requireApplication(scope) {
+    if (scope.kind === "application")
+        return scope.principalId;
+    return fail(403, "Application credential required");
+}

package/dist/tenant/commands.d.ts

@@ -0,0 +1,3 @@
+import type { SessionCommand } from "@nylorun/core/contracts";
+import { type AuthScope, type TenantContext } from "./context.js";
+export declare function command(ctx: TenantContext, id: string, input: SessionCommand, scope: AuthScope): Promise<unknown>;

package/dist/tenant/commands.js

@@ -0,0 +1,393 @@
+/**
+ * The session command service: `message`, `approve`/`respond`, `action_result` and `cancel`,
+ * with per-session idempotency keys. A command locks its session and commits its state
+ * change, events and wakes in one transaction (the store publishes the events and runs the
+ * `afterCommit` wakes), then aborts a cancelled advance and cascades workflow cancels to the
+ * linked agent sessions, one transaction each.
+ *
+ * Wakes (`ctx.wake`, architecture §12.3) carry the command type as the reason and a dedupe
+ * key naming the cause: `<type>:<turnId>:<segment>` for `message`, `approve` and `respond`
+ * (every accepted one writes a new checkpoint segment), and
+ * `action_result:<turnId>:<actionId>:<generation>` for executor results.
+ *
+ * Cancel commits `cancelled` first; the engine host sees it before its next effect and before
+ * settlement on any Worker. It then aborts an advance running on this process
+ * (`ctx.abortLocal`); reaching an advance on another process is the control stream's job.
+ */
+import { randomUUID } from "node:crypto";
+import { createDurableCheckpoint, createFlowCheckpoint, } from "@nylorun/harness/run";
+import { schemaFromJSON, } from "@nylorun/core/define";
+import { commandKey, fenceWorkflowActions, foreignInteractionConflict, isWorkflowManifest, planCancelCascade, wakeForQueuedEffects, wakeLinkedWorkflow, } from "../core/flow-host.js";
+import { resolveMessageManifest } from "../core/turn-manifest.js";
+import { canonical } from "../store/canonical.js";
+import { lockedSession, } from "./context.js";
+import { fail } from "./http.js";
+import { ownerOf, scoped } from "./auth.js";
+import { actionTarget, rebaseSessionState, turnManifestOf, variantStore, } from "./session.js";
+import { signalSessionCancel } from "./streams.js";
+import { toolIds } from "./transcript.js";
+/** A tool result whose output does not match the Action's stored output schema fails the tool. */
+function acceptedToolResult(action, command) {
+    if (action.kind !== "tool" || !action.outputSchema)
+        return command;
+    const value = command.outcome.value;
+    // Only a result carries output: failures, denials, interactions and deferrals pass as sent.
+    if (!isResultToolValue(value))
+        return command;
+    // Executors wrap successful tool output as `{ kind: "completed", output }`.
+    // Validate the tool payload, not the outcome envelope.
+    const candidate = completedToolOutput(value);
+    let matches = false;
+    try {
+        matches = schemaFromJSON(action.outputSchema).validate(candidate).ok;
+    }
+    catch {
+        matches = false;
+    }
+    if (matches)
+        return command;
+    return {
+        ...command,
+        outcome: {
+            ...command.outcome,
+            value: {
+                kind: "failed",
+                code: "tool.invalid-output",
+                message: "Tool result does not match the output schema stored on the action",
+            },
+        },
+    };
+}
+function completedToolOutput(value) {
+    if (value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value.kind === "completed" &&
+        "output" in value) {
+        return value.output;
+    }
+    return value;
+}
+const NON_RESULT_KINDS = new Set([
+    "failed",
+    "denied",
+    "interaction-required",
+    "deferred",
+]);
+function isResultToolValue(value) {
+    return !(!!value &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        NON_RESULT_KINDS.has(value.kind));
+}
+/** A command's identity for idempotency: everything but the request id. */
+const semantic = (value) => {
+    const { requestId: _, ...body } = value;
+    return canonical(body);
+};
+export async function command(ctx, id, input, scope) {
+    const { store } = ctx;
+    const cascadeCancelIds = [];
+    const response = await store.tx(async (t) => {
+        const s = await lockedSession(t, id, ownerOf(scope));
+        let command = input;
+        if (command.type === "action_result") {
+            const a = (await t.get("actions", command.actionId)) ??
+                fail(404, "Action not found");
+            if (a.sessionId !== id)
+                fail(403, "Action belongs to another session");
+            scoped(scope, a);
+            command = acceptedToolResult(a, command);
+        }
+        else if (scope.kind === "executor")
+            fail(403, "Application credential required");
+        const key = commandKey(id, command.idempotencyKey);
+        const existing = await t.get("commands", key);
+        if (existing) {
+            if (semantic(existing.command) !== semantic(command))
+                fail(409, "Idempotency key already binds another command");
+            return existing.response;
+        }
+        let event;
+        // The turn a `cancel` ended, if one was active.
+        let cancelledTurnId = null;
+        if (command.type === "action_result") {
+            const action = (await t.get("actions", command.actionId));
+            const prior = await t.get("effects", command.actionId);
+            if (action.status === "completed") {
+                if (action.claimId !== command.claimId ||
+                    action.generation !== command.generation ||
+                    canonical(prior.outcome) !== canonical(command.outcome))
+                    fail(409, "Conflicting action result");
+                await t.put("commands", key, { command, response: prior.receipt });
+                return prior.receipt;
+            }
+            if (s.status === "cancelled" ||
+                s.activeTurnId !== action.turnId ||
+                action.status !== "claimed" ||
+                action.claimId !== command.claimId ||
+                action.generation !== command.generation ||
+                Date.parse(action.leaseExpiresAt) <= Date.now())
+                fail(409, "Stale, expired, or cancelled claim");
+            action.status = "completed";
+            await t.put("actions", action.actionId, action);
+            prior.status = "completed";
+            prior.outcome = command.outcome;
+            s.status = "runnable";
+            const resultWake = {
+                reason: "action_result",
+                dedupeKey: `action_result:${action.turnId}:${action.actionId}:${action.generation}`,
+            };
+            t.afterCommit(() => ctx.wake(id, resultWake));
+            event = await t.event(id, s.activeTurnId, "action.completed", {
+                actionId: action.actionId,
+                ...actionTarget(action),
+                kind: action.kind,
+                ...(action.kind === "tool" ? toolIds(action.context) : {}),
+                result: command.outcome.value,
+            });
+            if (action.kind === "verify") {
+                const verdict = command.outcome.value;
+                if (verdict?.kind !== "failed") {
+                    await t.event(id, s.activeTurnId, "loop.verified", {
+                        path: String(action.context?.loopPath ?? action.path ?? ""),
+                        n: Number(action.context?.n ?? 1),
+                        pass: Boolean(verdict?.pass),
+                        ...(verdict?.feedback !== undefined
+                            ? { feedback: verdict.feedback }
+                            : {}),
+                        ...(verdict?.data !== undefined ? { data: verdict.data } : {}),
+                    });
+                }
+            }
+            else if (action.kind === "fn" && action.context?.role === "decide") {
+                const decision = command.outcome.value;
+                await t.event(id, s.activeTurnId, "loop.decided", {
+                    path: String(action.context?.loopPath ?? action.path ?? ""),
+                    n: Number(action.context?.n ?? 1),
+                    next: "output" in decision && !("input" in decision)
+                        ? "output"
+                        : "input",
+                    patched: Boolean(decision.agent),
+                });
+            }
+            const receipt = {
+                status: "accepted",
+                turnId: s.activeTurnId,
+                cursor: event.cursor,
+                requestId: command.requestId,
+            };
+            prior.receipt = receipt;
+            await t.put("effects", action.actionId, prior);
+            if (isWorkflowManifest(s.manifest) && s.activeTurnId) {
+                await wakeForQueuedEffects({
+                    t,
+                    workflowSessionId: id,
+                    turnId: s.activeTurnId,
+                    limits: ctx.flowLimits,
+                    schedule: ctx.wake,
+                });
+            }
+        }
+        else if (command.type === "cancel") {
+            cancelledTurnId = s.activeTurnId;
+            const workflowCancel = isWorkflowManifest(s.manifest);
+            const cascade = workflowCancel
+                ? await planCancelCascade({
+                    t,
+                    workflowSessionId: id,
+                    turnId: cancelledTurnId,
+                })
+                : null;
+            s.status = "cancelled";
+            if (workflowCancel) {
+                await fenceWorkflowActions({
+                    t,
+                    workflowSessionId: id,
+                    turnId: cancelledTurnId,
+                });
+            }
+            else if (cancelledTurnId !== null) {
+                for (const a of await t.actionsForSession(id, {
+                    turnId: cancelledTurnId,
+                    statuses: ["pending", "claimed"],
+                })) {
+                    // Claimed work may already have an external effect. Preserve it for reconciliation.
+                    a.status = a.status === "claimed" ? "uncertain" : "cancelled";
+                    await t.put("actions", a.actionId, a);
+                    const effect = await t.get("effects", a.actionId);
+                    if (effect) {
+                        effect.status = a.status;
+                        await t.put("effects", a.actionId, effect);
+                    }
+                }
+            }
+            if (cancelledTurnId !== null)
+                for (const effect of await t.effectsForTurn(id, cancelledTurnId, ["invoking"])) {
+                    effect.status = "uncertain";
+                    effect.error =
+                        "Turn cancelled before model outcome was durably recorded";
+                    await t.put("effects", effect.request.effectId, effect);
+                }
+            event = await t.event(id, cancelledTurnId, "turn.cancelled", {
+                reason: command.reason,
+            });
+            // The process running the advance aborts it on `session.cancel` (tenant/control).
+            t.afterCommit(() => signalSessionCancel(ctx, id));
+            s.activeTurnId = null;
+            if (cancelledTurnId !== null)
+                s.lastTurnId = cancelledTurnId;
+            // The next turn starts from the state preceding the cancelled turn, never its paused plan.
+            if (cancelledTurnId !== null)
+                s.state = s.turnStartState;
+            s.checkpoint = undefined;
+            s.waits = undefined;
+            s.error = undefined;
+            // Cascade: cancel linked agent sessions deepest-first (after fencing this session), each
+            // in its own transaction after this one commits (child sessions are never locked here).
+            if (cascade) {
+                for (const agentId of cascade.agentSessionIds) {
+                    const agent = await t.get("sessions", agentId);
+                    if (!agent ||
+                        !agent.activeTurnId ||
+                        ["idle", "completed", "failed", "cancelled"].includes(agent.status))
+                        continue;
+                    cascadeCancelIds.push(agentId);
+                }
+            }
+        }
+        else {
+            if (command.type === "message") {
+                if (!["idle", "completed", "failed", "cancelled"].includes(s.status))
+                    fail(409, "Session has active or unresolved work");
+                s.turnStartState = s.state;
+                s.activeTurnId = randomUUID();
+                if (isWorkflowManifest(s.manifest)) {
+                    const input = "content" in command ? command.content : command.data;
+                    s.checkpoint = createFlowCheckpoint({
+                        manifest: s.manifest,
+                        sessionId: id,
+                        turnId: s.activeTurnId,
+                        input,
+                    });
+                }
+                else {
+                    // Optional message.manifest: validate as variant, pin by hash, apply this turn only.
+                    const resolved = resolveMessageManifest({
+                        pinned: s.manifest,
+                        pinnedHash: s.manifestHash,
+                        messageManifest: command.manifest,
+                        store: variantStore(s),
+                    });
+                    if (!resolved.ok) {
+                        fail(400, resolved.message);
+                    }
+                    else {
+                        rebaseSessionState(s, resolved.hash);
+                        s.checkpoint = createDurableCheckpoint({
+                            manifest: resolved.manifest,
+                            sessionId: id,
+                            turnId: s.activeTurnId,
+                            input: "content" in command
+                                ? command.content
+                                : typeof command.data === "string"
+                                    ? command.data
+                                    : JSON.stringify(command.data),
+                            state: s.state,
+                            info: s.info,
+                        });
+                    }
+                }
+            }
+            else {
+                if (s.status !== "paused" || !s.state || !s.activeTurnId)
+                    fail(409, "Session is not awaiting a response");
+                const pending = s.state.plan?.calls ?? [];
+                if (!pending.some((c) => c.status === "interaction" &&
+                    c.interaction?.id === command.interactionId &&
+                    (command.type === "approve") ===
+                        (c.interaction?.kind === "approval")))
+                    fail(409, "Unknown interaction");
+                const input = command.type === "approve"
+                    ? {
+                        kind: "approve",
+                        interactionId: command.interactionId,
+                        approved: command.approved,
+                    }
+                    : {
+                        kind: "respond",
+                        interactionId: command.interactionId,
+                        value: command.value,
+                    };
+                if (isWorkflowManifest(s.manifest)) {
+                    // Approvals owned by linked agent sessions must be answered there (WF-R52).
+                    const conflict = await foreignInteractionConflict({
+                        t,
+                        workflowSessionId: id,
+                        interactionId: command.interactionId,
+                    });
+                    if (conflict)
+                        fail(409, conflict.message);
+                    // Workflow-owned interactions (tool-node / verify) resume on this session once
+                    // the flow engine supports pause segments; tracer root Loop has none yet.
+                    fail(409, "Workflow sessions do not accept approve/respond on the root without a pending interaction");
+                }
+                s.checkpoint = createDurableCheckpoint({
+                    manifest: turnManifestOf(s),
+                    sessionId: id,
+                    turnId: s.activeTurnId,
+                    input: input,
+                    state: s.state,
+                    info: s.info,
+                    segment: (s.checkpoint?.segment ?? 0) + 1,
+                });
+            }
+            await t.put("checkpoints", JSON.stringify([id, s.activeTurnId, s.checkpoint.segment]), { checkpoint: s.checkpoint, status: "runnable" });
+            s.status = "runnable";
+            s.waits = undefined;
+            const commandWake = {
+                reason: command.type,
+                dedupeKey: `${command.type}:${s.activeTurnId}:${s.checkpoint.segment}`,
+            };
+            t.afterCommit(() => ctx.wake(id, commandWake));
+            event = await t.event(id, s.activeTurnId, `command.${command.type}`, command);
+        }
+        await t.put("sessions", id, s);
+        // Direct cancel of a linked agent fails that node with agent.cancelled (WF-R54). The agent
+        // session is locked above, before wakeLinkedWorkflow locks its workflow.
+        if (command.type === "cancel")
+            await wakeLinkedWorkflow({
+                t,
+                agentSessionId: id,
+                turnId: cancelledTurnId,
+                cancelled: true,
+                error: "Agent turn was cancelled",
+                schedule: ctx.wake,
+            });
+        const response = {
+            status: "accepted",
+            turnId: s.activeTurnId,
+            cursor: event.cursor,
+            requestId: command.requestId,
+        };
+        await t.put("commands", key, { command, response });
+        return response;
+    });
+    if (input.type === "cancel")
+        ctx.abortLocal(id);
+    // Cascade cancel linked agents deepest-first under existing fencing (WF-R53).
+    for (const agentId of cascadeCancelIds) {
+        try {
+            await command(ctx, agentId, {
+                type: "cancel",
+                requestId: `flow-cascade-${id}-${agentId}`,
+                idempotencyKey: `flow-cascade-cancel:${id}:${agentId}`,
+                reason: "workflow cancelled",
+            }, scope);
+        }
+        catch {
+            /* agent may already be terminal */
+        }
+    }
+    return response;
+}