@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/tenant/harness-tokens.d.ts

@@ -0,0 +1,21 @@
+import type { SessionStore } from "../store/types.js";
+export declare const HARNESS_TOKENS_SETTING = "harness.tokens";
+export interface HarnessTokenInfo {
+    readonly id: string;
+    readonly createdAt: string;
+}
+export type HarnessTokenRefusal = {
+    readonly reason: "invalid_id";
+    readonly message: string;
+};
+/** The harness id `token` is for, or undefined when it is none of the Tenant's harness tokens. */
+export declare function harnessOfToken(store: SessionStore, token: string): Promise<string | undefined>;
+/** Creates or rotates harness `id`'s token; the token is returned this once. */
+export declare function putHarnessToken(store: SessionStore, id: string): Promise<{
+    id: string;
+    token: string;
+    rotated: boolean;
+} | HarnessTokenRefusal>;
+export declare function listHarnessTokens(store: SessionStore): Promise<HarnessTokenInfo[]>;
+/** Deletes harness `id`'s token; whether there was one. */
+export declare function deleteHarnessToken(store: SessionStore, id: string): Promise<boolean>;

package/dist/tenant/harness-tokens.js

@@ -0,0 +1,61 @@
+/**
+ * Per-harness tokens (R4.1): the credential a custom harness's container connects to the Harness
+ * API listener with. Each is bound to one harness id, so a harness can only say that id in
+ * `hello` and only take the sessions pinned to it. Our harness keeps the installation's
+ * `NYLORUN_HARNESS_TOKEN`, bound to `nylorun`; a pod's harness holds neither (it joins).
+ *
+ * The Tenant setting `harness.tokens` keeps each token's sha256 and when it was made, never the
+ * token: `nylorun-operate harness token put <id>` prints it once. Putting an id again rotates its
+ * token; the old one stops working at its next connection.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { DEFAULT_HARNESS, isHarnessId } from "@nylorun/core/contracts";
+export const HARNESS_TOKENS_SETTING = "harness.tokens";
+const sha256 = (token) => createHash("sha256").update(token).digest("hex");
+async function read(store) {
+    const raw = await store.tx((t) => t.getSetting(HARNESS_TOKENS_SETTING));
+    return raw === undefined ? {} : JSON.parse(raw);
+}
+/** The harness id `token` is for, or undefined when it is none of the Tenant's harness tokens. */
+export async function harnessOfToken(store, token) {
+    const hash = Buffer.from(sha256(token), "hex");
+    for (const [id, stored] of Object.entries(await read(store))) {
+        const candidate = Buffer.from(stored.sha256, "hex");
+        if (candidate.length === hash.length && timingSafeEqual(candidate, hash))
+            return id;
+    }
+    return undefined;
+}
+/** Creates or rotates harness `id`'s token; the token is returned this once. */
+export async function putHarnessToken(store, id) {
+    if (!isHarnessId(id))
+        return { reason: "invalid_id", message: `${id} is not a harness id: lowercase letters, digits and dashes, starting with a letter` };
+    if (id === DEFAULT_HARNESS)
+        return { reason: "invalid_id", message: `${DEFAULT_HARNESS} is our harness: it connects with NYLORUN_HARNESS_TOKEN` };
+    const token = randomBytes(32).toString("hex");
+    return store.tx(async (t) => {
+        const raw = await t.getSetting(HARNESS_TOKENS_SETTING);
+        const tokens = raw === undefined ? {} : JSON.parse(raw);
+        const rotated = id in tokens;
+        tokens[id] = { sha256: sha256(token), createdAt: new Date().toISOString() };
+        await t.putSetting(HARNESS_TOKENS_SETTING, JSON.stringify(tokens));
+        return { id, token, rotated };
+    });
+}
+export async function listHarnessTokens(store) {
+    return Object.entries(await read(store))
+        .map(([id, stored]) => ({ id, createdAt: stored.createdAt }))
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Deletes harness `id`'s token; whether there was one. */
+export async function deleteHarnessToken(store, id) {
+    return store.tx(async (t) => {
+        const raw = await t.getSetting(HARNESS_TOKENS_SETTING);
+        const tokens = raw === undefined ? {} : JSON.parse(raw);
+        if (!(id in tokens))
+            return false;
+        delete tokens[id];
+        await t.putSetting(HARNESS_TOKENS_SETTING, JSON.stringify(tokens));
+        return true;
+    });
+}

package/dist/tenant/host-token.d.ts

@@ -85,7 +85,7 @@ declare const KINDS: {
 export declare function verifyHostToken(store: SessionStore, tenantId: string, raw: string, kind: keyof typeof KINDS, cache?: HostTokenKeyCache): Promise<HostTokenVerdict>;
 /**
  * Why a host's claims are stale, or undefined while they are its sandbox's current host: the
- * sandbox exists as a pod sandbox, is not deleted, lost or expired, and its epoch and pod are
+ * sandbox exists as a pod Environment, is not deleted or lost, and its epoch and pod are
  * the token's. One indexed read of the sandbox's row.
  */
 export declare function staleHost(store: SessionStore, claims: HostClaims): Promise<string | undefined>;

package/dist/tenant/host-token.js

@@ -157,11 +157,11 @@ export async function verifyHostToken(store, tenantId, raw, kind, cache = new Ma
 }
 /**
  * Why a host's claims are stale, or undefined while they are its sandbox's current host: the
- * sandbox exists as a pod sandbox, is not deleted, lost or expired, and its epoch and pod are
+ * sandbox exists as a pod Environment, is not deleted or lost, and its epoch and pod are
  * the token's. One indexed read of the sandbox's row.
  */
 export async function staleHost(store, claims) {
-    const row = await store.tx((t) => t.sandboxResource(claims.sandboxId));
+    const row = await store.tx((t) => t.environment(claims.sandboxId));
     const pod = row?.pod;
     if (!row || row.kind !== "pod" || !pod)
         return "the sandbox is gone";
@@ -169,8 +169,6 @@ export async function staleHost(store, claims) {
         return "the sandbox was deleted";
     if (pod.observed === "lost")
         return "the sandbox was lost";
-    if (pod.observed === "expired")
-        return "the sandbox expired";
     if (pod.hostEpoch !== claims.epoch)
         return "another host holds the sandbox now";
     if (pod.podUid !== claims.podUid)

package/dist/tenant/identity-file.d.ts

@@ -15,9 +15,9 @@
  *     # Optional, with their defaults:
  *     subject: "{sub}"                           # scalar claims only
  *     scopes: { claim: scope }                   # or { fixed: [sessions:own, agents:read] }
- *     allowedScopes: [agents:read, sessions:own, sandboxes:write]   # add studio to grant it
+ *     allowedScopes: [agents:read, sessions:own, environments:write]   # add studio to grant it
  *     agents: [support]                          # absent reaches every agent
- *     sandboxes: ["{org_id}/*"]                  # absent reaches no sandbox
+ *     environments: ["{org_id}/*"]               # absent reaches no Environment
  * ```
  */
 import { type KeyObject } from "node:crypto";
@@ -55,8 +55,8 @@ export interface TrustedIssuerConfig {
     readonly allowedScopes: readonly IssuerScope[];
     /** The agents its tokens reach; absent reaches all. */
     readonly agents?: readonly string[];
-    /** Sandbox grant templates, such as `{org_id}/*`; absent reaches no sandbox. */
-    readonly sandboxes?: readonly string[];
+    /** Environment grant templates, such as `{org_id}/*`; absent reaches no Environment. */
+    readonly environments?: readonly string[];
 }
 /** A malformed identity file: the message names the issuer and the field. */
 export declare class IdentityFileError extends Error {

package/dist/tenant/identity-file.js

@@ -15,15 +15,15 @@
  *     # Optional, with their defaults:
  *     subject: "{sub}"                           # scalar claims only
  *     scopes: { claim: scope }                   # or { fixed: [sessions:own, agents:read] }
- *     allowedScopes: [agents:read, sessions:own, sandboxes:write]   # add studio to grant it
+ *     allowedScopes: [agents:read, sessions:own, environments:write]   # add studio to grant it
  *     agents: [support]                          # absent reaches every agent
- *     sandboxes: ["{org_id}/*"]                  # absent reaches no sandbox
+ *     environments: ["{org_id}/*"]               # absent reaches no Environment
  * ```
  */
 import { createPublicKey } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
-import { ISSUER_SCOPES, isSandboxGrant, TOKEN_SANDBOX_GRANTS_MAX, TOKEN_SCOPES, } from "@nylorun/core/contracts";
+import { ISSUER_SCOPES, isEnvironmentGrant, TOKEN_ENVIRONMENT_GRANTS_MAX, TOKEN_SCOPES, } from "@nylorun/core/contracts";
 /** The JWT algorithms an issuer may sign with. */
 export const ISSUER_ALGORITHMS = ["RS256", "ES256", "EdDSA"];
 /** An entry's defaults: the `sub` claim, the RFC 9068 `scope` claim, every token scope but `studio`. */
@@ -119,11 +119,11 @@ const IssuerEntrySchema = z
         .default(DEFAULT_SCOPES),
     allowedScopes: z.array(IssuerScopeSchema).min(1).default([...DEFAULT_ALLOWED_SCOPES]),
     agents: z.array(z.string().min(1)).optional(),
-    sandboxes: z
-        .array(template("a sandbox grant").refine(
+    environments: z
+        .array(template("an Environment grant").refine(
     // A rendered grant must be a grant: checked here with a sample value per claim.
-    (value) => isSandboxGrant(renderTemplate(value, () => "x")), "must render to a sandbox id or a prefix ending in /*, as {org_id}/*"))
-        .max(TOKEN_SANDBOX_GRANTS_MAX)
+    (value) => isEnvironmentGrant(renderTemplate(value, () => "x")), "must render to an Environment id or a prefix ending in /*, as {org_id}/*"))
+        .max(TOKEN_ENVIRONMENT_GRANTS_MAX)
         .optional(),
 });
 const IdentityFileSchema = z.object({ issuers: z.array(z.unknown()) });
@@ -173,6 +173,15 @@ export function parseIdentityFile(text, source = "identity file", options = {})
             ? entry.name
             : `#${index + 1}`;
         const where = `issuer ${named}`;
+        // Protocol 11 renamed these (R2d Q11): refused, never read as no grants.
+        if (entry && typeof entry === "object" && "sandboxes" in entry)
+            return fail(`${where}: sandboxes: renamed environments in protocol 11`);
+        const scopesNamed = JSON.stringify([
+            entry?.allowedScopes,
+            entry?.scopes,
+        ]);
+        if (scopesNamed.includes('"sandboxes:write"'))
+            return fail(`${where}: sandboxes:write: renamed environments:write in protocol 11`);
         const parsed = IssuerEntrySchema.safeParse(entry);
         if (!parsed.success)
             return fail(`${where}: ${issueText(parsed.error.issues)}`);
@@ -207,7 +216,7 @@ export function parseIdentityFile(text, source = "identity file", options = {})
             scopes: value.scopes,
             allowedScopes: [...new Set(value.allowedScopes)],
             ...(value.agents ? { agents: [...new Set(value.agents)] } : {}),
-            ...(value.sandboxes ? { sandboxes: value.sandboxes } : {}),
+            ...(value.environments ? { environments: value.environments } : {}),
         });
     });
     return issuers;

package/dist/tenant/issuers.js

@@ -37,7 +37,7 @@ const JWKS_MAX_BYTES = 256 * 1024;
 const JWKS_MAX_KEYS = 64;
 const DEFAULT_REFETCH_MS = 60_000;
 const DEFAULT_MAX_AGE_MS = 10 * 60_000;
-/** A grant's claim value: one sandbox id segment, so a claim never widens the template. */
+/** A grant's claim value: one Environment id segment, so a claim never widens the template. */
 const GRANT_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 /** The issuer's public keys: static, or its JWKS's as last fetched. */
 class IssuerKeys {
@@ -292,7 +292,7 @@ export async function verifyIssuerToken(ctx, issuer, raw, resourceMetadata) {
     const subject = renderTemplate(config.subject, (claim) => scalarClaim(payload, claim));
     if (subject === undefined || !isSubject(subject) || RESERVED.has(subject))
         return rejected("issuer_token_subject");
-    const sandboxes = config.sandboxes?.flatMap((grant) => {
+    const environments = config.environments?.flatMap((grant) => {
         const rendered = renderTemplate(grant, (claim) => {
             const value = scalarClaim(payload, claim);
             return value !== undefined && GRANT_SEGMENT.test(value) ? value : undefined;
@@ -309,7 +309,7 @@ export async function verifyIssuerToken(ctx, issuer, raw, resourceMetadata) {
         subject,
         scopes: scopesOf(config, payload),
         agents: config.agents ? new Set(config.agents) : "*",
-        sandboxes: [...new Set(sandboxes ?? [])],
+        environments: [...new Set(environments ?? [])],
         expiresAt: payload.exp * 1000,
         tokenId: jti,
         ...(verdict.kid !== undefined ? { keyId: verdict.kid } : {}),

package/dist/tenant/principals.js

@@ -6,7 +6,7 @@
  * `nylorun-operate keys`, `operator-keys.ts`); no other key is derived.
  *
  * The derivation is the one `@nylorun/admin` computes on the client side
- * (`admin/src/derived-credentials.ts`: `deriveStudioToken`); both sides must stay byte for byte
+ * (`sdks/admin/src/derived-credentials.ts`: `deriveStudioToken`); both sides must stay byte for byte
  * the same.
  */
 import { createHmac } from "node:crypto";

package/dist/tenant/reset.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
-import { detachAllSessions } from "./sandboxes.js";
+import { detachAllSessions } from "./environments.js";
 import { contentKey } from "../artifacts/folders.js";
 /**
  * Rename `dir` to a sibling, delete the sibling, recreate an empty `dir`.
@@ -38,14 +38,14 @@ function replaceDirectory(dir) {
  */
 export async function resetTenant(ctx, scope) {
     const clearSessions = scope === "sessions" || scope === "all";
-    const clearSandboxes = scope === "sandboxes" || scope === "all";
+    const clearSandboxes = scope === "environments" || scope === "all";
     const clearAll = scope === "all";
     if (clearSandboxes) {
         await ctx.sandbox.removeAll();
     }
     // The artifacts the reset deletes: their rows go in its transaction, their bytes after it.
     const blobKeys = await ctx.store.tx(async (t) => {
-        // Sandbox resources outlive their sessions: a sessions reset only detaches them.
+        // Environments outlive their sessions: a sessions reset only detaches them.
         if (clearSessions && !clearSandboxes)
             await detachAllSessions(t);
         const scoped = clearAll ? "all" : "sessions";

package/dist/tenant/runtime.d.ts

@@ -14,6 +14,7 @@ import type { HarnessChannel, MemoryPortsOptions } from "@nylorun/core/harness-a
 import { type HarnessPeer } from "../harness-api/server.js";
 import { type HostAuthority } from "../sandbox/join.js";
 import type { TenantPods } from "./context.js";
+import type { TraceOptions } from "../traces/options.js";
 /** TENANTS-CCR: test/injection hooks until TenantConfig gains them. */
 export type TenantOpenHooks = {
     modelProvider?: ModelProvider;
@@ -80,9 +81,11 @@ export type TenantOpenHooks = {
     harnessTap?: MemoryPortsOptions["tap"];
     /**
      * Sandbox pods (F7.2): the sandboxes service (`NYLORUN_SANDBOXES_URL`) and the Runtime image
-     * pods copy the engine from. Without it, kind `pod` is `sandbox_unavailable`.
+     * pods copy the engine from. Without it, kind `pod` is `environment_unavailable`.
      */
     pods?: TenantPods;
+    /** How the trace route makes spans (R7.5): the Host's `OTEL_*` resource and content opt-ins. */
+    traces?: TraceOptions;
 } & OpenedTenant;
 export declare class TenantRuntime implements TenantHandle {
     private readonly ctx;
@@ -97,6 +100,8 @@ export declare class TenantRuntime implements TenantHandle {
     private constructor();
     /** The Tenant's side of a sandbox pod's join (F7.2). */
     hostAuthority(): HostAuthority | undefined;
+    /** The custom harness a per-harness token is for (R4.1), or undefined. */
+    harnessOfToken(token: string): Promise<string | undefined>;
     static open(config: TenantConfig, hooks: TenantOpenHooks): Promise<TenantRuntime>;
     fetch(request: Request, node: NodeBindings): Promise<Response>;
     authorize(sessionId: string, request: {

package/dist/tenant/runtime.js

@@ -29,6 +29,7 @@ import { harnessStatusOf } from "./status.js";
 import { startInProcessHarness, startLoopbackHarness, } from "../harness-api/in-process.js";
 import { localWorkspace, remoteWorkspace, withPodWorkspaces, } from "../harness-api/workspace.js";
 import { hostAuthority } from "../sandbox/join.js";
+import { harnessOfToken } from "./harness-tokens.js";
 import { reconcileSandbox } from "../sandbox/pods/reconcile.js";
 import { sandboxWorkspaceReader } from "../artifacts/workspace.js";
 import { readDefinitionFile } from "./definition-files.js";
@@ -74,6 +75,10 @@ export class TenantRuntime {
     hostAuthority() {
         return this.ctx.closing || this.ctx.closed ? undefined : this.hosts;
     }
+    /** The custom harness a per-harness token is for (R4.1), or undefined. */
+    harnessOfToken(token) {
+        return harnessOfToken(this.ctx.store, token);
+    }
     static async open(config, hooks) {
         const envelope = hooks.envelope;
         const flowLimits = validateConfig(config);
@@ -193,7 +198,7 @@ export class TenantRuntime {
                     store: opened,
                     logger: config.logger,
                     preference,
-                    isPod: async (sandboxId) => (await opened.tx((t) => t.sandboxResource(sandboxId)))?.kind === "pod",
+                    isPod: async (sandboxId) => (await opened.tx((t) => t.environment(sandboxId)))?.kind === "pod",
                 })
                 : workspaces;
             const useVaultModel = config.model.kind === "vault";
@@ -256,6 +261,7 @@ export class TenantRuntime {
                 keys,
                 blobs,
                 workspaces: sandboxWorkspaceReader(sandbox),
+                ...(hooks.traces ? { traces: hooks.traces } : {}),
                 ...(hooks.runGrants ? { runGrants: hooks.runGrants } : {}),
                 workerId: hooks.workerId ?? WORKER_ID,
                 ownerLeaseMs: config.ownerLeaseMs ?? DEFAULT_OWNER_LEASE_MS,
@@ -268,10 +274,14 @@ export class TenantRuntime {
                 abortLocal: (sessionId, turnId) => abortLocal(ctx, sessionId, "cancel", turnId),
                 ...(hooks.pods ? { pods: hooks.pods } : {}),
                 sandboxSignal: async (sandboxId, signal) => {
-                    if (ctx.closing || ctx.closed || !execution.sandbox)
-                        return;
-                    await execution.sandbox(config.tenantId, sandboxId, signal);
+                    if (ctx.closing || ctx.closed)
+                        return false;
+                    await execution.sandbox?.(config.tenantId, sandboxId, signal);
+                    return true;
                 },
+                send: (request) => request.kind === "wake"
+                    ? ctx.wake(request.sessionId, request.wake)
+                    : ctx.sandboxSignal(request.sandboxId, request.signal),
                 ...(hooks.execution?.stuckInvocations
                     ? {
                         stuckInvocations: () => hooks.execution.stuckInvocations(config.tenantId),
@@ -283,6 +293,22 @@ export class TenantRuntime {
                     return () => sweepHooks.delete(hook);
                 },
             };
+            // What a commit asks of the execution goes without the request waiting; a send that
+            // fails is the sweep's to send again, so it is only a warning here.
+            opened.deliverTo(async (request) => {
+                try {
+                    return await ctx.send(request);
+                }
+                catch (error) {
+                    config.logger.warn("outbox delivery after commit failed; the sweep sends it again", {
+                        ...(request.kind === "wake"
+                            ? { sessionId: request.sessionId, reason: request.wake.reason }
+                            : { sandboxId: request.sandboxId, signal: request.signal.kind }),
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                    return false;
+                }
+            });
             harnessServer = createHarnessApiServer(ctx, { sandboxPreference: preference });
             if (mcp && manager)
                 harness = await startInProcessHarness(ctx, { mcp, sandbox: manager }, {

package/dist/tenant/scheduler.d.ts

@@ -5,8 +5,15 @@ export interface WorkState {
     readonly running: Map<string, AbortController>;
     /** The turn each running advance belongs to, by session id (`null`: none). */
     readonly runningTurns: Map<string, string | null>;
+    /** Called once when the last running advance ends (`endAdvance`), then forgotten. */
+    readonly idleWaiters: Set<() => void>;
 }
 export declare function createWorkState(): WorkState;
+/**
+ * Advance `id`'s end on this process: forgets its controller (unless a later advance of the
+ * session replaced it) and, when it was the last, settles every `idle` wait.
+ */
+export declare function endAdvance(work: WorkState, id: string, controller: AbortController): void;
 /**
  * Abort the advance of `id` if it runs on this process.
  * Cancel calls it after committing `cancelled`, and so does the control bus for cancels made

package/dist/tenant/scheduler.js

@@ -10,10 +10,45 @@
  * advance instead of settling it.
  */
 import { randomUUID } from "node:crypto";
+import { sleep } from "../retry.js";
 import { command } from "./commands.js";
 import { AdvanceAbort } from "./worker.js";
 export function createWorkState() {
-    return { running: new Map(), runningTurns: new Map() };
+    return { running: new Map(), runningTurns: new Map(), idleWaiters: new Set() };
+}
+/**
+ * Advance `id`'s end on this process: forgets its controller (unless a later advance of the
+ * session replaced it) and, when it was the last, settles every `idle` wait.
+ */
+export function endAdvance(work, id, controller) {
+    if (work.running.get(id) !== controller)
+        return;
+    work.running.delete(id);
+    work.runningTurns.delete(id);
+    if (work.running.size > 0)
+        return;
+    for (const waiter of work.idleWaiters)
+        waiter();
+    work.idleWaiters.clear();
+}
+/** Resolves once no advance runs on this process, or after `timeoutMs`, whichever is first. */
+async function idle(work, timeoutMs) {
+    if (work.running.size === 0)
+        return;
+    const timer = new AbortController();
+    let settle;
+    const ended = new Promise((resolve) => (settle = resolve));
+    work.idleWaiters.add(settle);
+    try {
+        await Promise.race([
+            ended,
+            sleep(Math.max(0, timeoutMs), timer.signal),
+        ]);
+    }
+    finally {
+        timer.abort();
+        work.idleWaiters.delete(settle);
+    }
 }
 const MESSAGES = {
     cancel: "Turn cancelled",
@@ -56,9 +91,7 @@ export async function drain(ctx, activeWork, timeoutMs) {
                     principalId: "drain",
                 });
     }
-    const deadline = Date.now() + timeoutMs;
-    while (ctx.work.running.size > 0 && Date.now() < deadline)
-        await new Promise((resolve) => setTimeout(resolve, 10));
+    await idle(ctx.work, timeoutMs);
 }
 /** Abort every advance running on this process; closing the Tenant is a `shutdown`. */
 export function abortAll(ctx, kind = "shutdown") {
@@ -72,9 +105,7 @@ export function abortAll(ctx, kind = "shutdown") {
  * (§11.4); the epoch fences anything they still try to write. Returns their session ids.
  */
 export async function waitForIdle(ctx, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (ctx.work.running.size > 0 && Date.now() < deadline)
-        await new Promise((resolve) => setTimeout(resolve, 10));
+    await idle(ctx.work, timeoutMs);
     const abandoned = [...ctx.work.running.keys()];
     if (abandoned.length > 0)
         ctx.config.logger.warn("tenant closed with advances still running", {

package/dist/tenant/session-streams.d.ts

@@ -120,5 +120,4 @@ export declare function checkSessionStreams(ctx: TenantContext): Promise<void>;
 export declare function clearObservers(hub: SessionStreams): void;
 /** Close: end every session observer. */
 export declare function endAllStreams(hub: SessionStreams): void;
-export declare function sleep(ms: number, signal: AbortSignal): Promise<void>;
 export {};

package/dist/tenant/session-streams.js

@@ -20,6 +20,7 @@
  */
 import { historyCursor, historyResume } from "../reads/cursor.js";
 import { decodeCursor, encodeCursor } from "../record/index.js";
+import { sleep } from "../retry.js";
 import { basinOf } from "../streams/basin.js";
 import { sessionStream, } from "../streams/types.js";
 import { fail } from "./http.js";
@@ -405,16 +406,3 @@ export function clearObservers(hub) {
 export function endAllStreams(hub) {
     clearObservers(hub);
 }
-export function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal.aborted)
-            return resolve();
-        const done = () => {
-            clearTimeout(timer);
-            signal.removeEventListener("abort", done);
-            resolve();
-        };
-        const timer = setTimeout(done, ms);
-        signal.addEventListener("abort", done, { once: true });
-    });
-}

package/dist/tenant/session.d.ts

@@ -1,16 +1,16 @@
 /**
- * Pure helpers over the session document: turn-manifest pins and variants, and state rebasing.
+ * Pure helpers over the session document: turn-manifest pins and variants. The engine's state
+ * is the harness's (R4.2): nothing here reads it.
  * No store access and no I/O. (The tools of an MCP snapshot
  * live in `mcp/snapshot.ts`.)
  *
  * Later waves: stable; the async store conversion (Wave 1 / A) does not change these.
  */
 import type { AgentManifest } from "@nylorun/core/define";
-import { type TurnManifestStore } from "../core/turn-manifest.js";
+import type { TurnManifestStore } from "../core/turn-manifest.js";
 import type { Session } from "./context.js";
 export { manifestFor, sessionToolsOf } from "../mcp/snapshot.js";
 /** Turn-manifest store backed by the session's `variants` map (no schema change). */
 export declare function variantStore(session: Session): TurnManifestStore;
 /** Manifest this turn's checkpoint is pinned to (session pin or a stored variant). */
 export declare function turnManifestOf(session: Session): AgentManifest;
-export declare function rebaseSessionState(session: Session, turnHash: string): void;

package/dist/tenant/session.js

@@ -1,4 +1,3 @@
-import { allowedManifestHashes, rebaseTurnState, } from "../core/turn-manifest.js";
 export { manifestFor, sessionToolsOf } from "../mcp/snapshot.js";
 /** Turn-manifest store backed by the session's `variants` map (no schema change). */
 export function variantStore(session) {
@@ -18,16 +17,3 @@ export function turnManifestOf(session) {
         return session.manifest;
     return session.variants?.[hash] ?? session.manifest;
 }
-export function rebaseSessionState(session, turnHash) {
-    const allowed = allowedManifestHashes({
-        pinnedHash: session.manifestHash,
-        variantHashes: Object.keys(session.variants ?? {}),
-    });
-    const next = rebaseTurnState({
-        state: session.state,
-        turnManifestHash: turnHash,
-        isAllowedHash: (hash) => allowed.has(hash),
-    });
-    if (next !== session.state)
-        session.state = next;
-}

package/dist/tenant/sessions.d.ts

@@ -1,7 +1,7 @@
 /**
- * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create or
- * re-attach vaults), the session list and the session view. Reads use the store's typed
- * queries; `PUT /v1/sessions/:id` runs in one transaction with the vault attachment checks.
+ * Session and definition resources: `PUT/GET /v1/agents`, `PUT /v1/sessions/:id` (create, or
+ * find an identical one), the session list and the session view. Reads use the store's typed
+ * queries; `PUT /v1/sessions/:id` runs in one transaction with the Environment's checks.
  */
 import { type PutAgentRequest, type PutSessionRequest } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
@@ -44,14 +44,14 @@ export declare function listSessions(ctx: TenantContext, agentId: string | null,
     }[];
 }>;
 /**
- * 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.
+ * Create a session from its definition, or find an identical one. `access`, 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 is an Environment whose owner guard names
+ * another owner.
  *
- * The session's sandbox is decided here and fixed for its life (§5 of Sandboxes v3): shared
- * with `{ session }`, none with `false`, inline, or the Tenant default when omitted. A definition
- * that declares its own sandbox (`.sandbox()`) keeps it and takes no sandbox request.
+ * The session's Environment is fixed for its life: its sandbox (kinds `virtual` and `pod`) is
+ * the session's, with the spec of the Environment's applied recipe pinned now, and its vault
+ * holds the session's credentials. Without one the session has no sandbox and no credentials.
  */
 export declare function putSession(ctx: TenantContext, id: string, body: PutSessionRequest, access?: SessionAccess, options?: {
     /**
@@ -60,10 +60,10 @@ export declare function putSession(ctx: TenantContext, id: string, body: PutSess
      */
     createOnly?: boolean;
     /**
-     * The sandboxes the caller reaches (a token caller's grants, `sandboxGrantsOf`); undefined
-     * reaches every one. `sandbox: { id }` must name one of them.
+     * The Environments the caller reaches (a token caller's grants, `environmentGrantsOf`);
+     * undefined reaches every one. `environment` must name one of them.
      */
-    sandboxGrants?: readonly string[];
+    environmentGrants?: readonly string[];
 }): Promise<Session>;
 /** The session resource returned by `GET`/`PUT /v1/sessions/:id`. */
 export declare function sessionView(t: Tx, s: Session): Promise<unknown>;