@nylorun/runtime 0.12.0-beta → 0.14.0-beta

package/dist/streams/types.d.ts

@@ -1,3 +1,43 @@
+/**
+ * The Durable Streams seam (Durable Streams §8).
+ *
+ * Durable Streams deliver what the record holds. Each Tenant has one S2 basin per basin
+ * generation (`streams/basin.ts`); inside it:
+ *
+ * | Stream | Contents | Written by | Read by |
+ * | --- | --- | --- | --- |
+ * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
+ * | `tenant/control` | `session.cancel`, `sessions.reset` and `subject.revoked` signals | API nodes | every process with the Tenant open |
+ *
+ * **Basin generations.** A session id is unique within its Tenant's basin generation. A
+ * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
+ * a session created again with the same id starts in an empty basin at sequence 0; the old
+ * basin is deleted afterwards. The cursor is `base64url("<sessionId>:<seq>")`.
+ *
+ * S2 is the supported implementation (`adapters/streams/s2.ts`, the only file
+ * importing the S2 SDK); `streams/memory.ts` is the in-memory fake.
+ *
+ * ## Guarantees every implementation keeps
+ *
+ * - **Sequence numbers.** Each stream numbers its records from 0 without gaps.
+ *   The tail is the sequence the next appended record gets (0 for a stream
+ *   that does not exist yet).
+ * - **Conditional appends.** With `matchSeq`, a batch is appended only when the
+ *   tail equals `matchSeq`; otherwise nothing is written and the result is a
+ *   `SeqMismatch` carrying the current tail. The relay appends a session
+ *   stream with `matchSeq` set to the record row's sequence, so a retried
+ *   append after an unacknowledged success is detected and never duplicated.
+ * - **Batches are atomic.** A batch is appended entirely or not at all.
+ * - **Reads resume.** `read` from `fromSeq` yields every record with
+ *   `seq >= fromSeq` in order, with no gap between history and the live tail.
+ * - **Tenant scope.** Methods take a Tenant id, or a basin key from `basinOf`
+ *   for a later generation. `ensureTenant` creates the basin (idempotent) and
+ *   must run before appends; streams are created on first append or read.
+ *   `deleteTenant` removes the basin and every stream in it (with
+ *   `allGenerations`, every generation's basin of the Tenant).
+ * - **Records are JSON.** Bodies are JSON-serializable values; implementations
+ *   encode them as they need.
+ */
 /** A record as read from a stream. */
 export interface StreamRecord<T = unknown> {
     seq: number;
@@ -48,9 +88,14 @@ export interface DurableStreams {
     tail(tenantId: string, stream: string): Promise<number>;
     /** Creates the Tenant's basin. Idempotent. */
     ensureTenant(tenantId: string): Promise<void>;
-    /** Deletes the Tenant's basin and all its streams. Idempotent. */
-    deleteTenant(tenantId: string): Promise<void>;
-    /** Deletes one stream (an abandoned session incarnation). Idempotent. */
+    /**
+     * Deletes the basin and all its streams. Idempotent. With `allGenerations`, given a Tenant
+     * id, also every later generation's basin (Tenant deletion).
+     */
+    deleteTenant(tenantId: string, options?: {
+        allGenerations?: boolean;
+    }): Promise<void>;
+    /** Deletes one stream. Idempotent. */
     deleteStream(tenantId: string, stream: string): Promise<void>;
     /**
      * Names of the Tenant's streams starting with `prefix`, in name order,
@@ -66,50 +111,35 @@ export interface DurableStreams {
     probe?(signal: AbortSignal): Promise<void>;
 }
 export declare const SESSION_STREAM_PREFIX = "sessions/";
-/** `work_available` signals for executor connections. */
-export declare const WORK_STREAM = "tenant/work";
 /** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
 export declare const CONTROL_STREAM = "tenant/control";
+/** The stream of a session: `sessions/<sessionId>`. */
+export declare function sessionStream(sessionId: string): string;
 /**
- * The incarnation of a session document written before incarnations existed.
- * Random incarnations are 12 characters, so never this.
- */
-export declare const LEGACY_INCARNATION = "0";
-/** A new session incarnation: 12 random base64url characters. */
-export declare function newStreamIncarnation(): string;
-/** The stream of one incarnation of a session: `sessions/<sessionId>/<incarnation>`. */
-export declare function sessionStream(sessionId: string, incarnation: string): string;
-/** The fields of a session document that name its stream. */
-export interface SessionStreamRef {
-    id: string;
-    /** Set when the session is created (`newStreamIncarnation`); never changed. */
-    streamIncarnation?: string;
-}
-/** The stream of a session as stored now. */
-export declare function streamOfSession(session: SessionStreamRef): string;
-/** The session id and incarnation of a session stream, or undefined for other streams. */
-export declare function parseSessionStream(stream: string): {
-    sessionId: string;
-    incarnation: string;
-} | undefined;
-/**
- * Signals are not canonical events: they are appended without the outbox, and
- * a lost signal costs latency, not correctness.
+ * Signals are not events: they are appended directly, never recorded, and a
+ * lost signal costs latency, not correctness.
  */
-export interface WorkSignal {
-    type: "work_available";
-}
 /** Ends the advance of `sessionId` on the process running it. */
 export interface SessionCancelSignal {
     type: "session.cancel";
     sessionId: string;
 }
 /**
- * Session streams were abandoned (a Tenant reset): each process checks its
- * session feeds and ends those whose session is gone or has a new incarnation.
+ * The Tenant was reset and moved to basin generation `generation`. Appended to the old
+ * generation's `tenant/control`: each process switches its readers to the new basin and
+ * ends the streams of sessions the reset deleted.
  */
 export interface SessionsResetSignal {
     type: "sessions.reset";
+    generation?: number;
+}
+/**
+ * A subject's tokens older than `epoch` were revoked: each process ends that subject's
+ * streams opened with them.
+ */
+export interface SubjectRevokedSignal {
+    type: "subject.revoked";
+    subject: string;
+    epoch: number;
 }
-export type ControlSignal = SessionCancelSignal | SessionsResetSignal;
-export declare const WORK_AVAILABLE: Readonly<WorkSignal>;
+export type ControlSignal = SessionCancelSignal | SessionsResetSignal | SubjectRevokedSignal;

package/dist/streams/types.js

@@ -1,24 +1,18 @@
 /**
- * The Durable Streams seam (architecture §12.4).
+ * The Durable Streams seam (Durable Streams §8).
  *
- * Durable Streams tell everyone else what the Session Store recorded. Each
- * Tenant has one S2 basin; inside it:
+ * Durable Streams deliver what the record holds. Each Tenant has one S2 basin per basin
+ * generation (`streams/basin.ts`); inside it:
  *
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
- * | `sessions/<sessionId>/<incarnation>` | every `LiveEvent` of one incarnation of the session, in sequence | the relay, from the outbox | history and session SSE |
- * | `tenant/work` | `work_available` signals | API nodes and Workers after committing pending Actions | executor SSE on every API node |
- * | `tenant/control` | `session.cancel` and `sessions.reset` signals | API nodes | every process with the Tenant open |
+ * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
+ * | `tenant/control` | `session.cancel`, `sessions.reset` and `subject.revoked` signals | API nodes | every process with the Tenant open |
  *
- * **Incarnations.** A session's stream name carries an incarnation, a random
- * id stored on the session document when the session is created
- * (`streamIncarnation`, see `streamOfSession`). A session deleted by a reset
- * and created again with the same id gets a new incarnation, so a new stream
- * starting at sequence 0: nothing ever deletes and re-creates the same stream.
- * Abandoned streams are deleted best effort afterwards
- * (`collectSessionStreams` in `tenant/streams.ts`). The cursor stays
- * `base64url("<sessionId>:<seq>")`; readers resolve the incarnation from the
- * session.
+ * **Basin generations.** A session id is unique within its Tenant's basin generation. A
+ * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
+ * a session created again with the same id starts in an empty basin at sequence 0; the old
+ * basin is deleted afterwards. The cursor is `base64url("<sessionId>:<seq>")`.
  *
  * S2 is the supported implementation (`adapters/streams/s2.ts`, the only file
  * importing the S2 SDK); `streams/memory.ts` is the in-memory fake.
@@ -31,56 +25,27 @@
  * - **Conditional appends.** With `matchSeq`, a batch is appended only when the
  *   tail equals `matchSeq`; otherwise nothing is written and the result is a
  *   `SeqMismatch` carrying the current tail. The relay appends a session
- *   stream with `matchSeq` set to the outbox row's sequence, so a retried
+ *   stream with `matchSeq` set to the record row's sequence, so a retried
  *   append after an unacknowledged success is detected and never duplicated.
  * - **Batches are atomic.** A batch is appended entirely or not at all.
  * - **Reads resume.** `read` from `fromSeq` yields every record with
  *   `seq >= fromSeq` in order, with no gap between history and the live tail.
- * - **Tenant scope.** `ensureTenant` creates the Tenant's basin (idempotent)
- *   and must run before appends; streams are created on first append.
- *   `deleteTenant` removes the basin and every stream in it.
+ * - **Tenant scope.** Methods take a Tenant id, or a basin key from `basinOf`
+ *   for a later generation. `ensureTenant` creates the basin (idempotent) and
+ *   must run before appends; streams are created on first append or read.
+ *   `deleteTenant` removes the basin and every stream in it (with
+ *   `allGenerations`, every generation's basin of the Tenant).
  * - **Records are JSON.** Bodies are JSON-serializable values; implementations
  *   encode them as they need.
  */
-import { randomBytes } from "node:crypto";
 // ---------------------------------------------------------------------------
 // Stream names and signal records
 export const SESSION_STREAM_PREFIX = "sessions/";
-/** `work_available` signals for executor connections. */
-export const WORK_STREAM = "tenant/work";
 /** `session.cancel` and `sessions.reset` signals for every process with the Tenant open. */
 export const CONTROL_STREAM = "tenant/control";
-/**
- * The incarnation of a session document written before incarnations existed.
- * Random incarnations are 12 characters, so never this.
- */
-export const LEGACY_INCARNATION = "0";
-/** A new session incarnation: 12 random base64url characters. */
-export function newStreamIncarnation() {
-    return randomBytes(9).toString("base64url");
-}
-/** The stream of one incarnation of a session: `sessions/<sessionId>/<incarnation>`. */
-export function sessionStream(sessionId, incarnation) {
+/** The stream of a session: `sessions/<sessionId>`. */
+export function sessionStream(sessionId) {
     if (!sessionId)
         throw new Error("sessionId is required");
-    if (!incarnation || incarnation.includes("/"))
-        throw new Error("incarnation must be non-empty and contain no '/'");
-    return `${SESSION_STREAM_PREFIX}${sessionId}/${incarnation}`;
-}
-/** The stream of a session as stored now. */
-export function streamOfSession(session) {
-    return sessionStream(session.id, session.streamIncarnation ?? LEGACY_INCARNATION);
-}
-/** The session id and incarnation of a session stream, or undefined for other streams. */
-export function parseSessionStream(stream) {
-    if (!stream.startsWith(SESSION_STREAM_PREFIX))
-        return undefined;
-    const rest = stream.slice(SESSION_STREAM_PREFIX.length);
-    const slash = rest.lastIndexOf("/");
-    if (slash <= 0 || slash === rest.length - 1)
-        return undefined;
-    return { sessionId: rest.slice(0, slash), incarnation: rest.slice(slash + 1) };
+    return `${SESSION_STREAM_PREFIX}${sessionId}`;
 }
-export const WORK_AVAILABLE = Object.freeze({
-    type: "work_available",
-});

package/dist/tenant/access-policy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The Tenant's access policy (Host feature `subject-tokens`): the roles subject tokens are
+ * minted for, what a publishable key grants alone (`anon`), and how long tokens live. One
+ * validated JSON document in the Tenant settings; a Tenant that never set one has no roles,
+ * so nothing can be minted.
+ *
+ * A token's permissions are resolved from the policy on every request, so editing a role
+ * changes outstanding tokens at their next request and removing one ends them.
+ */
+import { type AccessPolicy, type RoleLimits, type TokenScope } from "@nylorun/core/contracts";
+import type { Tx } from "../store/types.js";
+export declare const ACCESS_POLICY_SETTING = "access.policy";
+export declare function readPolicy(t: Tx): Promise<AccessPolicy>;
+export declare function writePolicy(t: Tx, policy: AccessPolicy): Promise<void>;
+/** What a token may do right now: its role narrowed by what the mint asked for. */
+export interface EffectiveAccess {
+    readonly role: string;
+    readonly scopes: ReadonlySet<TokenScope>;
+    readonly agents: ReadonlySet<string> | "*";
+    readonly limits?: RoleLimits;
+}
+/** Agents both lists allow; `"*"` allows every agent. */
+export declare function intersectAgents(a: readonly string[] | "*", b: readonly string[] | "*" | undefined): ReadonlySet<string> | "*";
+/**
+ * The role's permissions narrowed to `scopes` and `agents`, or undefined when the role no
+ * longer exists.
+ */
+export declare function resolveRole(policy: AccessPolicy, role: string, scopes: readonly TokenScope[], agents?: readonly string[]): EffectiveAccess | undefined;
+/** True when `agentId` is allowed by `agents`. */
+export declare function agentAllowed(agents: ReadonlySet<string> | "*", agentId: string): boolean;

package/dist/tenant/access-policy.js

@@ -0,0 +1,52 @@
+/**
+ * The Tenant's access policy (Host feature `subject-tokens`): the roles subject tokens are
+ * minted for, what a publishable key grants alone (`anon`), and how long tokens live. One
+ * validated JSON document in the Tenant settings; a Tenant that never set one has no roles,
+ * so nothing can be minted.
+ *
+ * A token's permissions are resolved from the policy on every request, so editing a role
+ * changes outstanding tokens at their next request and removing one ends them.
+ */
+import { AccessPolicySchema, DEFAULT_ACCESS_POLICY, } from "@nylorun/core/contracts";
+export const ACCESS_POLICY_SETTING = "access.policy";
+export async function readPolicy(t) {
+    const stored = await t.getSetting(ACCESS_POLICY_SETTING);
+    if (stored === undefined)
+        return DEFAULT_ACCESS_POLICY;
+    // Only `writePolicy` stores it, after validation.
+    return AccessPolicySchema.parse(JSON.parse(stored));
+}
+export async function writePolicy(t, policy) {
+    await t.putSetting(ACCESS_POLICY_SETTING, JSON.stringify(AccessPolicySchema.parse(policy)));
+}
+/** Agents both lists allow; `"*"` allows every agent. */
+export function intersectAgents(a, b) {
+    if (b === undefined || b === "*")
+        return a === "*" ? "*" : new Set(a);
+    if (a === "*")
+        return new Set(b);
+    const allowed = new Set(a);
+    return new Set(b.filter((agent) => allowed.has(agent)));
+}
+/**
+ * The role's permissions narrowed to `scopes` and `agents`, or undefined when the role no
+ * longer exists.
+ */
+export function resolveRole(policy, role, scopes, agents) {
+    const entry = Object.hasOwn(policy.roles, role)
+        ? policy.roles[role]
+        : undefined;
+    if (!entry)
+        return undefined;
+    const allowed = new Set(entry.scopes);
+    return {
+        role,
+        scopes: new Set(scopes.filter((scope) => allowed.has(scope))),
+        agents: intersectAgents(entry.agents, agents),
+        ...(entry.limits ? { limits: entry.limits } : {}),
+    };
+}
+/** True when `agentId` is allowed by `agents`. */
+export function agentAllowed(agents, agentId) {
+    return agents === "*" || agents.has(agentId);
+}

package/dist/tenant/actions.d.ts

@@ -1,153 +1,14 @@
-import type { IncomingMessage } from "node:http";
-import { type RegisterExecutorsRequestSchema } from "@nylorun/core/contracts";
-import { type ExecutorRecord } from "../core/executors.js";
 import { type SandboxRouteDeps } from "../core/sandbox-routes.js";
-import { type AuthScope, type TenantContext } from "./context.js";
-type RegisterExecutorsRequest = ReturnType<typeof RegisterExecutorsRequestSchema.parse>;
+import { type TenantContext } from "./context.js";
+import type { DeliveryScope } from "./delivery-token.js";
 /** Session and Action lookups for the sandbox route handlers. */
 export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;
-/** `GET /v1/actions`: the pending Actions of the executor's agent. */
-export declare function listPendingActions(ctx: TenantContext, executor: ExecutorRecord): Promise<{
-    actions: ({
-        actionId: string;
-        sessionId: string;
-        turnId: string;
-        agentId: string;
-        manifestHash: string;
-        implementationVersion: string;
-        input: unknown;
-        context: Record<string, unknown>;
-        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
-        generation: number;
-        claimId: string | null;
-        leaseExpiresAt: string | null;
-        agent?: {
-            id: string;
-            path: string;
-            delegationId?: string | undefined;
-        } | undefined;
-        kind: "tool";
-        capabilityId: string;
-        toolName: string;
-        inputSchema?: Record<string, unknown> | undefined;
-        outputSchema?: Record<string, unknown> | undefined;
-    } | {
-        actionId: string;
-        sessionId: string;
-        turnId: string;
-        agentId: string;
-        manifestHash: string;
-        implementationVersion: string;
-        input: unknown;
-        context: Record<string, unknown>;
-        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
-        generation: number;
-        claimId: string | null;
-        leaseExpiresAt: string | null;
-        agent?: {
-            id: string;
-            path: string;
-            delegationId?: string | undefined;
-        } | undefined;
-        kind: "tool";
-        path: string;
-        key: string;
-        inputSchema?: Record<string, unknown> | undefined;
-        outputSchema?: Record<string, unknown> | undefined;
-    } | {
-        actionId: string;
-        sessionId: string;
-        turnId: string;
-        agentId: string;
-        manifestHash: string;
-        implementationVersion: string;
-        input: unknown;
-        context: Record<string, unknown>;
-        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
-        generation: number;
-        claimId: string | null;
-        leaseExpiresAt: string | null;
-        agent?: {
-            id: string;
-            path: string;
-            delegationId?: string | undefined;
-        } | undefined;
-        kind: "hook";
-        hook: {
-            at: "after" | "before";
-            scope: "step" | "turn";
-            capabilityIds: string[];
-        };
-    } | {
-        actionId: string;
-        sessionId: string;
-        turnId: string;
-        agentId: string;
-        manifestHash: string;
-        implementationVersion: string;
-        input: unknown;
-        context: Record<string, unknown>;
-        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
-        generation: number;
-        claimId: string | null;
-        leaseExpiresAt: string | null;
-        agent?: {
-            id: string;
-            path: string;
-            delegationId?: string | undefined;
-        } | undefined;
-        kind: "fn";
-        path: string;
-        key: string;
-    } | {
-        actionId: string;
-        sessionId: string;
-        turnId: string;
-        agentId: string;
-        manifestHash: string;
-        implementationVersion: string;
-        input: unknown;
-        context: Record<string, unknown>;
-        status: "cancelled" | "claimed" | "completed" | "pending" | "uncertain";
-        generation: number;
-        claimId: string | null;
-        leaseExpiresAt: string | null;
-        agent?: {
-            id: string;
-            path: string;
-            delegationId?: string | undefined;
-        } | undefined;
-        kind: "verify";
-        path: string;
-        key: string;
-    })[];
+/** `POST /v1/actions/:id/sandbox/:tool`: a sandbox tool call for the Action being delivered. */
+export declare function actionSandboxTool(ctx: TenantContext, scope: DeliveryScope, actionId: string, toolName: string, body: () => Promise<unknown>, signal: AbortSignal): Promise<{
+    kind: "completed";
+    output: unknown;
+} | {
+    kind: "failed";
+    code: string;
+    message: string;
 }>;
-/** `POST /v1/actions/:id/sandbox/:tool`: a claim-scoped sandbox tool call. */
-export declare function actionSandboxTool(ctx: TenantContext, scope: AuthScope, actionId: string, toolName: string, request: IncomingMessage): Promise<import("../sandbox/tools.js").SandboxToolOutcome>;
-/** `POST /v1/actions/:id/claim` and `/heartbeat`; anything else under the Action is a 404. */
-export declare function updateAction(ctx: TenantContext, scope: AuthScope, actionId: string, method: string | undefined, operation: string | undefined, body: unknown): Promise<unknown>;
-/** `GET /v1/executors`. */
-export declare function listExecutors(ctx: TenantContext): {
-    executors: {
-        agentId: string;
-        implementationVersion: string;
-        manifestHash?: string | undefined;
-        connected: boolean;
-        updatedAt: string;
-    }[];
-};
-/** `PUT /v1/executors`: persist the batch, then update the registry and end rotated streams. */
-export declare function registerExecutors(ctx: TenantContext, principalId: string, body: RegisterExecutorsRequest): Promise<{
-    executors: {
-        agentId: string;
-        implementationVersion: string;
-        rotated: boolean;
-        replacedBy?: "different-credential" | undefined;
-    }[];
-}>;
-/** `DELETE /v1/executors/:agentId`: forget the executor and end its streams. */
-export declare function deleteExecutor(ctx: TenantContext, agentId: string): Promise<{
-    agentId: string;
-    deleted: boolean;
-}>;
-export {};