@ricsam/r5d-worker 0.0.172 → 0.0.173

package/dist/mjs/runtime/protocol.mjs

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { OperationEnvelope, OwnershipFence, RUNTIME_PROTOCOL, RuntimeHello, RuntimeId } from "@ricsam/r5d-api/runtime-protocol";
 const EXECUTOR_CAPABILITY = "host-executor-v1";
+const EXECUTOR_STREAM_CAPABILITY = "host-stream-v1";
+const STREAM_CHUNK_BYTES = 64 * 1024;
 const MAX_FRAME_BYTES = 1024 * 1024;
 const text = z.string().max(256 * 1024).refine((s) => !s.includes("\0"), "NUL is not allowed");
 const absolutePath = z.string().min(1).max(4096).refine((s) => s.startsWith("/") && !s.includes("\0"), "Absolute POSIX path required");
@@ -54,7 +56,17 @@ const ExecutorCommand = z.discriminatedUnion("method", [
     cols: z.number().int().min(1).max(1e3),
     rows: z.number().int().min(1).max(1e3)
   }).strict(),
-  z.object({ method: z.literal("cancel"), run: RunIdentity, actionId: RuntimeId }).strict()
+  z.object({ method: z.literal("cancel"), run: RunIdentity, actionId: RuntimeId }).strict(),
+  // Live terminal channel. Neither command has a durable action identity: a
+  // subscription is replayed from an offset, and live input is keystrokes the
+  // person can simply type again, exactly as over ssh.
+  z.object({ method: z.literal("subscribe"), run: RunIdentity, offset: z.number().int().nonnegative().default(0) }).strict(),
+  z.object({
+    method: z.literal("input"),
+    run: RunIdentity,
+    data: text.optional(),
+    resize: z.object({ cols: z.number().int().min(1).max(1e3), rows: z.number().int().min(1).max(1e3) }).strict().optional()
+  }).strict().refine((value) => value.data !== void 0 || value.resize !== void 0, "Input carries data or a size")
 ]);
 const ExecutorRequest = z.object({
   protocol: z.literal(RUNTIME_PROTOCOL),
@@ -124,6 +136,7 @@ export {
   AdapterConfig,
   AdapterGrant,
   EXECUTOR_CAPABILITY,
+  EXECUTOR_STREAM_CAPABILITY,
   ExecutorCommand,
   ExecutorConfig,
   ExecutorCredential,
@@ -133,6 +146,7 @@ export {
   MAX_FRAME_BYTES,
   Principal,
   RunIdentity,
+  STREAM_CHUNK_BYTES,
   ShellPayload,
   isDefiniteStartRejection,
   isStartNonAdmissionCode

package/dist/mjs/runtime/workspace/authority.mjs

@@ -50,6 +50,7 @@ class WorkspaceAuthority {
   closed = false;
   closeTask;
   actions = /* @__PURE__ */ new Set();
+  subscriptions = /* @__PURE__ */ new Set();
   repositoryInitializations = /* @__PURE__ */ new Map();
   outerRepository;
   pending = 0;
@@ -1895,19 +1896,59 @@ class WorkspaceAuthority {
     return this.action(async () => {
       const { b, route } = await this.runRoute(identity, run);
       const result = await route.client.poll({ ...run, fence: route.workerFence }, stdoutOffset, stderrOffset, maxBytes);
-      await this.serial(
-        b,
-        async () => {
-          b.state.runs[run.operationId].state = result.receipt.state;
-          b.state.runs[run.operationId].updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-          if (["completed", "cancelled"].includes(result.receipt.state)) b.state.runs[run.operationId].completedAt ??= (/* @__PURE__ */ new Date()).toISOString();
-          await this.save(b);
-        },
-        true
-      );
+      await this.recordRunState(b, run.operationId, result.receipt.state);
       return result;
     });
   }
+  /** Run liveness is process state observed from the executor, not a workspace
+   * mutation: it is recorded on its own short queue, never behind the checkout's
+   * hydration, commit or publication work. A crash between two writers loses
+   * nothing lasting — `refresh` re-reads every open run from the executor. */
+  recordRunState(b, operationId, state) {
+    return this.serialKey(
+      `runs:${b.config.id}`,
+      async () => {
+        const run = b.state.runs[operationId];
+        if (!run) return;
+        run.state = state;
+        run.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+        if (["completed", "cancelled"].includes(state)) run.completedAt ??= (/* @__PURE__ */ new Date()).toISOString();
+        await this.save(b);
+      },
+      true
+    );
+  }
+  /** Live terminal channel. The subscription is not an admitted action: it
+   * lives as long as its transport, outlives the request budget, and is torn
+   * down on close. Its exit frame is the only durable-state effect. */
+  async subscribe(identity, run, offset, handlers) {
+    if (this.closing) throw new WorkspaceError("authority_closed", "Workspace authority is closing");
+    const { b, route } = await this.runRoute(identity, run);
+    if (!route.client.subscribe) throw new WorkspaceError("stream_unavailable", "Executor does not advertise terminal streaming", true);
+    const holder = {};
+    holder.subscription = await route.client.subscribe({ ...run, fence: route.workerFence }, offset, {
+      frame: (frame) => {
+        if (frame.event === "exit") void this.recordRunState(b, run.operationId, frame.receipt.state).catch(() => {
+        });
+        handlers.frame(frame);
+      },
+      close: (error) => {
+        if (holder.subscription) this.subscriptions.delete(holder.subscription);
+        handlers.close(error);
+      }
+    });
+    this.subscriptions.add(holder.subscription);
+    return holder.subscription;
+  }
+  /** Live PTY input: fenced and owned like a write, but with no action receipt
+   * and no queue in front of it. */
+  async streamInput(identity, run, data, resize) {
+    return this.action(async () => {
+      const { route } = await this.runRoute(identity, run);
+      if (!route.client.input) throw new WorkspaceError("stream_unavailable", "Executor does not advertise terminal streaming", true);
+      return route.client.input({ ...run, fence: route.workerFence }, data, resize);
+    });
+  }
   async actionOutcome(b, actionId, invoke) {
     try {
       const result = await invoke();
@@ -1963,6 +2004,7 @@ class WorkspaceAuthority {
     return task;
   }
   async finishClose() {
+    for (const subscription of this.subscriptions) subscription.close();
     await Promise.allSettled([...this.actions]);
     await Promise.allSettled([...this.queues.values()]);
     for (const b of this.benches.values()) await this.refresh(b);

package/dist/types/personal/runtime.d.ts

@@ -38,6 +38,19 @@ export declare const PersonalWorkerGrant: z.ZodObject<{
     }, z.core.$strict>;
     leaseExpiresAt: z.ZodCoercedNumber<unknown>;
 }, z.core.$loose>;
+declare const Workbench: z.ZodObject<{
+    id: z.ZodString;
+    repositoryId: z.ZodString;
+    branch: z.ZodString;
+    sessionId: z.ZodString;
+    rootProfile: z.ZodDefault<z.ZodEnum<{
+        account: "account";
+        project: "project";
+    }>>;
+    namespace: z.ZodOptional<z.ZodString>;
+    projectName: z.ZodOptional<z.ZodString>;
+    baseCommitHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const PersonalWorkspaceRequest: z.ZodObject<{
     protocol: z.ZodLiteral<1>;
     userId: z.ZodString;
@@ -151,5 +164,21 @@ export declare function openPersonalWorkerRuntime(options: {
         unchanged?: boolean;
         error?: string;
     }[]>;
+    subscribeTerminal: (input: {
+        sessionId: string;
+        workbench: z.infer<typeof Workbench>;
+        operationId: string;
+        offset: number;
+    }, handlers: Parameters<WorkspaceAuthority["subscribe"]>[3]) => Promise<import("../runtime/client").ExecutorSubscription>;
+    terminalInput: (input: {
+        sessionId: string;
+        operationId: string;
+        data?: string;
+        resize?: {
+            cols: number;
+            rows: number;
+        };
+    }) => Promise<import("../runtime/protocol").InputResult>;
     close(): Promise<void>;
 }>;
+export {};

package/dist/types/personal/terminal-stream-protocol.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/** Live terminal channel between a personal worker and the web runtime, and
+ * between the web runtime and a browser. Frames are JSON text messages.
+ *
+ * Nothing on this channel is durable: a lost frame is retyped by the person
+ * at the keyboard or re-read from the durable offset by the browser. That is
+ * what keeps a keystroke off the relay ledger and out of every workspace queue. */
+export declare const TERMINAL_STREAM_CAPABILITY = "terminal-stream-v1";
+export declare const STREAM_INPUT_MAX_CHARS = 100000;
+export declare const STREAM_HEARTBEAT_MS = 25000;
+export declare const StreamWorkbench: z.ZodObject<{
+    id: z.ZodString;
+    repositoryId: z.ZodString;
+    branch: z.ZodString;
+    sessionId: z.ZodString;
+    rootProfile: z.ZodDefault<z.ZodEnum<{
+        account: "account";
+        project: "project";
+    }>>;
+    namespace: z.ZodOptional<z.ZodString>;
+    projectName: z.ZodOptional<z.ZodString>;
+    baseCommitHash: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type StreamWorkbench = z.output<typeof StreamWorkbench>;
+/** Web runtime → worker. */
+export declare const ServerToWorkerFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"attach">;
+    streamId: z.ZodString;
+    sessionId: z.ZodString;
+    operationId: z.ZodString;
+    offset: z.ZodNumber;
+    workbench: z.ZodObject<{
+        id: z.ZodString;
+        repositoryId: z.ZodString;
+        branch: z.ZodString;
+        sessionId: z.ZodString;
+        rootProfile: z.ZodDefault<z.ZodEnum<{
+            account: "account";
+            project: "project";
+        }>>;
+        namespace: z.ZodOptional<z.ZodString>;
+        projectName: z.ZodOptional<z.ZodString>;
+        baseCommitHash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"input">;
+    streamId: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    resize: z.ZodOptional<z.ZodObject<{
+        cols: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"detach">;
+    streamId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+}, z.core.$strict>], "type">;
+export type ServerToWorkerFrame = z.infer<typeof ServerToWorkerFrame>;
+/** Worker → web runtime. */
+export declare const WorkerToServerFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"hello">;
+    version: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"attached">;
+    streamId: z.ZodString;
+    offset: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"output">;
+    streamId: z.ZodString;
+    offset: z.ZodNumber;
+    base64: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"exit">;
+    streamId: z.ZodString;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    signal: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    streamId: z.ZodString;
+    code: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"detached">;
+    streamId: z.ZodString;
+    code: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+}, z.core.$strict>], "type">;
+export type WorkerToServerFrame = z.infer<typeof WorkerToServerFrame>;
+/** Browser → web runtime. The PTY, its offset and the worker are fixed by the
+ * socket's URL, so the browser only ever sends what a keyboard produces. */
+export declare const BrowserToServerFrame: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"input">;
+    data: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"resize">;
+    cols: z.ZodNumber;
+    rows: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"pong">;
+}, z.core.$strict>], "type">;
+export type BrowserToServerFrame = z.infer<typeof BrowserToServerFrame>;
+/** Web runtime → browser. `offset` is the durable stdout offset after the
+ * frame's bytes, the same number the polling transport calls its cursor. */
+export type ServerToBrowserFrame = {
+    type: "attached";
+    offset: number;
+} | {
+    type: "output";
+    offset: number;
+    base64: string;
+} | {
+    type: "exit";
+    exitCode: number | null;
+    signal: string | null;
+} | {
+    type: "error";
+    code: string;
+} | {
+    type: "unavailable";
+    reason?: string;
+} | {
+    type: "ping";
+} | {
+    type: "pong";
+};
+/** Number of leading bytes that end on a UTF-8 sequence boundary. A split
+ * suffix is carried into the next frame so offsets never cut a character. */
+export declare function completeUtf8Prefix(bytes: Uint8Array): number;

package/dist/types/personal/terminal-stream.d.ts

@@ -0,0 +1,31 @@
+import type { PersonalWorkerRuntime } from "./runtime";
+/** The subset of a WebSocket this client drives; Bun's global client fits it
+ * and tests substitute a scripted one. */
+export type StreamSocket = {
+    onopen: ((event?: unknown) => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onclose: ((event?: unknown) => void) | null;
+    onerror: ((event?: unknown) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+};
+export type TerminalStreamRuntime = Pick<PersonalWorkerRuntime, "subscribeTerminal" | "terminalInput">;
+export type TerminalStreamOptions = {
+    /** ws(s) URL of this worker's stream endpoint, instance included. */
+    url: string;
+    credential: string;
+    version: string;
+    runtime: TerminalStreamRuntime;
+    connect?: (url: string, headers: Record<string, string>) => StreamSocket;
+    log?: (line: string) => void;
+    /** Reconnect delays; the last one repeats. */
+    backoffMs?: number[];
+};
+/** One long-lived socket per worker carries every attached shell. The socket
+ * is the transport only: PTYs, their receipts and their bytes stay in the
+ * executor, so a reconnect re-attaches at the browser's durable offset. */
+export declare function startTerminalStream(options: TerminalStreamOptions): {
+    close(): Promise<void>;
+};

package/dist/types/runtime/client.d.ts

@@ -1,9 +1,21 @@
 import type { OperationEnvelope, OwnershipFence } from "@ricsam/r5d-api/runtime-protocol";
-import { AdapterConfig, type ActionReceipt, type AdapterGrant, type AdapterRegistration, type ExecutorCommand, type PollResult, type RunIdentity, type RunReceipt } from "./protocol";
+import { AdapterConfig, ExecutorError, type ActionReceipt, type AdapterGrant, type AdapterRegistration, type ExecutorCommand, type InputResult, type PollResult, type RunIdentity, type RunReceipt, type StreamFrame, type SubscribeResult } from "./protocol";
+export type ExecutorSubscription = SubscribeResult & {
+    close(): void;
+};
+export type ExecutorStreamHandlers = {
+    frame(frame: StreamFrame): void;
+    /** Called once, after the last frame, with the transport's failure if any. */
+    close(error?: ExecutorError): void;
+};
 /** Stateless one-request connections: disconnect/timeout never implies the operation did not happen. */
 export declare class HostExecutorClient {
     readonly config: ReturnType<typeof AdapterConfig.parse>;
     constructor(config: AdapterConfig);
+    private frame;
+    /** Keeps its socket open: the admission reply resolves the promise, then every
+     * newline-delimited frame reaches `handlers.frame` until either side closes. */
+    subscribe(run: RunIdentity, offset: number, handlers: ExecutorStreamHandlers): Promise<ExecutorSubscription>;
     request<T = unknown>(command: ExecutorCommand): Promise<T>;
     status(): Promise<unknown>;
     registerAdapter(grant: AdapterGrant): Promise<AdapterRegistration>;
@@ -14,4 +26,9 @@ export declare class HostExecutorClient {
     write(run: RunIdentity, actionId: string, data: string, eof?: boolean): Promise<ActionReceipt>;
     resize(run: RunIdentity, actionId: string, cols: number, rows: number): Promise<ActionReceipt>;
     cancel(run: RunIdentity, actionId: string): Promise<ActionReceipt>;
+    /** Live PTY input without a durable action: nothing to replay, nothing to poison. */
+    input(run: RunIdentity, data?: string, resize?: {
+        cols: number;
+        rows: number;
+    }): Promise<InputResult>;
 }

package/dist/types/runtime/executor.d.ts

@@ -1,5 +1,5 @@
 import { type RuntimeHello } from "@ricsam/r5d-api/runtime-protocol";
-import { ExecutorConfig, type ResolvedConfig } from "./protocol";
+import { ExecutorConfig, type ResolvedConfig, type StreamSink } from "./protocol";
 import { ExecutorStore } from "./storage";
 type PtyModule = typeof import("node-pty");
 export declare const tokenHash: (token: string) => string;
@@ -11,6 +11,7 @@ export declare class HostExecutor {
     private readonly adapters;
     readonly hello: RuntimeHello;
     private readonly active;
+    private readonly subscribers;
     private readonly leaseTimer;
     private closing;
     private poisoned;
@@ -19,8 +20,14 @@ export declare class HostExecutor {
     /** Authority is synchronous and authenticated; never queue lease renewal behind a blocked OS write.
      * Resource commands retain one ordered admission/action boundary. Commands already admitted may
      * complete after promotion; queued commands and yielded admission hashes must recheck the fence.
+     * The live terminal channel (subscribe, input) carries no durable action and
+     * never waits behind that boundary: a keystroke is not queued behind a spawn.
      */
-    handle(input: unknown): Promise<unknown>;
+    handle(input: unknown, sink?: StreamSink): Promise<unknown>;
+    /** Drops a subscription whose transport closed. Idempotent. */
+    unsubscribe(sink: StreamSink): void;
+    private notify;
+    private pump;
     private authenticate;
     private authority;
     private workerFence;

package/dist/types/runtime/protocol.d.ts

@@ -1,5 +1,10 @@
 import { z } from "zod";
 export declare const EXECUTOR_CAPABILITY = "host-executor-v1";
+/** Live terminal channel: a kept-open subscription socket plus fenced,
+ * receipt-free input. Advertised by executors that stream. */
+export declare const EXECUTOR_STREAM_CAPABILITY = "host-stream-v1";
+/** Longest single output frame on a subscription socket. */
+export declare const STREAM_CHUNK_BYTES: number;
 export declare const MAX_FRAME_BYTES: number;
 export declare const Lane: z.ZodEnum<{
     general: "general";
@@ -248,6 +253,40 @@ export declare const ExecutorCommand: z.ZodDiscriminatedUnion<[z.ZodObject<{
         }, z.core.$strict>;
     }, z.core.$strict>;
     actionId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"subscribe">;
+    run: z.ZodObject<{
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    method: z.ZodLiteral<"input">;
+    run: z.ZodObject<{
+        operationId: z.ZodString;
+        userId: z.ZodString;
+        sessionId: z.ZodOptional<z.ZodString>;
+        fence: z.ZodObject<{
+            installationId: z.ZodString;
+            resourceType: z.ZodString;
+            resourceId: z.ZodString;
+            ownerId: z.ZodString;
+            epoch: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    data: z.ZodOptional<z.ZodString>;
+    resize: z.ZodOptional<z.ZodObject<{
+        cols: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>], "method">;
 export type ExecutorCommand = z.input<typeof ExecutorCommand>;
 export declare const ExecutorRequest: z.ZodObject<{
@@ -419,6 +458,40 @@ export declare const ExecutorRequest: z.ZodObject<{
             }, z.core.$strict>;
         }, z.core.$strict>;
         actionId: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"subscribe">;
+        run: z.ZodObject<{
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        offset: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        method: z.ZodLiteral<"input">;
+        run: z.ZodObject<{
+            operationId: z.ZodString;
+            userId: z.ZodString;
+            sessionId: z.ZodOptional<z.ZodString>;
+            fence: z.ZodObject<{
+                installationId: z.ZodString;
+                resourceType: z.ZodString;
+                resourceId: z.ZodString;
+                ownerId: z.ZodString;
+                epoch: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        data: z.ZodOptional<z.ZodString>;
+        resize: z.ZodOptional<z.ZodObject<{
+            cols: z.ZodNumber;
+            rows: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>], "method">;
 }, z.core.$strict>;
 export declare const ExecutorCredential: z.ZodObject<{
@@ -521,6 +594,31 @@ export type ActionReceipt = {
     actionId: string;
     state: "accepted" | "completed" | "unknown";
 };
+/** Frames written after a subscription's admission reply, one per line. `offset`
+ * is the durable stdout offset after the frame's bytes. */
+export type StreamFrame = {
+    event: "output";
+    offset: number;
+    base64: string;
+} | {
+    event: "exit";
+    receipt: RunReceipt;
+};
+export type SubscribeResult = {
+    receipt: RunReceipt;
+    offset: number;
+};
+export type InputResult = {
+    ok: true;
+};
+/** Transport a subscription pushes into; the daemon binds it to one socket. */
+export type StreamSink = {
+    /** Resolves once the admission reply has been written; frames wait for it. */
+    ready: Promise<void>;
+    /** Resolves once the frame is flushed to the transport (backpressure). */
+    send(frame: StreamFrame): Promise<void>;
+    end(): void;
+};
 export type PollResult = {
     receipt: RunReceipt;
     stdout: {