Gateway

/** @jsxImportSource smthrs */
import { Gateway, Task, Workflow, createSmithers } from "smthrs";
import { z } from "zod";

const { smithers, outputs } = createSmithers({
  result: z.object({ ok: z.boolean() }),
});

const deploy = smithers((ctx) => (
  <Workflow name="deploy">
    <Task id="ship" output={outputs.result}>{{ ok: true }}</Task>
  </Workflow>
));

const gateway = new Gateway({
  heartbeatMs: 15_000,
  auth: {
    mode: "token",
    tokens: { "operator-token": { role: "operator", scopes: ["*"] } },
  },
});

gateway.register("deploy", deploy, { schedule: "0 8 * * 1-5" });
await gateway.listen({ port: 7331 });

const ws = new WebSocket("ws://localhost:7331");
ws.onmessage = (m) => console.log(JSON.parse(m.data));
ws.onopen = () => ws.send(JSON.stringify({
  type: "req",
  id: "c1",
  method: "connect",
  params: {
    minProtocol: 1,
    maxProtocol: 1,
    client: { id: "docs-example", version: "1.0.0", platform: "browser" },
    auth: { token: "operator-token" },
  },
}));

import { SmithersGatewayClient } from "smthrs/gateway-client";

const gateway = new SmithersGatewayClient();
const workflows = await gateway.listWorkflows();

// Resilient pushed updates: backoff + jitter on reconnect, resume from the last
// observed seq via run.gap_resync, stop on run.completed or abort.
for await (const frame of gateway.streamRunEventsResilient({ runId: "run-1" })) {
  if (frame.event === "run.completed") break;
}

import { SmithersGatewayClient } from "smthrs/gateway-client";

const statusProcess = Bun.spawnSync([
  "bunx", "smthrs", "gateway", "status", "--format", "json",
], {
  cwd: process.cwd(),
  stdout: "pipe",
  stderr: "pipe",
});

if (!statusProcess.success) {
  throw new Error(new TextDecoder().decode(statusProcess.stderr));
}

const status = JSON.parse(new TextDecoder().decode(statusProcess.stdout));
if (!status.running || typeof status.url !== "string") {
  throw new Error("No healthy workspace Gateway is running");
}

const gateway = new SmithersGatewayClient({
  baseUrl: status.url,
  token: process.env.SMITHERS_API_KEY,
  client: { id: "local-health-cron", platform: "bun" },
});

const runs = await gateway.listRuns({ filter: { limit: 50 } });

api[24]{route,rpc,scope}:
  GET /v1/api/runs,listRuns,run:read
  GET /v1/api/runs/:id,getRun,run:read
  POST /v1/api/runs,launchRun,run:write
  POST /v1/api/runs/:id/resume,resumeRun,run:write
  POST /v1/api/runs/:id/cancel,cancelRun,run:write
  POST /v1/api/runs/:id/rewind,rewindRun,run:admin
  GET /v1/api/runs/:id/tree,getDevToolsSnapshot,observability:read
  GET /v1/api/events,streamRunEvents tail snapshot,run:read
  GET /v1/api/nodes/:runId/:nodeId/output,getNodeOutput,run:read
  GET /v1/api/nodes/:runId/:nodeId/diff,getNodeDiff,run:read
  GET /v1/api/approvals,listApprovals,run:read
  POST /v1/api/approvals/:id,submitApproval,approval:submit
  POST /v1/api/signals,submitSignal,signal:submit
  GET /v1/api/workflows,listWorkflows,run:read
  GET /v1/api/docs,listDocs,run:read
  GET /v1/api/prompts,listPrompts,prompt:read
  GET /v1/api/scores,listScores,score:read
  GET /v1/api/tickets,listTickets,ticket:read
  GET /v1/api/memory-facts,listMemoryFacts,memory:read
  GET /v1/api/crons,cronList,cron:read
  GET /v1/api/accounts,listAccounts,account:read
  GET /v1/api/schema-signature,getSchemaSignature,run:read
  GET /v1/api/stream,SSE invalidation feed,run:read

rpc[41]{method,params,returns,scope,transport}:
  launchRun,workflow/input?/options.runId?/options.idempotencyKey?,{runId/workflow},run:write,http+websocket
  resumeRun,runId/options.force?,{runId/status},run:write,http+websocket
  cancelRun,runId,{runId/won/status/terminalStatus?/repaired/cancellationSource?/cancelledAttempts?/descendants?/terminatedOwners?/terminatedAgents?},run:write,http+websocket
  pauseRun,runId,{runId/status:pausing},run:write,http+websocket
  hijackRun,runId/options?,{runId/status:hijack-ready/sessionId},run:admin,http+websocket
  rewindRun,runId/frameNo/confirm:true,JumpResult,run:admin,http+websocket
  submitApproval,runId/nodeId/iteration?/decision,{runId/nodeId/iteration/approved},approval:submit,http+websocket
  submitSignal,runId/correlationKey/payload?/signalName?,Delivery metadata,signal:submit,http+websocket
  getRun,runId,Run record + optional runState,run:read,http+websocket
  listRuns,filter.status?/filter.limit?/filter.offset?/filter.workflow?,Run summaries,run:read,http+websocket
  getSchemaSignature,,{schemaVersion/signature/components},run:read,http+websocket
  listWorkflows,filter.hasUi?,Workflow summaries,run:read,http+websocket
  listApprovals,filter.runId?/filter.workflow?/filter.limit?,Pending approvals,run:read,http+websocket
  listDocs,filter.kind?/filter.includeDeleted?/filter.updatedAfterMs?/filter.limit?,GatewayDocRow[],run:read,http+websocket
  streamRunEvents,runId/afterSeq?,{streamId/runId/afterSeq/currentSeq},run:read,websocket
  streamDevTools,runId/afterSeq?/fromSeq?,{streamId/runId/fromSeq/afterSeq} + devtools.event frames,observability:read,websocket
  getDevToolsSnapshot,runId/frameNo?,DevTools snapshot payload,observability:read,http+websocket
  getNodeOutput,runId/nodeId/iteration?,NodeOutputResponse,run:read,http+websocket
  getNodeDiff,runId/nodeId/iteration?,Node diff response,run:read,http+websocket
  getRunDiff,runId,DiffBundle or oversized marker,run:read,http+websocket
  whatHappened,runId/nodeId?/iteration?,Narrated recap payload,run:read,http+websocket
  cronList,filter.workflow?,Cron rows,cron:read,http+websocket
  cronCreate,workflow/pattern/cronId?/enabled?,Created cron row,cron:write,http+websocket
  cronDelete,cronId,{cronId/removed},cron:write,http+websocket
  cronRun,cronId? or workflow/input?,{runId/workflow},cron:write,http+websocket
  listAccounts,,Registered agent accounts (api keys redacted),account:read,http+websocket
  listMemoryFacts,namespace?,Memory facts,memory:read,http+websocket
  listPrompts,,Prompt[],prompt:read,http+websocket
  listScores,runId/nodeId?,Scorer results,score:read,http+websocket
  listScoresForRuns,runIds/nodeId?/scorerId?/scorerName?/source?/order?/offset?/limit?,Scorer results across runs,score:read,http+websocket
  getScoreDetail,runId/scoreId,Score detail,score:read,http+websocket
  listTickets,kind?,Work docs,ticket:read,http+websocket
  createTicket,path/content/kind?/status?,Created doc row,ticket:write,http+websocket
  updateTicket,path/content?/status?,Updated doc row,ticket:write,http+websocket
  deleteTicket,path,{path/deleted},ticket:write,http+websocket
  createBrowserSession,source:url or dev-server/viewport?,BrowserSnapshot,run:write,http+websocket
  browserAct,sessionId/actionId/expectedRevision?/action,Browser action outcome,run:write,http+websocket
  browserContext,sessionId/sinceRevision?/include?,Bounded perception slices,run:read,http+websocket
  browserPick,sessionId/point{x/y},Locator metadata + inline JPEG,run:read,http+websocket
  closeBrowserSession,sessionId,{closed/sessionId},run:write,http+websocket
  listBrowserSessions,,Live BrowserSnapshot[],run:read,http+websocket

scopes[14]{scope,allows}:
  run:read,Read run state/lists/event streams/node output/node diffs
  run:write,Launch/resume/cancel runs; implies run:read
  run:admin,Hijack or rewind runs; implies run:write and run:read
  approval:submit,Submit approval decisions
  signal:submit,Submit workflow signals
  cron:read,List cron schedules
  cron:write,Create/delete/trigger cron schedules; implies cron:read
  account:read,List registered agent accounts (api keys redacted)
  memory:read,List cross-run memory facts
  prompt:read,List workspace prompts
  score:read,List scorer/eval results for a run
  ticket:read,List work docs (tickets/plans/specs/proposals)
  ticket:write,Create/update/soft-delete work docs; implies ticket:read
  observability:read,Read DevTools and other observability streams

type RewindRunRequest = {
  runId: string;     // /^[a-z0-9_-][a-z0-9_.-]{0,63}$/
  frameNo: number;   // 0 <= frameNo <= latestFrameNo
  confirm: true;     // must be literal true
};

type JumpResult = {
  ok: true;
  newFrameNo: number;
  revertedSandboxes: number;
  deletedFrames: number;
  deletedAttempts: number;
  invalidatedDiffs: number;
  durationMs: number;
};

type NodeOutputResponse = {
  status: "produced" | "pending" | "failed";
  row: Record<string, unknown> | null;
  schema: OutputSchemaDescriptor | null;
  partial?: Record<string, unknown> | null; // only when status === "failed"
};

type OutputSchemaDescriptor = {
  fields: Array<{
    name: string;
    type: "string" | "number" | "boolean" | "object" | "array" | "null" | "unknown";
    optional: boolean;
    nullable: boolean;
    description?: string;
    enum?: readonly unknown[];
  }>;
};

errors[28]{code,http}:
  InvalidRequest,400
  InvalidInput,400
  Unauthorized,401
  Forbidden,403
  RunNotFound,404
  ScoreNotFound,404
  RUN_NOT_ACTIVE,409
  CONFLICT,409
  CronNotFound,404
  TicketNotFound,404
  NodeNotFound,404
  IterationNotFound,404
  NodeHasNoOutput,404
  FrameOutOfRange,400
  SeqOutOfRange,400
  Busy,409
  AlreadyDecided,409
  RateLimited,429
  PayloadTooLarge,413
  BackpressureDisconnect,429
  UnsupportedSandbox,501
  VcsError,500
  RewindFailed,500
  TIME_TRAVEL_SIDE_EFFECT_BLOCKED,409
  Internal,500
  REVISION_CONFLICT,409
  SSRF_BLOCKED,400
  QUOTA_EXCEEDED,429

legacyErrors[12]{code,meaning,http}:
  INVALID_REQUEST,Invalid request,400
  INVALID_INPUT,Invalid input,400
  INVALID_FRAME,Invalid frame,400
  PROTOCOL_UNSUPPORTED,Unsupported protocol,400
  UNAUTHORIZED,Unauthorized,401
  FORBIDDEN,Forbidden,403
  NOT_FOUND,Not found,404
  METHOD_NOT_FOUND,Unknown method,404
  PAYLOAD_TOO_LARGE,Payload too large,413
  InvalidRunId,Invalid run id,400
  InvalidFrameNo,Invalid frame number,400
  ConfirmationRequired,Confirmation required,400

type DevToolsSnapshot = {
  version: 1;
  runId: string;
  frameNo: number;   // latest frame reflected in this tree
  seq: number;       // monotonic sequence id (equals frameNo today)
  root: DevToolsNode;
};

type DevToolsNode = {
  id: number;        // stable across frames for the same logical node
  type: "workflow" | "task" | "sequence" | "parallel" | /* …see protocol */;
  name: string;
  props: Record<string, unknown>;
  task?: { nodeId: string; kind: "agent" | "compute" | "static"; prompt?: string /* the task's initial prompt; absent for queued nodes */ };
  children: DevToolsNode[];
  depth: number;
};

type DevToolsDelta = {
  version: 1;
  baseSeq: number;   // must match the subscriber's current seq
  seq: number;       // new seq after applying ops, in order
  ops: Array<
    | { op: "addNode"; parentId: number; index: number; node: DevToolsNode }
    | { op: "removeNode"; id: number }
    | { op: "updateProps"; id: number; props: Record<string, unknown> }
    | { op: "updateTask"; id: number; task: DevToolsNode["task"] }
    | { op: "replaceRoot"; node: DevToolsNode } // emitted when the root's
                                                // identity or shape changes;
                                                // `removeNode` of the root is
                                                // never emitted.
  >;
};

type DevToolsEvent =
  | { version: 1; kind: "snapshot"; snapshot: DevToolsSnapshot }
  | { version: 1; kind: "delta"; delta: DevToolsDelta };

GET /v1/auth/session?token=<bearer>&next=<path>

bunx smthrs gateway --host 0.0.0.0 --mint-token
# or let the UI command autostart it:
bunx smthrs monitor --host 0.0.0.0

type GatewayOptions = {
  protocol?: number;                 // default 1
  features?: string[];               // default ["streaming", "runs"]
  heartbeatMs?: number;              // default 15_000
  auth?: GatewayAuthConfig;
  workspaceRoot?: string;            // anchors disk-backed reads and the advertised identity
  workflowRegistryStatus?: () => {   // additive readiness fields on health
    workflowsLoaded?: number;
    workflowsTotal?: number;
  };
  identity?: {                       // advertised on GET /health, the health RPC, and the WS hello
    backend?: string;                // sqlite | pglite | postgres
    version?: string;                // serving package version
  };
  ui?: GatewayUiConfig;              // custom gateway UI; true mounts the built-in console
  operatorUi?: GatewayOperatorUiConfig | false; // default { path: "/console" }; false disables
  defaults?: {
    cliAgentTools?: "all" | "explicit-only";
    outOfProcessEventBridge?: boolean;
    outOfProcessEventBridgePollMs?: number;
  };
  maxBodyBytes?: number;             // default 1_048_576 for POST /rpc
  maxPayload?: number;               // default 1_048_576 for WebSocket frames
  maxConnections?: number;           // default 1_000
  eventWindowSize?: number;          // default 10_000 per-run replay frames
  outOfProcessEventBridge?: boolean; // default true; streams persisted events from detached runs
  outOfProcessEventBridgePollMs?: number; // default 1_000
  headersTimeout?: number;           // default 30_000
  requestTimeout?: number;           // default 60_000
};

type GatewayOperatorUiConfig = {
  path?: string;                      // default "/console"
  title?: string;
  props?: Record<string, unknown>;
};

type GatewayUiConfig =
  | true
  | {
      entry: string;
      path?: string;                  // gateway default "/"; workflow default "/workflows/<workflowKey>"
      title?: string;
      props?: Record<string, unknown>;
    };

type GatewayTokenGrant = {
  role: string;
  scopes: string[];
  userId?: string;
  appId?: string;
  tokenId?: string;
  issuedAtMs?: number;
  expiresAtMs?: number;
  revokedAtMs?: number;
};

type GatewayAuthConfig =
  | {
      mode: "token";
      tokens: Record<string, GatewayTokenGrant>;
      allowedOrigins?: string[];     // default [] (no Origin allowlist)
    }
  | {
      mode: "jwt";
      issuer: string;
      audience: string | string[];
      secret: string;                // HS256
      scopesClaim?: string;          // default "scope"
      roleClaim?: string;            // default "role"
      userClaim?: string;            // default "sub"
      appClaim?: string;             // default "app"
      defaultRole?: string;          // default "operator"
      defaultScopes?: string[];      // default [] when scope claim is absent
      clockSkewSeconds?: number;     // default 60; negative values clamp to 0
      allowedOrigins?: string[];     // default [] (no Origin allowlist)
    }
  | {
      mode: "trusted-proxy";
      trustedProxies: string[];      // REQUIRED: peer IPs / CIDR blocks, or "unix"
      allowedOrigins?: string[];     // default [] (no Origin allowlist)
      trustedHeaders?: string[];     // default ["x-user-id","x-user-scopes","x-user-role"]
      defaultRole?: string;          // default "operator"
      defaultScopes?: string[];      // trusted-proxy: used when the scopes header is absent, else the request is rejected
    };

const gateway = new Gateway({
  auth: {
    mode: "trusted-proxy",
    trustedProxies: ["10.4.0.0/24"],   // the proxy subnet that fronts this Gateway
    defaultScopes: ["run:read"],
  },
});
await gateway.listen({ host: "10.4.0.20", port: 7331 });