@rigkit/sdk 0.1.8

package/src/runtime/app.ts

@@ -0,0 +1,63 @@
+import { RIGKIT_ENGINE_VERSION } from "@rigkit/engine";
+import { RIGKIT_RUNTIME_VERSION } from "./version.ts";
+import { createRuntimeControlApiHandler } from "./api-handlers.ts";
+import {
+  RUNTIME_API_VERSION,
+  RUNTIME_PROTOCOL_HASH,
+} from "./protocol.ts";
+import { type RunStore } from "./runs.ts";
+import type { RuntimeContext } from "./types.ts";
+
+export type { RuntimeAppState } from "./control.ts";
+
+export type RuntimeApp = {
+  fetch(request: Request): Promise<Response>;
+  request(path: string, init?: RequestInit): Promise<Response>;
+};
+
+export function createRuntimeApp(context: RuntimeContext, store: RunStore): RuntimeApp {
+  const controlApi = createRuntimeControlApiHandler(context, store);
+
+  return {
+    async fetch(request) {
+      return controlApi.handler(request);
+    },
+
+    async request(path, init) {
+      const url = path.startsWith("http://") || path.startsWith("https://")
+        ? path
+        : `http://runtime.local${path.startsWith("/") ? path : `/${path}`}`;
+      return await this.fetch(new Request(url, init)) ?? runtimeJsonError(500, "Request did not produce a response");
+    },
+  };
+}
+
+export function sessionRunIdFor(pathname: string): string | undefined {
+  const match = /^\/runs\/([^/]+)\/session$/.exec(pathname);
+  return match?.[1] ? decodeURIComponent(match[1]) : undefined;
+}
+
+export function runtimeJsonError(status: number, message: string): Response {
+  return withRuntimeHeaders(Response.json({ error: { message } }, { status }));
+}
+
+export function withRuntimeHeaders(response: Response): Response {
+  const headers = new Headers(response.headers);
+  for (const [key, value] of Object.entries(runtimeHeaders())) {
+    headers.set(key, value);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+export function runtimeHeaders() {
+  return {
+    "x-rigkit-api-version": String(RUNTIME_API_VERSION),
+    "x-rigkit-protocol-hash": RUNTIME_PROTOCOL_HASH,
+    "x-rigkit-engine-version": RIGKIT_ENGINE_VERSION,
+    "x-rigkit-runtime-version": RIGKIT_RUNTIME_VERSION,
+  };
+}

package/src/runtime/cli.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+import { resolve } from "node:path";
+import { serveRuntime } from "./server.ts";
+
+type ServeArgs = {
+  projectId?: string;
+  projectDir?: string;
+  configPath?: string;
+  statePath?: string;
+  sourceJson?: string;
+  handlePath?: string;
+  tokenPath?: string;
+  host?: string;
+  port?: number;
+  idleMs?: number;
+};
+
+const [command, ...args] = process.argv.slice(2);
+
+if (command !== "serve") {
+  console.error(`Usage: rigkit-runtime serve --project-id <id> --project-dir <dir> --config <file> --handle <file> --token <file>`);
+  process.exit(1);
+}
+
+const options = parseServeArgs(args);
+const missing = [
+  ["--project-id", options.projectId],
+  ["--project-dir", options.projectDir],
+  ["--config", options.configPath],
+  ["--handle", options.handlePath],
+  ["--token", options.tokenPath],
+].filter(([, value]) => !value);
+if (missing.length > 0) {
+  console.error(`Missing required runtime args: ${missing.map(([name]) => name).join(", ")}`);
+  process.exit(1);
+}
+
+const runtime = await serveRuntime({
+  projectId: options.projectId!,
+  projectDir: resolve(options.projectDir!),
+  configPath: resolve(options.configPath!),
+  statePath: options.statePath ? resolve(options.statePath) : undefined,
+  source: options.sourceJson ? JSON.parse(options.sourceJson) : undefined,
+  handlePath: resolve(options.handlePath!),
+  tokenPath: resolve(options.tokenPath!),
+  host: options.host,
+  port: options.port,
+  idleMs: options.idleMs,
+});
+
+console.log(JSON.stringify({
+  type: "ready",
+  url: runtime.url,
+  token: runtime.token,
+}));
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => {
+    runtime.stop();
+    process.exit(0);
+  });
+}
+
+await new Promise(() => {});
+
+function parseServeArgs(args: string[]): ServeArgs {
+  const parsed: ServeArgs = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index]!;
+    const next = args[index + 1];
+    const readValue = () => {
+      if (!next) throw new Error(`${arg} requires a value`);
+      index += 1;
+      return next;
+    };
+
+    switch (arg) {
+      case "--project-id":
+        parsed.projectId = readValue();
+        break;
+      case "--project-dir":
+      case "--project":
+        parsed.projectDir = readValue();
+        break;
+      case "--config":
+        parsed.configPath = readValue();
+        break;
+      case "--state":
+      case "--state-path":
+        parsed.statePath = readValue();
+        break;
+      case "--source-json":
+        parsed.sourceJson = readValue();
+        break;
+      case "--handle":
+        parsed.handlePath = readValue();
+        break;
+      case "--token":
+        parsed.tokenPath = readValue();
+        break;
+      case "--host":
+        parsed.host = readValue();
+        break;
+      case "--port":
+        parsed.port = Number(readValue());
+        break;
+      case "--idle-ms":
+        parsed.idleMs = Number(readValue());
+        break;
+      default:
+        throw new Error(`Unknown runtime arg ${arg}`);
+    }
+  }
+  return parsed;
+}

package/src/runtime/control.ts

@@ -0,0 +1,163 @@
+import { RIGKIT_ENGINE_VERSION, type WorkspaceRecord } from "@rigkit/engine";
+import { RIGKIT_RUNTIME_VERSION } from "./version.ts";
+import { RuntimeHostRequestError } from "./errors.ts";
+import { loadEngine, operationManifestFor, runOperation } from "./operations.ts";
+import {
+  RUNTIME_API_VERSION,
+  RUNTIME_PROTOCOL_HASH,
+  RuntimeProtocolSchemaError,
+  type HostResponse,
+  type RunOperationRequest,
+  type RuntimeOperation,
+} from "./protocol.ts";
+import {
+  createRun,
+  summarizeRun,
+  sseResponse,
+  type RunStore,
+} from "./runs.ts";
+import type { RuntimeContext } from "./types.ts";
+
+export type RuntimeAppState = {
+  readonly context: RuntimeContext;
+  readonly store: RunStore;
+};
+
+export class RuntimeControlHttpError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message);
+    this.name = "RuntimeControlHttpError";
+  }
+}
+
+export function runtimeHealth(context: RuntimeContext) {
+  return {
+    ok: true,
+    projectId: context.projectId,
+    projectDir: context.projectDir,
+    configPath: context.configPath,
+    statePath: context.statePath,
+    engineVersion: RIGKIT_ENGINE_VERSION,
+    runtimeVersion: RIGKIT_RUNTIME_VERSION,
+    expiresAt: context.getExpiresAt(),
+  };
+}
+
+export function runtimeMetadata() {
+  return {
+    apiVersion: RUNTIME_API_VERSION,
+    engineVersion: RIGKIT_ENGINE_VERSION,
+    runtimeVersion: RIGKIT_RUNTIME_VERSION,
+    protocolHash: RUNTIME_PROTOCOL_HASH,
+  };
+}
+
+export async function runtimeProject(context: RuntimeContext) {
+  const engine = await loadEngine(context);
+  return engine.getProjectInfo();
+}
+
+export async function runtimeOperations(context: RuntimeContext) {
+  const engine = await loadEngine(context);
+  return operationManifestFor(engine);
+}
+
+export async function runtimeWorkflows(context: RuntimeContext) {
+  const engine = await loadEngine(context);
+  return { workflows: engine.listWorkflowSummaries() };
+}
+
+export async function runtimeWorkspaces(context: RuntimeContext) {
+  const engine = await loadEngine(context);
+  return { workspaces: engine.listWorkspaces().map(runtimeWorkspace) };
+}
+
+export async function runtimeSnapshots(context: RuntimeContext) {
+  const engine = await loadEngine(context);
+  return { snapshots: engine.listSnapshots() };
+}
+
+export function runtimeRuns(store: RunStore) {
+  return {
+    runs: [...store.runs.values()].map((run) => summarizeRun(run)),
+  };
+}
+
+export async function startRuntimeRun(state: RuntimeAppState, body: RunOperationRequest) {
+  const engine = await loadEngine(state.context);
+  const manifest = operationManifestFor(engine);
+  const operation = findRuntimeOperation(manifest.operations, body.operation);
+  if (!operation) throw new RuntimeControlHttpError(400, `Unknown operation ${body.operation}`);
+
+  const run = createRun(operation.id, body.input ?? {}, operation);
+  state.store.runs.set(run.id, run);
+  runOperation(run, state.store, state.context);
+
+  return {
+    runId: run.id,
+    operation: run.operation,
+    status: run.status,
+    eventsUrl: `/runs/${run.id}/events`,
+    sessionUrl: `/runs/${run.id}/session`,
+  };
+}
+
+export function runtimeRun(store: RunStore, runId: string) {
+  const run = store.runs.get(runId);
+  if (!run) throw new RuntimeControlHttpError(404, `Unknown run ${runId}`);
+  return summarizeRun(run);
+}
+
+export function runtimeRunEvents(store: RunStore, runId: string): Response {
+  const run = store.runs.get(runId);
+  if (!run) throw new RuntimeControlHttpError(404, `Unknown run ${runId}`);
+  return sseResponse(run);
+}
+
+export function submitHostResponse(state: RuntimeAppState, requestId: string, body: HostResponse) {
+  const pending = state.store.hostResponses.get(requestId);
+  if (!pending) throw new RuntimeControlHttpError(404, `Unknown host request ${requestId}`);
+
+  state.store.hostResponses.delete(requestId);
+  clearPendingHostRequest(state.store, requestId);
+  if ("error" in body) {
+    pending.reject(new RuntimeHostRequestError({
+      requestId,
+      hostCode: body.error.code,
+      message: body.error.message ?? "Host request failed",
+    }));
+  } else {
+    pending.resolve(body.result ?? null);
+  }
+  return { ok: true };
+}
+
+export function shutdownRuntime(context: RuntimeContext) {
+  setTimeout(() => context.stop(), 0);
+  return { ok: true };
+}
+
+export function runtimeControlErrorStatus(error: unknown): number {
+  if (error instanceof RuntimeControlHttpError) return error.status;
+  if (error instanceof RuntimeProtocolSchemaError) return 400;
+  return 500;
+}
+
+function findRuntimeOperation(operations: RuntimeOperation[], requestedOperation: string): RuntimeOperation | undefined {
+  return operations.find((operation) =>
+    operation.id === requestedOperation || operation.aliases?.includes(requestedOperation)
+  );
+}
+
+function runtimeWorkspace(workspace: WorkspaceRecord): WorkspaceRecord & { data: WorkspaceRecord["metadata"] } {
+  return {
+    ...workspace,
+    data: workspace.metadata,
+  };
+}
+
+export function clearPendingHostRequest(store: RunStore, requestId: string): void {
+  for (const run of store.runs.values()) {
+    run.pendingHostRequestIds.delete(requestId);
+  }
+}

package/src/runtime/errors.ts

@@ -0,0 +1,108 @@
+import {
+  EngineOperationNotFoundError,
+  EngineOperationValidationError,
+} from "@rigkit/engine";
+
+export type RuntimeFailureCode =
+  | "ENGINE_FAILED"
+  | "HOST_REQUEST_FAILED"
+  | "OPERATION_NOT_FOUND"
+  | "OPERATION_VALIDATION_FAILED"
+  | "RUN_CANCELLED";
+
+export class RuntimeOperationValidationError extends Error {
+  readonly code = "OPERATION_VALIDATION_FAILED" as const;
+  readonly operation: string;
+
+  constructor(input: { operation: string; cause: unknown }) {
+    super(`Invalid input for operation ${input.operation}: ${String(input.cause)}`, { cause: input.cause });
+    this.name = "RuntimeOperationValidationError";
+    this.operation = input.operation;
+  }
+}
+
+export class RuntimeOperationNotFoundError extends Error {
+  readonly code = "OPERATION_NOT_FOUND" as const;
+  readonly operation: string;
+
+  constructor(operation: string) {
+    super(`Unknown operation ${operation}`);
+    this.name = "RuntimeOperationNotFoundError";
+    this.operation = operation;
+  }
+}
+
+export class RuntimeHostRequestError extends Error {
+  readonly code = "HOST_REQUEST_FAILED" as const;
+  readonly requestId?: string;
+  readonly method?: string;
+  readonly hostCode?: string;
+
+  constructor(input: {
+    message?: string;
+    requestId?: string;
+    method?: string;
+    hostCode?: string;
+    cause?: unknown;
+  }) {
+    super(input.message ?? "Host request failed", { cause: input.cause });
+    this.name = "RuntimeHostRequestError";
+    this.requestId = input.requestId;
+    this.method = input.method;
+    this.hostCode = input.hostCode;
+  }
+}
+
+export class RuntimeEngineError extends Error {
+  readonly code = "ENGINE_FAILED" as const;
+
+  constructor(input: { message?: string; cause: unknown }) {
+    super(input.message ?? errorMessage(input.cause), { cause: input.cause });
+    this.name = "RuntimeEngineError";
+  }
+}
+
+export class RuntimeRunCancelledError extends Error {
+  readonly code = "RUN_CANCELLED" as const;
+
+  constructor() {
+    super("Run cancelled by host");
+    this.name = "RuntimeRunCancelledError";
+  }
+}
+
+export type RuntimeRunError =
+  | RuntimeEngineError
+  | RuntimeHostRequestError
+  | RuntimeOperationNotFoundError
+  | RuntimeOperationValidationError
+  | RuntimeRunCancelledError;
+
+export function isRuntimeRunError(error: unknown): error is RuntimeRunError {
+  return error instanceof RuntimeEngineError
+    || error instanceof RuntimeHostRequestError
+    || error instanceof RuntimeOperationNotFoundError
+    || error instanceof RuntimeOperationValidationError
+    || error instanceof RuntimeRunCancelledError;
+}
+
+export function normalizeRuntimeRunError(error: unknown): RuntimeRunError {
+  if (isRuntimeRunError(error)) return error;
+  if (error instanceof EngineOperationNotFoundError) return new RuntimeOperationNotFoundError(error.operation);
+  if (error instanceof EngineOperationValidationError) {
+    return new RuntimeOperationValidationError({ operation: error.operation, cause: error });
+  }
+  return new RuntimeEngineError({ cause: error });
+}
+
+export function runtimeFailureBody(error: unknown): { code: RuntimeFailureCode; message: string } {
+  const normalized = normalizeRuntimeRunError(error);
+  return {
+    code: normalized.code,
+    message: normalized.message,
+  };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/runtime/index.ts

@@ -0,0 +1,81 @@
+export {
+  RuntimeEngineError,
+  RuntimeHostRequestError,
+  RuntimeOperationNotFoundError,
+  RuntimeOperationValidationError,
+  RuntimeRunCancelledError,
+  isRuntimeRunError,
+  normalizeRuntimeRunError,
+  runtimeFailureBody,
+  type RuntimeFailureCode,
+  type RuntimeRunError,
+} from "./errors.ts";
+export {
+  RuntimeServerError,
+  serveRuntime,
+  serveRuntimeEffect,
+  type ServeRuntimeOptions,
+  type RuntimeServer,
+} from "./server.ts";
+export { RIGKIT_RUNTIME_VERSION } from "./version.ts";
+export {
+  RuntimeApiState,
+  createRuntimeControlApiHandler,
+  runtimeApiStateLayer,
+  runtimeControlApiErrorMiddlewareLayer,
+  runtimeControlApiHandlersLayer,
+} from "./api-handlers.ts";
+export {
+  RuntimeControlHttpError,
+  runtimeControlErrorStatus,
+} from "./control.ts";
+export {
+  createRuntimeStateService,
+  type RuntimeStateService,
+  type RuntimeStateServiceOptions,
+} from "./state.ts";
+export {
+  HostCapabilityRequirementEffectSchema,
+  HostMethodRequirementEffectSchema,
+  OkResponseEffectSchema,
+  OperationsManifestEffectSchema,
+  ProjectInfoEffectSchema,
+  RunStartedEffectSchema,
+  RuntimeHealthEffectSchema,
+  RuntimeMetadataEffectSchema,
+  RuntimeOperationCliEffectSchema,
+  RuntimeOperationEffectSchema,
+  RuntimeRunEffectSchema,
+  RunsResponseEffectSchema,
+  SnapshotsResponseEffectSchema,
+  WorkflowSummaryEffectSchema,
+  WorkflowsResponseEffectSchema,
+  WorkspaceEffectSchema,
+  WorkspacesResponseEffectSchema,
+  runtimeControlApi,
+  runtimeControlOpenApiDocument,
+} from "./api.ts";
+export { createRuntimeApp, type RuntimeAppState } from "./app.ts";
+export type { HostCapabilitySessionResult } from "./runs.ts";
+export {
+  DEFAULT_IDLE_MS,
+  HostCommandRequestEffectSchema,
+  HostCommandRequestSchema,
+  HostCommandResultEffectSchema,
+  HostCommandResultSchema,
+  HostResponseEffectSchema,
+  HostResponseSchema,
+  RUNTIME_API_VERSION,
+  RUNTIME_PROTOCOL_HASH,
+  RunOperationRequestEffectSchema,
+  RunOperationRequestSchema,
+  RuntimeProtocolSchemaError,
+  type RuntimeOperationsManifest,
+  type HostCommandRequest,
+  type HostCommandResult,
+  type HostResponse,
+  type HostCapabilityRequestEvent,
+  type HostRequestEvent,
+  type RuntimeEvent,
+  type RuntimeOperation,
+} from "./protocol.ts";

package/src/runtime/openapi.ts

@@ -0,0 +1,5 @@
+import { runtimeControlOpenApiDocument } from "./api.ts";
+
+export function openApiDocument(): Record<string, unknown> {
+  return runtimeControlOpenApiDocument() as unknown as Record<string, unknown>;
+}