@unoverse-platform/studio 0.1.115 → 0.1.116

package/vendor/base/src/agent-mcp/invoke.ts

@@ -11,6 +11,7 @@
  * Node-MCP rows still route in-process via the caller's `api.callService`: they have a
  * node to run. Renamed from `invokeComponentAppNative` when workflow tasks joined it.
  */
+import { taskToolName } from "../definitions/registry/taskUri.js";
 import type { AppInvocationContext, DiscoveredMCP } from "./types.js";
 
 /**
@@ -73,35 +74,166 @@ export async function connectPlatformMcp(
   };
 }
 
+/** The tasks extension's id (`io.modelcontextprotocol/tasks`), as the official library names it. */
+const TASKS_EXTENSION = "io.modelcontextprotocol/tasks";
+const MODERN = "2026-07-28";
+
+type CallResult = {
+  isError?: boolean;
+  content?: Array<{ type: string; text?: string }>;
+  structuredContent?: Record<string, any>;
+};
+
+/**
+ * ONE CALL, FOLLOWED AS AN MCP TASK WHEN IT IS ONE (docs/mcp/MCP_TASKS.md steps 6 and 7). Every
+ * Task is an MCP task: a workflow, a form, an app that asks. The harness calls as a 2026-07-28
+ * client that declared the tasks extension, so a Task answers at once with its task and the
+ * official client (`@modelcontextprotocol/ext-tasks/client`) follows it to its result; a call
+ * with nothing to wait for answers at once, through the same client. Several calls in one turn
+ * each follow their own task, side by side.
+ *
+ * The one piece of host code the library asks for is `rawDispatch`: it sends one JSON-RPC request
+ * on the 2026 framing and hands back the response. The host owns request ids, so it adds them.
+ */
+async function callFollowingTasks(toolId: string, args: Record<string, unknown>, ctx: AppInvocationContext): Promise<CallResult> {
+  const { Client, StreamableHTTPClientTransport } = await import("@modelcontextprotocol/client");
+  const { createTaskSessionFromClient, resultFromTaskOutcome } = await import("@modelcontextprotocol/ext-tasks/client");
+  const base = (ctx.baseUrl || process.env.UNOVERSE_SERVICE_URL || "http://localhost:4106").replace(/\/$/, "");
+  const auth: Record<string, string> = ctx.accessToken ? { Authorization: `Bearer ${ctx.accessToken}` } : {};
+  const clientInfo = { name: "unoverse-agent-mcp", version: "1.0.0" };
+  const clientCapabilities = { extensions: { [TASKS_EXTENSION]: {} } };
+  const client = new Client(clientInfo, { versionNegotiation: { mode: { pin: MODERN } }, capabilities: clientCapabilities } as never);
+  await client.connect(
+    new StreamableHTTPClientTransport(new URL(`${base}/mcp`), {
+      fetch: (url: string | URL, init?: RequestInit) => fetch(url, { ...init, headers: { ...Object.fromEntries(new Headers(init?.headers)), ...auth } }),
+    }),
+  );
+  let next = 0;
+  const rawDispatch = async (request: { method: string; params?: Record<string, unknown> }) => {
+    const id = `task-${++next}`;
+    const name = request.method === "tools/call" ? request.params?.name : request.method.startsWith("tasks/") ? request.params?.taskId : undefined;
+    const res = await fetch(`${base}/mcp`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        "mcp-protocol-version": MODERN,
+        "mcp-method": request.method,
+        ...(typeof name === "string" ? { "mcp-name": name } : {}),
+        ...auth,
+      },
+      body: JSON.stringify({ jsonrpc: "2.0", id, ...request }),
+    });
+    const text = await res.text();
+    // A JSON answer, or a stream whose last message for this id is the answer.
+    if (!text.includes("data: ")) return JSON.parse(text);
+    const answers = text.split("\n").filter((l) => l.startsWith("data: ")).map((l) => JSON.parse(l.slice(6)));
+    return answers.filter((m) => m.id === id).pop() ?? answers.pop();
+  };
+  try {
+    const session = createTaskSessionFromClient(client as never, {
+      endpointId: `${base}/mcp`,
+      rawDispatch: rawDispatch as never,
+      v2RequestFraming: { protocolVersion: MODERN, clientInfo, clientCapabilities },
+    } as never);
+    const execution = await session.callTool(
+      // THE TOOL NAME FROM THE TASK'S ONE URI (docs/mcp/MCP_TASKS.md § 2a): a task URI or its short
+      // form `<org>/<name>` is called as `<org>.<name>`; anything else (a bare app id) as given.
+      taskToolName(toolId) ?? toolId,
+      args as never,
+      {
+        ...(ctx.trace?.executionId && ctx.trace?.nodeId ? { metadata: { [TRACE_META]: ctx.trace as never } } : {}),
+        // A person completing a form, or an Agent working: either may take many minutes; the run's own cap ends it first.
+        requestTimeoutMs: 24 * 60 * 60 * 1000,
+      },
+    );
+    if (execution.kind === "task") console.log(`[unoverse:task] FOLLOW ${toolId}: followed as an MCP task to its result`);
+    // THE CALLING RUN STOPPED: the task it follows is cancelled (native `tasks/cancel`), so it does
+    // not run on for nobody. The outcome then reads cancelled, and the call fails with it.
+    const stop = () => {
+      if (execution.kind !== "task") return;
+      console.log(`[unoverse:task] CANCEL ${toolId}: its caller's run stopped`);
+      void execution.cancel().catch(() => {});
+    };
+    if (ctx.signal?.aborted) stop();
+    else ctx.signal?.addEventListener("abort", stop, { once: true });
+    try {
+      // WHAT THE TASK IS DOING, AS IT CHANGES (docs/mcp/MCP_TASKS.md § 5). The extension's own
+      // settle hands every task update to `onEvent`; each new statusMessage goes to the caller,
+      // once per change, and a caller that did not ask for them is never told.
+      let lastStatus = "";
+      const onEvent = ctx.onStatus
+        ? (event: { type: string; task?: { statusMessage?: string } }) => {
+            const message = event.type === "task" ? String(event.task?.statusMessage ?? "").trim() : "";
+            if (!message || message === lastStatus) return;
+            lastStatus = message;
+            try {
+              ctx.onStatus!(message);
+            } catch {
+              /* a listener's failure never fails the task it watches */
+            }
+          }
+        : undefined;
+      const { outcome } = await execution.settle(onEvent ? ({ onEvent } as never) : undefined);
+      return resultFromTaskOutcome(outcome) as CallResult;
+    } finally {
+      ctx.signal?.removeEventListener("abort", stop);
+    }
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+/** A workflow Task: its result comes back as `output.result`, the run's result as text. */
+export async function invokeWorkflowTask(
+  toolId: string,
+  ctx: AppInvocationContext,
+): Promise<{ status: "completed"; output?: Record<string, unknown>; conversationId?: string; message?: string }> {
+  const result = await callFollowingTasks(
+    toolId,
+    {
+      message: ctx.message ?? "",
+      ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
+      ...(ctx.userId ? { userId: ctx.userId } : {}),
+      ...(ctx.chatId ? { chatId: ctx.chatId } : {}),
+      ...((ctx.args ?? {}) as Record<string, never>),
+    },
+    ctx,
+  );
+  const text = result.content?.find((c) => c.type === "text")?.text ?? "";
+  if (result.isError) throw new Error(text || `${toolId} did not complete`);
+  return {
+    status: "completed",
+    output: { result: text },
+    conversationId: ctx.conversationId,
+    message:
+      "The Agent completed. `output.result` is what it found, already shown to the person on screen. " +
+      "Continue the task with it: answer from it, and do not repeat it verbatim unless asked.",
+  };
+}
+
 export async function invokeTaskNative(
   toolId: string,
   ctx: AppInvocationContext,
 ): Promise<{ status: "completed"; output?: Record<string, unknown>; conversationId?: string; action?: string; message?: string }> {
-  const { client, close } = await connectPlatformMcp(ctx);
-  try {
-    const result = (await client.callTool(
+  {
+    const result = (await callFollowingTasks(
+      toolId,
       {
-        // Org-qualified refs are served as dotted aliases (no "/" in MCP tool names).
-        name: toolId.replace(/\//g, "."),
-        arguments: {
-          message: ctx.message ?? "",
-          ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
-          ...(ctx.userId ? { userId: ctx.userId } : {}),
-          ...(ctx.chatId ? { chatId: ctx.chatId } : {}),
-          ...(ctx.props ? { props: ctx.props } : {}),
-          ...(ctx.instanceId ? { instanceId: ctx.instanceId } : {}),
-          ...(ctx.fromRow ? { fromRow: true } : {}),
-          ...(ctx.shell ? { shell: true } : {}),
-          ...(typeof ctx.rank === "number" ? { rank: ctx.rank } : {}),
-          ...(ctx.batch ? { batch: ctx.batch } : {}),
-          // A workflow task's own arguments, as the model wrote them against the task's schema.
-          ...(ctx.args ?? {}),
-        },
-        ...(ctx.trace?.executionId && ctx.trace?.nodeId ? { _meta: { [TRACE_META]: ctx.trace } } : {}),
+        message: ctx.message ?? "",
+        ...(ctx.conversationId ? { conversationId: ctx.conversationId } : {}),
+        ...(ctx.userId ? { userId: ctx.userId } : {}),
+        ...(ctx.chatId ? { chatId: ctx.chatId } : {}),
+        ...(ctx.props ? { props: ctx.props } : {}),
+        ...(ctx.instanceId ? { instanceId: ctx.instanceId } : {}),
+        ...(ctx.fromRow ? { fromRow: true } : {}),
+        ...(ctx.shell ? { shell: true } : {}),
+        ...(typeof ctx.rank === "number" ? { rank: ctx.rank } : {}),
+        ...(ctx.batch ? { batch: ctx.batch } : {}),
+        // A workflow task's own arguments, as the model wrote them against the task's schema.
+        ...(ctx.args ?? {}),
       },
-      undefined,
-      // A human is completing the wizard, or an Agent is working — lift the SDK's 60s default to 24h.
-      { timeout: 24 * 60 * 60 * 1000 },
+      ctx,
     )) as {
       isError?: boolean;
       content?: Array<{ type: string; text?: string }>;
@@ -167,8 +299,6 @@ export async function invokeTaskNative(
               "The component is now displayed on the user's screen. Continue your answer for the user now — the render is a visual aid, not your reply.",
           }),
     };
-  } finally {
-    await close();
   }
 }
 

package/vendor/base/src/agent-mcp/tools.ts

@@ -5,7 +5,7 @@
  * the row at all, so its input schema is read LIVE from the app's own resource at mint time.
  */
 import type { AgentToolDef, DiscoveredMCP, AppInvocationContext, OfferedFunction } from "./types.js";
-import { connectPlatformMcp, invokeTaskNative } from "./invoke.js";
+import { connectPlatformMcp, invokeTaskNative, invokeWorkflowTask } from "./invoke.js";
 import { APP_ETIQUETTE } from "./discovery.js";
 
 /**
@@ -109,30 +109,35 @@ export function isBindinglessComponentApp(mcp: DiscoveredMCP): boolean {
   return !!mcp.component && !mcp.workflowId;
 }
 
-/** A workflow task (2026-09-06): a task-augmented native tool, held until the Agent's run completes. */
+/** A workflow task (2026-09-06): a native tool the harness follows as an MCP task to its result (step 6). */
 export function isWorkflowTask(mcp: DiscoveredMCP): boolean {
   return !!mcp.taskTool;
 }
 
+/** What a caller may hear while a task it called runs: its status, each time it changes. */
+export type TaskCallHooks = Pick<AppInvocationContext, "onStatus">;
+
 /**
  * THE ONE workflow-task adapter every agent family wires for a discovered workflow task.
  * The model's arguments go to the tool as they are (the task's own input schema shaped
  * them); the identity rides beside them so the server pushes the face into THIS
- * conversation and runs the Agent as THIS caller. The held call resolves with the run's
- * result in `output.result`.
+ * conversation and runs the Agent as THIS caller. The task is followed to its result
+ * (docs/mcp/MCP_TASKS.md step 6), which comes back in `output.result`.
  */
 export function workflowTaskInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace">,
-): (input: unknown) => ReturnType<typeof invokeTaskNative> {
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace" | "signal">,
+): (input: unknown, hooks?: TaskCallHooks) => ReturnType<typeof invokeWorkflowTask> {
   const toolId = mcp.taskTool as string;
-  return (input: unknown) => {
+  return (input: unknown, hooks?: TaskCallHooks) => {
     const { message, ...rest } = (input ?? {}) as Record<string, unknown>;
-    return invokeTaskNative(toolId, {
+    return invokeWorkflowTask(toolId, {
+      ...(hooks?.onStatus ? { onStatus: hooks.onStatus } : {}),
       conversationId: identity.conversationId,
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.signal ? { signal: identity.signal } : {}),
       ...(identity.trace ? { trace: { ...identity.trace, kind: "task" } } : {}),
       ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",
@@ -157,7 +162,7 @@ export function workflowTaskInvoker(
  */
 export function componentAppInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "trace">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "trace" | "signal">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = mcp.component as string;
   return (input: unknown) => {
@@ -167,6 +172,7 @@ export function componentAppInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.signal ? { signal: identity.signal } : {}),
       ...(identity.trace ? { trace: { ...identity.trace, kind: mcp.task ? "task" : "tool" } } : {}),
       message: typeof message === "string" ? message : "",
       ...(Object.keys(hydrated).length ? { props: hydrated } : {}),
@@ -192,7 +198,7 @@ export function componentAppInvoker(
  */
 export function workflowAppInvoker(
   mcp: DiscoveredMCP,
-  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace">,
+  identity: Pick<AppInvocationContext, "conversationId" | "userId" | "chatId" | "accessToken" | "baseUrl" | "trace" | "signal">,
 ): (input: unknown) => ReturnType<typeof invokeTaskNative> {
   const toolId = String(mcp.methodName);
   return (input: unknown) => {
@@ -202,6 +208,7 @@ export function workflowAppInvoker(
       userId: identity.userId,
       accessToken: identity.accessToken,
       chatId: identity.chatId,
+      ...(identity.signal ? { signal: identity.signal } : {}),
       ...(identity.trace ? { trace: { ...identity.trace, kind: mcp.task ? "task" : "tool" } } : {}),
       ...(identity.baseUrl ? { baseUrl: identity.baseUrl } : {}),
       message: typeof message === "string" ? message : "",

package/vendor/base/src/agent-mcp/types.ts

@@ -111,6 +111,14 @@ export interface AppInvocationContext {
    * Sent as the call's `_meta`, never as an argument; absent for a call no model made.
    */
   trace?: { executionId?: string; nodeId?: string; kind?: "tool" | "task" };
+  /** The calling run's stop signal: when the run stops, a task it follows is cancelled (`tasks/cancel`). */
+  signal?: AbortSignal;
+  /**
+   * WHAT THE TASK IS DOING NOW, as it changes: each new `statusMessage` of a task this call
+   * follows, from the tasks extension's own updates (docs/mcp/MCP_TASKS.md § 5, "what reaches
+   * the model"). The caller decides what to do with it; an Agent narrates it.
+   */
+  onStatus?: (statusMessage: string) => void;
   /** The caller's stream session — where the wizard renders and elicitation is answered. */
   conversationId?: string;
   userId?: string;

package/vendor/base/src/auth/agentSwitch.ts

@@ -0,0 +1,52 @@
+/**
+ * SWITCHING AN AGENT ON (docs/architecture/signal/AGENTS.md § 7, § 7a; UNO-221).
+ *
+ * An Agent folder says the most it may ever do (`access`). It does nothing until a person switches
+ * it on in this environment; that person is responsible for it (`act` on its token). Three rules:
+ *
+ *   - no daily budget, no Agent (§ 9): switching on is refused;
+ *   - the person must hold everything in `access`: refused, naming what they lack;
+ *   - its token carries `access` capped at what the owner holds, never more.
+ *
+ * Pure: who the person is and what they hold come in; the engine keeps the switch
+ * (`engine/src/agentKeys/agentSwitch.ts`).
+ */
+import { grantedTo } from "../security/permissions.js";
+
+/** What switching on needs from the Agent's folder. */
+export interface SwitchableAgent {
+  /** `<org>/<name>`. */
+  ref: string;
+  access: string[];
+  budget?: { perDay?: string };
+}
+
+/** The person switching it on, as the gate read them. */
+export interface SwitchingPerson {
+  id: string;
+  roles?: string[];
+  permissions?: string[];
+}
+
+export type SwitchCheck =
+  | { ok: true; ownerPermissions: string[] }
+  | { ok: false; reason: "no-budget" | "lacks-access"; missing: string[]; message: string };
+
+/** May this person switch this Agent on? When yes, what they hold is kept as the cap. */
+export function checkSwitchOn(agent: SwitchableAgent, person: SwitchingPerson): SwitchCheck {
+  if (!agent.budget?.perDay?.trim()) {
+    return { ok: false, reason: "no-budget", missing: [], message: `${agent.ref} has no daily budget: set budget.perDay in its agent.yaml` };
+  }
+  const held = grantedTo(person);
+  const missing = agent.access.filter((p) => !held.has(p as never));
+  if (missing.length) {
+    return { ok: false, reason: "lacks-access", missing, message: `To switch on ${agent.ref} you need ${missing.join(", ")}` };
+  }
+  return { ok: true, ownerPermissions: [...held].sort() };
+}
+
+/** What its token carries: its `access`, never more than the owner holds. */
+export function agentPermissions(access: string[], ownerPermissions: string[]): string[] {
+  const owner = new Set(ownerPermissions);
+  return access.filter((p) => owner.has(p));
+}

package/vendor/base/src/auth/agentToken.ts

@@ -0,0 +1,142 @@
+/**
+ * AN AGENT'S TOKEN: an Agent working with nobody signed in runs as itself.
+ *
+ * Design: docs/auth-security/IDENTITY.md, Agents; docs/architecture/signal/AGENTS.md § 7. The
+ * Agent is its folder, `agent:<org>/<name>`; its token is signed by THIS CELL, not by the login
+ * provider, so it works the same whatever provider signs people in. Its permissions are its
+ * folder's `access`, capped at what its owner holds (`agentSwitch.ts`); `act` names the owner.
+ *
+ * No database here. The engine keeps the key (`engine/src/agentKeys/`) and hands it in; a
+ * test can drive every branch with a key it made itself. The one network read is
+ * `engineAgentKeys`, the public half, fetched from the engine when a token is checked.
+ */
+
+import { SignJWT, jwtVerify, decodeJwt, importJWK, generateKeyPair, exportJWK, createRemoteJWKSet, type JWK, type JWTPayload, type JWTVerifyGetKey } from "jose";
+
+/** `iss` on every Agent token. A cell-local name: each cell signs with its own key, so a
+ *  token from another cell carries the same name and still fails the signature. */
+export const AGENT_ISSUER = "unoverse:agent";
+
+/** Every Agent's user id starts with this, so a node can tell one from a person. */
+export const AGENT_ID_PREFIX = "agent:";
+
+export const AGENT_ALG = "ES256";
+
+/** The longest a run is expected to take. A token is signed per run. */
+export const AGENT_TOKEN_TTL_SECONDS = 3600;
+
+export interface AgentClaims {
+  /** The Agent, `<org>/<name>`: its folder. */
+  agent: string;
+  /** Its title, for the run history. */
+  name: string;
+  /** The person who switched it on, and is accountable for it. */
+  ownerId: string;
+  /** Its `access`, already capped at the owner's own. */
+  permissions: string[];
+}
+
+export function isAgentId(id: unknown): id is string {
+  return typeof id === "string" && id.startsWith(AGENT_ID_PREFIX);
+}
+
+/** A cell's signing key as plain JSON: what the engine stores and hands in. */
+export interface AgentKeyPair {
+  kid: string;
+  publicJwk: JWK;
+  privateJwk: JWK;
+}
+
+/** Make a new key pair. The engine calls this once per cell and stores the result. */
+export async function newAgentKeyPair(kid: string): Promise<AgentKeyPair> {
+  const { publicKey, privateKey } = await generateKeyPair(AGENT_ALG, { extractable: true });
+  const publicJwk = { ...(await exportJWK(publicKey)), kid, alg: AGENT_ALG, use: "sig" };
+  const privateJwk = { ...(await exportJWK(privateKey)), kid, alg: AGENT_ALG };
+  return { kid, publicJwk, privateJwk };
+}
+
+/** Sign one run's token. `audience` is the cell's `AUTH_AUDIENCE`, the same as a person's. */
+export async function signAgentToken(
+  claims: AgentClaims,
+  key: { kid: string; privateJwk: JWK },
+  audience: string | undefined,
+  now: Date = new Date(),
+): Promise<string> {
+  const iat = Math.floor(now.getTime() / 1000);
+  const jwt = new SignJWT({
+    name: claims.name,
+    permissions: claims.permissions,
+    act: { sub: claims.ownerId },
+  })
+    .setProtectedHeader({ alg: AGENT_ALG, kid: key.kid, typ: "at+jwt" })
+    .setIssuer(AGENT_ISSUER)
+    .setSubject(`${AGENT_ID_PREFIX}${claims.agent}`)
+    .setIssuedAt(iat)
+    .setExpirationTime(iat + AGENT_TOKEN_TTL_SECONDS);
+  if (audience) jwt.setAudience(audience);
+  return jwt.sign(await importJWK(key.privateJwk, AGENT_ALG));
+}
+
+/** Is this token one this platform signed for an Agent? Read, not verified: it only picks
+ *  which check to run. */
+export function isAgentToken(token: string): boolean {
+  try {
+    return decodeJwt(token).iss === AGENT_ISSUER;
+  } catch {
+    return false;
+  }
+}
+
+export interface VerifiedAgent {
+  id: string;
+  name?: string;
+  ownerId?: string;
+  permissions: string[];
+  raw: JWTPayload;
+}
+
+/**
+ * Check an Agent's token: signature against the cell's keys, issuer, expiry, audience.
+ * Null when any of them fails. FAIL CLOSED: a token without a `permissions` list, or whose
+ * subject is not an Agent id, is refused rather than read as "no permissions".
+ */
+export async function verifyAgentToken(
+  token: string,
+  keys: JWTVerifyGetKey,
+  audience: string | undefined,
+): Promise<VerifiedAgent | null> {
+  try {
+    const { payload } = await jwtVerify(token, keys, {
+      issuer: AGENT_ISSUER,
+      algorithms: [AGENT_ALG],
+      ...(audience ? { audience } : {}),
+    });
+    if (!isAgentId(payload.sub) || !Array.isArray(payload.permissions)) return null;
+    const act = payload.act as { sub?: unknown } | undefined;
+    return {
+      id: payload.sub,
+      name: typeof payload.name === "string" ? payload.name : undefined,
+      ownerId: typeof act?.sub === "string" ? act.sub : undefined,
+      permissions: (payload.permissions as unknown[]).filter((p): p is string => typeof p === "string"),
+      raw: payload,
+    };
+  } catch (error) {
+    const code = (error as { code?: string }).code;
+    console.warn(`[auth] Agent token refused: ${code ?? (error as Error).message}`);
+    return null;
+  }
+}
+
+/**
+ * The cell's public Agent keys, from the engine's internal listener. The same address the
+ * server and the memory service already use to reach the engine (`WORKFLOW_SERVICE_URL`).
+ * jose caches the set and refetches it when a token names a key it has not seen.
+ */
+let engineKeys: JWTVerifyGetKey | null = null;
+export function engineAgentKeys(): JWTVerifyGetKey {
+  if (!engineKeys) {
+    const engine = (process.env.WORKFLOW_SERVICE_URL || "http://localhost:4101").replace(/\/$/, "");
+    engineKeys = createRemoteJWKSet(new URL(`${engine}/agent-keys/jwks.json`));
+  }
+  return engineKeys;
+}

package/vendor/base/src/auth/auth.ts

@@ -14,6 +14,7 @@
 import { jwtVerify, createRemoteJWKSet, JWTPayload } from "jose";
 import { isAuthEnabled, devIdentity } from "./authConfig.js";
 import { grantedTo } from "../security/permissions.js";
+import { isAgentToken, verifyAgentToken, engineAgentKeys } from "./agentToken.js";
 
 // Read env lazily (not at module load) so it's correct regardless of when .env loads.
 //
@@ -145,6 +146,12 @@ export async function validateJWT(token: string): Promise<AuthUser | null> {
 }
 
 async function verifyJWT(token: string): Promise<AuthUser | null> {
+  // AN AGENT'S TOKEN is signed by this cell, not the login provider (IDENTITY.md, Agents):
+  // checked against the cell's own keys, never the provider's. No email, no roles.
+  if (isAgentToken(token)) {
+    const agent = await verifyAgentToken(token, engineAgentKeys(), getAudience());
+    return agent ? { id: agent.id, roles: [], permissions: agent.permissions, raw: agent.raw } : null;
+  }
   const jwksSet = await getJWKS();
   const issuers = getIssuerCandidates();
   if (!jwksSet || issuers.length === 0) {

package/vendor/base/src/definitions/load/load.ts

@@ -184,7 +184,12 @@ export function loadDefinition(
             if (m.preview && typeof m.preview === "object") def.preview = m.preview as Record<string, string[]>;
             // THE WORKFLOW THAT WORKS IT (UNOVERSE_HOST_PAGE.md rule 4): the manifest names it,
             // and the page reads it here to start a call on it.
-            if (m.binding && typeof m.binding === "object") def.binding = m.binding as { workflow?: string; trigger?: string; pipeline?: string };
+            if (m.binding && typeof m.binding === "object") def.binding = m.binding as { workflow?: string; trigger?: string; pipeline?: string; autoTrigger?: boolean };
+            // THE TASK IT CARRIES (docs/design/lifecycle-hooks.md): which moments have a hook, so a
+            // page that draws it knows to ask for its task. Only the moments ride; the calls stay
+            // on the server, in the template's folder.
+            if (Array.isArray(m.lifecycle))
+              (def as unknown as Record<string, unknown>).lifecycle = (m.lifecycle as Array<Record<string, unknown>>).map((e) => ({ phase: e?.phase }));
             // SPATIAL-CAPABLE, exactly as a component is (§9c, ruled 2026-08-30): a
             // template is found by what a guest says, through the same projection, the
             // same registry switch and the same embedded text. The difference is only

package/vendor/base/src/definitions/registry/agentFolders.ts

@@ -0,0 +1,113 @@
+/**
+ * AGENTS AS FOLDERS, READ (docs/architecture/signal/AGENTS.md § 3, § 3a).
+ *
+ * One shape for every Agent: `agents/<name>/agent.yaml` and its soul (`SOUL.md`). This reads them
+ * for whoever shows or runs an Agent (Studio's Agents lane, Signal, Spatial). A flat file directly
+ * in `agents/` is the older Agent file (agents.ts), read there until it is converted.
+ *
+ * Read as written: the lint (`lintObjects`) is what refuses a broken one; here a folder that cannot
+ * be read is left out with a warning, never taking the org's other Agents with it
+ * (UNOVERSE_ORGANISATION.md § 11).
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { listOrgs, projectDir } from "./homes.js";
+import { isolated } from "../isolated.js";
+
+/** One Agent trigger, as the file writes it: what wakes it, and the node behind it. */
+export interface AgentTrigger {
+  name: string;
+  node?: string;
+  wakes?: string;
+  config?: Record<string, unknown>;
+}
+
+/** An Agent folder: its file as written, its soul's words, where it is. */
+export interface AgentFolder {
+  /** `<org>/<name>`. */
+  ref: string;
+  org: string;
+  name: string;
+  title?: string;
+  role?: string;
+  description?: string;
+  whenToUse?: string;
+  category?: string;
+  version?: string;
+  avatar?: string;
+  skills: string[];
+  model?: { use?: string; reasoning?: string; fallback?: string };
+  budget?: { perDay?: string; perRun?: string };
+  tasks: string[];
+  access: string[];
+  triggers: AgentTrigger[];
+  checkIn?: string;
+  memory?: { agent?: string };
+  askWhenUnsure?: string;
+  /** The soul's own words (character only), empty when the file is missing. */
+  soul: string;
+  /** The folder, relative to the org repo. */
+  path: string;
+}
+
+const str = (v: unknown): string | undefined => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+const strs = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && !!x.trim()) : []);
+const rec = (v: unknown): Record<string, unknown> | undefined => (v && typeof v === "object" && !Array.isArray(v) ? (v as Record<string, unknown>) : undefined);
+
+/** One Agent folder of an org, or null when it is not one. */
+export function readAgentFolder(root: string, org: string, name: string): AgentFolder | null {
+  const dir = join(root, "agents", name);
+  const file = join(dir, "agent.yaml");
+  if (!existsSync(file)) return null;
+  const doc = (parse(readFileSync(file, "utf8")) as Record<string, unknown>) ?? {};
+  if (doc.type !== "agent") return null;
+  const soulName = str(doc.soul) ?? "SOUL.md";
+  const soulFile = join(dir, soulName);
+  const model = rec(doc.model);
+  const budget = rec(doc.budget);
+  const memory = rec(doc.memory);
+  return {
+    ref: `${org}/${name}`,
+    org,
+    name,
+    title: str(doc.title),
+    role: str(doc.role),
+    description: str(doc.description),
+    whenToUse: str(doc.whenToUse),
+    category: str(doc.category),
+    version: str(doc.version),
+    avatar: str(doc.avatar),
+    skills: strs(doc.skills),
+    ...(model ? { model: { use: str(model.use), reasoning: str(model.reasoning), fallback: str(model.fallback) } } : {}),
+    ...(budget ? { budget: { perDay: str(budget.perDay), perRun: str(budget.perRun) } } : {}),
+    tasks: strs(doc.tasks),
+    access: strs(doc.access),
+    triggers: (Array.isArray(doc.triggers) ? doc.triggers : [])
+      .map(rec)
+      .filter((c): c is Record<string, unknown> => !!c && !!str(c.name))
+      .map((c) => ({ name: str(c.name)!, node: str(c.node), wakes: str(c.wakes), ...(rec(c.config) ? { config: rec(c.config) } : {}) })),
+    checkIn: str(doc.checkIn),
+    ...(memory ? { memory: { agent: str(memory.agent) } } : {}),
+    askWhenUnsure: str(doc.askWhenUnsure),
+    soul: existsSync(soulFile) ? readFileSync(soulFile, "utf8") : "",
+    path: `agents/${name}`,
+  };
+}
+
+/** Every Agent folder of one org, by name. */
+export function listAgentFoldersIn(root: string, org: string): AgentFolder[] {
+  const dir = join(root, "agents");
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !e.name.startsWith("_"))
+    .map((e) => isolated(`agent ${org}/${e.name}`, () => readAgentFolder(root, org, e.name)) ?? null)
+    .filter((a): a is AgentFolder => a !== null)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Every Agent folder across the workspace, or one org's. */
+export function listAgentFolders(org?: string): AgentFolder[] {
+  const orgs = org && org !== "all" ? [org] : listOrgs();
+  return orgs.flatMap((o) => listAgentFoldersIn(projectDir(o), o));
+}