@nylorun/runtime 0.11.0-beta → 0.13.0-beta

package/dist/tenant/effects.js

@@ -1,4 +1,5 @@
-import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowEffect, isFlowToolEffect, linkedMessageKey, linkedTurnEnd, } from "../core/flow-host.js";
+import { embeddedAgent, flowDelegateManifest, hashManifest, isWorkflowManifestV2, } from "@nylorun/core/define";
+import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowEffect, isFlowToolEffect, isWorkflowManifest, linkedMessageKey, linkedTurnEnd, } from "../core/flow-host.js";
 import { mayDispatchMore } from "../core/limits.js";
 import { canonical } from "../store/canonical.js";
 import { isOwnershipLost } from "../store/ownership.js";
@@ -10,8 +11,9 @@ import { sandboxCapabilityOf } from "../sandbox/manager.js";
 import { owningSandboxSessionId, sandboxSpecOf } from "../sandbox/share.js";
 import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
-import { actionTarget, linkedAgentOutput, manifestFor, mcpToolOf, pinnedTool, } from "./session.js";
+import { actionTarget, linkedAgentOutput, manifestFor, mcpToolOf, pinnedTool, turnManifestOf, } from "./session.js";
 import { command } from "./commands.js";
+import { assistantMessage, toolCompleted, toolIds } from "./transcript.js";
 import { abortKind } from "./worker.js";
 export function invokeModel(ctx, request, signal, model) {
     if (model)
@@ -51,6 +53,20 @@ async function linkedOutcome(t, effect, agent) {
         },
     };
 }
+/**
+ * What an effect's journal row must match on replay. A delegation's context carries only the
+ * parent's tool call id, for its events; rows journaled before it existed still match.
+ */
+function requestIdentity(request) {
+    if (request.kind !== "delegation")
+        return request;
+    const { context: _, ...identity } = request;
+    return identity;
+}
+function delegationCallId(request) {
+    const callId = request.context?.callId;
+    return typeof callId === "string" ? { callId } : {};
+}
 export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
     const { store } = ctx;
     const journaled = await store.tx(async (t) => {
@@ -65,7 +81,7 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
         });
         const existing = await t.get("effects", request.effectId);
         if (existing) {
-            if (canonical(existing.request) !== canonical(request))
+            if (canonical(requestIdentity(existing.request)) !== canonical(requestIdentity(request)))
                 throw new Error("Effect identity request drift");
             if (existing.status === "completed")
                 return resolved({ status: "completed", outcome: existing.outcome });
@@ -104,7 +120,11 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
                 outcome,
             });
             const settled = request.effectId.endsWith(":settled");
-            await t.event(s.id, s.activeTurnId, settled ? "delegation.completed" : "delegation.started", { agent: request.agent, ...request.input });
+            await t.event(s.id, s.activeTurnId, settled ? "delegation.completed" : "delegation.started", {
+                agent: request.agent,
+                ...delegationCallId(request),
+                ...request.input,
+            });
             return resolved({ status: "completed", outcome });
         }
         const agentManifest = manifestFor(s.manifest, request.agent);
@@ -166,6 +186,7 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             actionId: action.actionId,
             kind: action.kind,
             ...actionTarget(action),
+            ...(action.kind === "tool" ? toolIds(request.context) : {}),
             input: action.input,
         });
         t.signalWork();
@@ -198,6 +219,11 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             effect.status = "completed";
             effect.outcome = { value };
             await t.put("effects", request.effectId, effect);
+            const transcript = invoke === "model"
+                ? assistantMessage(request, value)
+                : toolCompleted(request, value);
+            if (transcript)
+                await t.event(s.id, request.turnId, invoke === "model" ? "message.assistant" : "tool.completed", transcript);
             return { status: "completed", outcome: effect.outcome };
         });
     }
@@ -361,8 +387,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         await ownedSession(t, lease, workflow.id);
         if (exists)
             return;
-        const definition = (await t.get("definitions", body.agentId)) ??
-            fail(404, "Definition not found");
+        const definition = await leafDefinition(t, workflow, body, request);
         const sandboxOwnerId = sandboxSpecOf(workflow.manifest) || workflow.sandboxOwnerId
             ? owningSandboxSessionId(workflow, await sandboxLookup(t, workflow.sandboxOwnerId))
             : undefined;
@@ -415,13 +440,15 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
     return store.tx(async (t) => {
         const s = await ownedSession(t, lease, request.sessionId);
         const agent = await sessionOf(t, agentSessionId);
-        await t.event(s.id, s.activeTurnId, "loop.iteration", {
-            path: String(request.context.loopPath ?? path.split("/")[0]),
-            n,
-            sessionId: agentSessionId,
-            turnId: accepted.turnId ?? undefined,
-            manifestHash: agent.checkpoint?.manifestHash,
-        });
+        // Only a Loop's own agent turns are iterations; a step elsewhere in the flow is not.
+        if (typeof request.context.loopPath === "string")
+            await t.event(s.id, s.activeTurnId, "loop.iteration", {
+                path: request.context.loopPath,
+                n,
+                sessionId: agentSessionId,
+                turnId: accepted.turnId ?? undefined,
+                manifestHash: agent.checkpoint?.manifestHash,
+            });
         await t.event(s.id, s.activeTurnId, "node.agent", {
             path,
             iterations,
@@ -537,3 +564,50 @@ export async function authorize(ctx, sessionId, request) {
     }
     return result;
 }
+/**
+ * The definition a flow leaf's session runs. A v2 workflow embeds its leaves, so they
+ * come from the workflow's own manifest and can't drift from it; v1 leaves come from the
+ * registry by id.
+ */
+async function leafDefinition(t, workflow, body, request) {
+    // A flow agent used as a tool: its manifest is inlined in the parent's pinned tool.
+    if (request.context.role === "delegate" && !isWorkflowManifest(workflow.manifest)) {
+        const flow = flowDelegateManifest(turnManifestOf(workflow), body.agentId);
+        if (!flow)
+            return fail(404, `Agent '${body.agentId}' is not a flow agent used as a tool`);
+        return {
+            manifest: flow,
+            manifestHash: hashManifest(flow),
+            implementationVersion: workflow.implementationVersion,
+            pluginRoots: leafPluginRoots(workflow.pluginRoots, body.agentId),
+        };
+    }
+    if (isWorkflowManifestV2(workflow.manifest)) {
+        const leaf = embeddedAgent(workflow.manifest, body.flow ?? [], body.agentId);
+        if (!leaf || isWorkflowManifestV2(leaf))
+            fail(404, `Agent '${body.agentId}' is not embedded in workflow '${workflow.manifest.id}'`);
+        const manifest = leaf;
+        return {
+            manifest,
+            manifestHash: hashManifest(manifest),
+            implementationVersion: workflow.implementationVersion,
+            pluginRoots: leafPluginRoots(workflow.pluginRoots, body.agentId),
+        };
+    }
+    const definition = await t.get("definitions", body.agentId);
+    if (!definition)
+        fail(404, "Definition not found");
+    return definition;
+}
+/**
+ * A v2 workflow keys its leaves' plugin roots `<agentId>/<capability>`, and an agent keys
+ * a flow agent it uses as a tool the same way (`<flowId>/<leafId>/<capability>`).
+ */
+function leafPluginRoots(roots, agentId) {
+    const own = {};
+    const prefix = `${agentId}/`;
+    for (const [key, root] of Object.entries(roots ?? {}))
+        if (key.startsWith(prefix))
+            own[key.slice(prefix.length)] = root;
+    return own;
+}

package/dist/tenant/http.d.ts

@@ -11,11 +11,17 @@ export declare const OPAQUE_NOT_FOUND: {
     code: "not_found";
     message: string;
 };
+/** A rejection's stable code and details, for the ones a client acts on (default `request_rejected`). */
+export interface Rejection {
+    readonly code?: string;
+    readonly details?: unknown;
+}
 export declare class HttpError extends Error {
     readonly status: number;
-    constructor(status: number, message: string);
+    readonly rejection: Rejection;
+    constructor(status: number, message: string, rejection?: Rejection);
 }
-export declare const fail: (status: number, message: string) => never;
+export declare const fail: (status: number, message: string, rejection?: Rejection) => never;
 export declare class OpaqueAuthError extends Error {
     readonly status = 404;
     readonly body: {

package/dist/tenant/http.js

@@ -6,13 +6,15 @@ export const OPAQUE_NOT_FOUND = {
 };
 export class HttpError extends Error {
     status;
-    constructor(status, message) {
+    rejection;
+    constructor(status, message, rejection = {}) {
         super(message);
         this.status = status;
+        this.rejection = rejection;
     }
 }
-export const fail = (status, message) => {
-    throw new HttpError(status, message);
+export const fail = (status, message, rejection) => {
+    throw new HttpError(status, message, rejection);
 };
 export class OpaqueAuthError extends Error {
     status = 404;

package/dist/tenant/module.js

@@ -152,6 +152,9 @@ export function createTenantModule(options) {
                 ...(input.studioCredentialHash
                     ? { studioCredentialHash: input.studioCredentialHash }
                     : {}),
+                ...(input.derivedPrincipals?.length
+                    ? { derivedPrincipals: input.derivedPrincipals }
+                    : {}),
             };
             // The store records its own schema version.
             const envelope = envelopeNow({

package/dist/tenant/principals.d.ts

@@ -9,5 +9,8 @@ export declare const STUDIO_PRINCIPAL_ID = "studio";
  * Exported for WS-B's `TenantStore.create` (A3).
  */
 export declare function bootstrapPrincipal(t: Tx, bootstrap: BootstrapPrincipal, now?: Date): Promise<void>;
-/** Whether the stored bootstrap (and Studio) principals equal `bootstrap`. */
+/**
+ * Whether the stored bootstrap, Studio and derived principals equal `bootstrap`. A retried
+ * create names the same derived principals, so each must be stored with its hash.
+ */
 export declare function bootstrapPrincipalMatches(t: Tx, bootstrap: BootstrapPrincipal): Promise<boolean>;

package/dist/tenant/principals.js

@@ -22,8 +22,19 @@ export async function bootstrapPrincipal(t, bootstrap, now = new Date()) {
             idempotencyKey: null,
             createdAt,
         });
+    for (const principal of bootstrap.derivedPrincipals ?? [])
+        await t.insertPrincipal({
+            id: principal.id,
+            role: "application",
+            tokenHash: principal.credentialHash,
+            idempotencyKey: null,
+            createdAt,
+        });
 }
-/** Whether the stored bootstrap (and Studio) principals equal `bootstrap`. */
+/**
+ * Whether the stored bootstrap, Studio and derived principals equal `bootstrap`. A retried
+ * create names the same derived principals, so each must be stored with its hash.
+ */
 export async function bootstrapPrincipalMatches(t, bootstrap) {
     const row = await t.principalById(bootstrap.principalId);
     if (!row ||
@@ -32,6 +43,14 @@ export async function bootstrapPrincipalMatches(t, bootstrap) {
         row.idempotencyKey !== bootstrap.idempotencyKey)
         return false;
     const studio = await t.principalById(STUDIO_PRINCIPAL_ID);
-    return ((studio?.role === "application" ? studio.tokenHash : undefined) ===
-        bootstrap.studioCredentialHash);
+    if ((studio?.role === "application" ? studio.tokenHash : undefined) !==
+        bootstrap.studioCredentialHash)
+        return false;
+    for (const principal of bootstrap.derivedPrincipals ?? []) {
+        const stored = await t.principalById(principal.id);
+        if (stored?.role !== "application" ||
+            stored.tokenHash !== principal.credentialHash)
+            return false;
+    }
+    return true;
 }

package/dist/tenant/routes-tenant.js

@@ -2,6 +2,7 @@ import { CreateCredentialRequestSchema, CreateVaultRequestSchema, PutHostModelRe
 import { hostModelCatalog } from "../model/catalog.js";
 import { resetTenant } from "./reset.js";
 import { buildTenantStatus, seedTenantConfig } from "./status.js";
+import { ownerOf } from "./auth.js";
 import { fail, readBody } from "./http.js";
 import { clearExecutorStreams, clearObservers } from "./live.js";
 import { requestStreamCollection, sessionStreamsAbandoned, streamsStatus, } from "./streams.js";
@@ -9,7 +10,8 @@ import { clearWork, drain } from "./scheduler.js";
 import { usesFixtureModel } from "./model-setting.js";
 export async function dispatchTenant(ctx, scope, method, path, request) {
     const { vault } = ctx;
-    if (scope.kind !== "application") {
+    // A subject reaches only the routes `authorize` allowed its scopes.
+    if (scope.kind === "executor") {
         await vault.reject(path.join("/"));
         fail(403, "Application credential required");
     }
@@ -83,22 +85,31 @@ export async function dispatchTenant(ctx, scope, method, path, request) {
 }
 export async function dispatchVault(ctx, scope, method, path, url, request) {
     const { vault } = ctx;
-    if (scope.kind !== "application") {
+    if (scope.kind === "executor") {
         await vault.reject(path.join("/"));
         fail(403, "Application credential required");
     }
+    // Acting for a subject: only the subject's own vaults, and never on another's behalf.
+    const owner = ownerOf(scope);
     if (path.length === 2 && method === "POST") {
         const body = CreateVaultRequestSchema.parse(await readBody(request));
+        if (owner !== undefined && body.ownerUserId !== owner)
+            fail(403, "ownerUserId must be the subject");
         return vault.createVault(body);
     }
     if (path.length === 2 && method === "GET") {
         const ownerUserId = url.searchParams.get("ownerUserId") ??
+            owner ??
             fail(400, "ownerUserId is required");
+        if (owner !== undefined && ownerUserId !== owner)
+            fail(403, "ownerUserId must be the subject");
         return { vaults: await vault.listVaults(ownerUserId) };
     }
     const vaultId = path[2];
     if (!vaultId)
         fail(404, "Vault not found");
+    if (owner !== undefined)
+        await vault.assertOwner(vaultId, owner);
     if (path.length === 3 && method === "GET")
         return vault.getVault(vaultId);
     if (path.length === 3 && method === "DELETE")

package/dist/tenant/routes.js

@@ -3,7 +3,7 @@ import { VaultError } from "../vault/error.js";
 import { SandboxRouteError, handleSessionSandboxTool, } from "../core/sandbox-routes.js";
 import { loadSession, sessionOf } from "./context.js";
 import { HttpError, OpaqueAuthError, fail, readBody, requestAborted, } from "./http.js";
-import { authenticate, requireApplication } from "./auth.js";
+import { authenticate, authorize, ownerOf, requireApplication, requirePrincipal, } from "./auth.js";
 import { command } from "./commands.js";
 import { actionSandboxTool, deleteExecutor, listExecutors, listPendingActions, registerExecutors, sandboxRouteDeps, updateAction, } from "./actions.js";
 import { listDefinitions, listSessions, putDefinition, putSession, sessionView, } from "./sessions.js";
@@ -28,6 +28,9 @@ export async function handle(ctx, request, response, _url) {
         const scope = await authenticate(ctx, request);
         if (path[0] !== "v1")
             fail(404, "Route not found");
+        authorize(scope, method, path);
+        // Set when the request acts for a subject: only the subject's own sessions are reachable.
+        const owner = ownerOf(scope);
         if (path[1] === "executors" && path[2] === "connect" && method === "GET") {
             if (scope.kind !== "executor")
                 return fail(403, "Executor credential required");
@@ -59,7 +62,7 @@ export async function handle(ctx, request, response, _url) {
             return json(await dispatchVault(ctx, scope, method, path, url, request));
         if (path[1] === "tenant")
             return json(await dispatchTenant(ctx, scope, method, path, request));
-        const principalId = requireApplication(scope);
+        const principalId = requirePrincipal(scope);
         if (path[1] === "executors" && path.length === 2 && method === "GET")
             return json(listExecutors(ctx));
         // The length guard matters: the connect branch above only matches GET, so without it a
@@ -74,7 +77,7 @@ export async function handle(ctx, request, response, _url) {
         if (path[1] === "agents" && path.length === 2 && method === "GET")
             return json(await listDefinitions(ctx));
         if (path[1] === "sessions" && path.length === 2 && method === "GET")
-            return json(await listSessions(ctx, url.searchParams.get("agentId")));
+            return json(await listSessions(ctx, url.searchParams.get("agentId"), owner));
         if (path[1] === "agents" &&
             path[2] &&
             path.length === 3 &&
@@ -84,13 +87,13 @@ export async function handle(ctx, request, response, _url) {
             const id = path[2];
             if (method === "PUT" && path.length === 3) {
                 const body = PutSessionRequestSchema.parse(await readBody(request));
-                const session = await putSession(ctx, id, body);
+                const session = await putSession(ctx, id, body, owner);
                 return json(await ctx.store.tx((t) => sessionView(t, session)));
             }
             if (method === "GET" && path.length === 3)
-                return json(await ctx.store.tx(async (t) => sessionView(t, await sessionOf(t, id))));
+                return json(await ctx.store.tx(async (t) => sessionView(t, await sessionOf(t, id, owner))));
             // Every other session route needs the session to exist.
-            await loadSession(ctx, id);
+            await loadSession(ctx, id, owner);
             const cursor = requestCursor(request, url);
             if (method === "GET" && path[3] === "items")
                 return json(await readHistory(ctx, id, cursor, url.searchParams.get("agent") ?? undefined));
@@ -133,10 +136,16 @@ export async function handle(ctx, request, response, _url) {
                 error?.message === "Invalid cursor"
                 ? 400
                 : 500;
+        const rejection = error instanceof HttpError ? error.rejection : {};
         json({
             status: "rejected",
-            code: status === 500 ? "internal_error" : "request_rejected",
+            code: status === 500
+                ? "internal_error"
+                : rejection.code ?? "request_rejected",
             message: status === 500 ? "Runtime request failed" : error.message,
+            ...(rejection.details === undefined
+                ? {}
+                : { details: rejection.details }),
         }, status);
     }
 }

package/dist/tenant/sessions.d.ts

@@ -19,7 +19,8 @@ export declare function putDefinition(ctx: TenantContext, agentId: string, body:
     manifestHash: string;
     implementationVersion: string;
 }>;
-export declare function listSessions(ctx: TenantContext, agentId: string | null): Promise<{
+/** `owner`, when the request acts for a subject, limits the list to that subject's sessions. */
+export declare function listSessions(ctx: TenantContext, agentId: string | null, owner?: string): Promise<{
     sessions: {
         id: string;
         agentId: string;
@@ -28,7 +29,12 @@ export declare function listSessions(ctx: TenantContext, agentId: string | null)
         activeTurnId: string | null;
     }[];
 }>;
-/** Create a session from its definition, or re-attach vaults to an identical one. */
-export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest): Promise<Session>;
+/**
+ * Create a session from its definition, or re-attach vaults to an identical one. `owner`, when
+ * the request acts for a subject, must be the session's owner: another owner's session id is
+ * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
+ * sandboxes.
+ */
+export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, owner?: string): Promise<Session>;
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export declare function sessionView(t: Tx, s: Session): Promise<unknown>;

package/dist/tenant/sessions.js

@@ -42,8 +42,12 @@ export async function putDefinition(ctx, agentId, body) {
         implementationVersion: body.implementationVersion,
     };
 }
-export async function listSessions(ctx, agentId) {
-    const sessions = await ctx.store.tx((t) => t.listSessions(agentId === null ? {} : { agentId }));
+/** `owner`, when the request acts for a subject, limits the list to that subject's sessions. */
+export async function listSessions(ctx, agentId, owner) {
+    const sessions = await ctx.store.tx((t) => t.listSessions({
+        ...(agentId === null ? {} : { agentId }),
+        ...(owner === undefined ? {} : { ownerUserId: owner }),
+    }));
     return {
         sessions: sessions.map((s) => ({
             id: s.id,
@@ -54,20 +58,30 @@ export async function listSessions(ctx, agentId) {
         })),
     };
 }
-/** Create a session from its definition, or re-attach vaults to an identical one. */
-export function putSession(ctx, id, body) {
+/**
+ * Create a session from its definition, or re-attach vaults to an identical one. `owner`, when
+ * the request acts for a subject, must be the session's owner: another owner's session id is
+ * the 404 of a missing one (not the 409 of a mismatch), and so are another owner's vaults and
+ * sandboxes.
+ */
+export function putSession(ctx, id, body, owner) {
     const vaultIds = body.vaultIds ?? [];
     const credentialSelections = body.credentialSelections ?? [];
+    const opaque = owner !== undefined;
+    if (opaque && body.ownerUserId !== owner)
+        fail(403, "ownerUserId must be the subject");
     return ctx.store.tx(async (t) => {
         const prior = await t.lockSession(id);
+        if (opaque && prior && prior.ownerUserId !== owner)
+            fail(404, "Session not found");
         const definition = prior === undefined || body.sandbox
             ? (await t.get("definitions", body.agentId)) ??
                 fail(404, "Definition not found")
             : undefined;
         const sandboxOwnerId = body.sandbox
-            ? validateSandboxAttach(body, (definition ?? prior).manifest, await sandboxLookup(t, body.sandbox.session))
+            ? validateSandboxAttach(body, (definition ?? prior).manifest, await sandboxLookup(t, body.sandbox.session), { opaque })
             : undefined;
-        await ctx.vault.assertAttachment(t, body.ownerUserId, vaultIds, credentialSelections);
+        await ctx.vault.assertAttachment(t, body.ownerUserId, vaultIds, credentialSelections, { opaque });
         if (prior) {
             if (sessionIdentity(prior.creation) !== sessionIdentity(body))
                 fail(409, "Session already exists with different creation parameters");

package/dist/tenant/transcript.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Transcript events (Host feature `transcript-events`): what a chat UI shows, written in the
+ * transaction that completes the effect, so a replayed effect never writes them again.
+ * Payload schemas: `@nylorun/core/contracts` (`parseTranscriptEvent`).
+ */
+import type { HostEffect } from "@nylorun/harness/run";
+/** The model's tool call id and the harness invocation, for tool effects and tool actions. */
+export declare function toolIds(context: unknown): {
+    callId: string;
+    invocationId: string;
+} | Record<string, never>;
+/**
+ * `message.assistant` for a completed model effect: the step's text and tool calls. The
+ * provider returns a `ModelCandidate` or a bare string; anything else writes no event.
+ */
+export declare function assistantMessage(request: HostEffect, value: unknown): {
+    agent: import("@nylorun/core").AgentRef;
+    invocationId: string;
+    text: string;
+    toolCalls: {
+        callId: string;
+        name: string;
+        input: unknown;
+    }[];
+} | {
+    agent?: undefined;
+    invocationId: string;
+    text: string;
+    toolCalls: {
+        callId: string;
+        name: string;
+        input: unknown;
+    }[];
+} | undefined;
+/** `tool.completed` for an MCP or sandbox tool: its output, or the tool error it reported. */
+export declare function toolCompleted(request: HostEffect, value: unknown): {
+    agent: import("@nylorun/core").AgentRef;
+    error: {
+        code: string;
+        message: string;
+    };
+    output?: undefined;
+    capabilityId: string;
+    toolName: string;
+} | {
+    agent?: undefined;
+    error: {
+        code: string;
+        message: string;
+    };
+    output?: undefined;
+    capabilityId: string;
+    toolName: string;
+} | {
+    agent: import("@nylorun/core").AgentRef;
+    error?: undefined;
+    output: unknown;
+    capabilityId: string;
+    toolName: string;
+} | {
+    agent?: undefined;
+    error?: undefined;
+    output: unknown;
+    capabilityId: string;
+    toolName: string;
+} | {
+    callId: string;
+    invocationId: string;
+    agent: import("@nylorun/core").AgentRef;
+    error: {
+        code: string;
+        message: string;
+    };
+    output?: undefined;
+    capabilityId: string;
+    toolName: string;
+} | {
+    callId: string;
+    invocationId: string;
+    agent?: undefined;
+    error: {
+        code: string;
+        message: string;
+    };
+    output?: undefined;
+    capabilityId: string;
+    toolName: string;
+} | {
+    callId: string;
+    invocationId: string;
+    agent: import("@nylorun/core").AgentRef;
+    error?: undefined;
+    output: unknown;
+    capabilityId: string;
+    toolName: string;
+} | {
+    callId: string;
+    invocationId: string;
+    agent?: undefined;
+    error?: undefined;
+    output: unknown;
+    capabilityId: string;
+    toolName: string;
+} | undefined;

package/dist/tenant/transcript.js

@@ -0,0 +1,58 @@
+/** The model's tool call id and the harness invocation, for tool effects and tool actions. */
+export function toolIds(context) {
+    const c = context;
+    return typeof c?.callId === "string" && typeof c.invocationId === "string"
+        ? { callId: c.callId, invocationId: c.invocationId }
+        : {};
+}
+const agentOf = (request) => request.agent ? { agent: request.agent } : {};
+/**
+ * `message.assistant` for a completed model effect: the step's text and tool calls. The
+ * provider returns a `ModelCandidate` or a bare string; anything else writes no event.
+ */
+export function assistantMessage(request, value) {
+    const invocationId = request.context
+        ?.invocationId;
+    if (typeof invocationId !== "string")
+        return undefined;
+    const blocks = typeof value === "string"
+        ? [{ type: "text", text: value }]
+        : Array.isArray(value?.output)
+            ? value.output
+            : [];
+    let text = "";
+    const toolCalls = [];
+    for (const block of blocks) {
+        if (block?.type === "text" && typeof block.text === "string")
+            text += block.text;
+        else if (block?.type === "tool-call" &&
+            typeof block.id === "string" &&
+            typeof block.name === "string")
+            toolCalls.push({ callId: block.id, name: block.name, input: block.args });
+    }
+    if (!text && toolCalls.length === 0)
+        return undefined;
+    return { invocationId, text, toolCalls, ...agentOf(request) };
+}
+/** `tool.completed` for an MCP or sandbox tool: its output, or the tool error it reported. */
+export function toolCompleted(request, value) {
+    const ids = toolIds(request.context);
+    if (!("callId" in ids))
+        return undefined;
+    const outcome = value;
+    const result = outcome?.kind === "failed"
+        ? {
+            error: {
+                code: String(outcome.code ?? "tool.failed"),
+                message: String(outcome.message ?? ""),
+            },
+        }
+        : { output: outcome?.kind === "completed" ? outcome.output : value };
+    return {
+        ...ids,
+        capabilityId: request.capabilityId,
+        toolName: request.toolName,
+        ...result,
+        ...agentOf(request),
+    };
+}

package/dist/tenant/types.d.ts

@@ -109,6 +109,12 @@ export interface BootstrapPrincipal {
     idempotencyKey: string;
     /** When set, also registers application principal `studio` with this hash. */
     studioCredentialHash?: string;
+    /** Application principals whose keys the admin key derives (feature `derived-principals`). */
+    derivedPrincipals?: readonly DerivedPrincipal[];
+}
+export interface DerivedPrincipal {
+    id: string;
+    credentialHash: string;
 }
 /**
  * The deep module (§8). HTTP, CLI and tests use only this.