@rigkit/sdk 0.0.0-canary-20260518T014918-c5bc0c2

package/README.md

@@ -0,0 +1,17 @@
+# @rigkit/sdk
+
+Project-local rigkit authoring API and runtime daemon package.
+
+Configs should import authoring helpers from this package:
+
+```ts
+import { env, workflow } from "@rigkit/sdk";
+```
+
+Inside a task handler, `console.log`, `console.info`, `console.debug`, `console.warn`, and `console.error` are intercepted and streamed to the runtime as structured `log.output` events with a level. The CLI renders each level distinctly (debug dim, log default, warn yellow, error red). For SDKs that accept a logger callback (e.g. `freestyle.client.vms.create({ logger: console.log })`), pass `console.log` directly. Set `RIGKIT_NO_CONSOLE_INTERCEPT=1` to disable the intercept and write to the host's terminal instead.
+Provider VM commands can also report incremental stdout/stderr through
+`ExecOptions.onOutput`; the runtime forwards those chunks over the same run
+session and falls back to buffered command output when a provider cannot stream.
+
+Local hosts start the project daemon through the `rigkit-project-runtime` binary
+installed by this package.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rigkit/sdk",
+  "version": "0.0.0-canary-20260518T014918-c5bc0c2",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freestyle-sh/rigkit.git",
+    "directory": "packages/sdk"
+  },
+  "bin": {
+    "rigkit-project-runtime": "./src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./host": "./src/host.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@effect/platform": "0.96.1",
+    "@effect/platform-bun": "0.89.0",
+    "effect": "^3.21.2",
+    "@rigkit/engine": "0.0.0-canary-20260518T014918-c5bc0c2",
+    "@rigkit/runtime-client": "0.0.0-canary-20260518T014918-c5bc0c2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+import { resolve } from "node:path";
+import { serveRuntime } from "./runtime/server.ts";
+
+type ServeArgs = {
+  projectId?: string;
+  runtimeFingerprint?: string;
+  projectDir?: string;
+  configPath?: string;
+  statePath?: string;
+  globalFragmentRoot?: 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-project-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!,
+  runtimeFingerprint: options.runtimeFingerprint,
+  projectDir: resolve(options.projectDir!),
+  configPath: resolve(options.configPath!),
+  statePath: options.statePath ? resolve(options.statePath) : undefined,
+  globalFragmentRoot: options.globalFragmentRoot ? resolve(options.globalFragmentRoot) : 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();
+  });
+}
+
+await runtime.closed;
+await Bun.sleep(25);
+process.exit(0);
+
+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 "--runtime-fingerprint":
+        parsed.runtimeFingerprint = 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 "--global-fragment-root":
+        parsed.globalFragmentRoot = 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/host.ts

@@ -0,0 +1,55 @@
+export type HostCapabilityLogOptions = {
+  stream?: "stdout" | "stderr" | "info";
+  label?: string;
+};
+
+export type HostCapabilityContext = {
+  log(data: string, options?: HostCapabilityLogOptions): void;
+};
+
+export type HostCapabilityDefinition<Input = unknown, Result = unknown> = {
+  readonly schemaHash?: string;
+  readonly input?: unknown;
+  readonly output?: unknown;
+  readonly handle: (params: Input, context?: HostCapabilityContext) => Result | Promise<Result>;
+};
+
+export type HostCapabilityHandler<Input = unknown, Result = unknown> =
+  & HostCapabilityDefinition<Input, Result>
+  & {
+    readonly id: string;
+  };
+
+export function defineHostCapability<const Id extends string, Input = unknown, Result = unknown>(
+  id: Id,
+  definition: HostCapabilityDefinition<Input, Result>,
+): HostCapabilityHandler<Input, Result> & { readonly id: Id } {
+  return {
+    id,
+    ...definition,
+  };
+}
+
+export function defineHostCapabilities<const Definitions extends Record<string, HostCapabilityDefinition<any, any>>>(
+  definitions: Definitions,
+): Array<{
+  readonly [Id in keyof Definitions & string]: HostCapabilityHandler<
+    HostCapabilityInput<Definitions[Id]>,
+    HostCapabilityResult<Definitions[Id]>
+  > & { readonly id: Id };
+}[keyof Definitions & string]> {
+  return Object.entries(definitions).map(([id, definition]) =>
+    defineHostCapability(id, definition as HostCapabilityDefinition)
+  ) as Array<{
+    readonly [Id in keyof Definitions & string]: HostCapabilityHandler<
+      HostCapabilityInput<Definitions[Id]>,
+      HostCapabilityResult<Definitions[Id]>
+    > & { readonly id: Id };
+  }[keyof Definitions & string]>;
+}
+
+type HostCapabilityInput<Definition> =
+  Definition extends HostCapabilityDefinition<infer Input, any> ? Input : unknown;
+
+type HostCapabilityResult<Definition> =
+  Definition extends HostCapabilityDefinition<any, infer Result> ? Result : unknown;

package/src/index.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import {
+  RIGKIT_SDK_VERSION,
+  createRuntimeControlApiHandler,
+  defineConfig,
+  env,
+  runtimeControlApi,
+  runtimeControlOpenApiDocument,
+  RuntimeHostRequestError,
+  serveRuntime,
+  serveRuntimeEffect,
+  sequence,
+  workflow,
+} from "./index.ts";
+import { defineHostCapabilities, defineHostCapability } from "./host.ts";
+
+describe("@rigkit/sdk package boundary", () => {
+  test("exports authoring API and project runtime entrypoints", () => {
+    expect(RIGKIT_SDK_VERSION).toBe("0.0.0-canary-20260518T014918-c5bc0c2");
+    expect(env).toBeTypeOf("function");
+    expect(env.secret).toBeTypeOf("function");
+    expect(defineConfig).toBeTypeOf("function");
+    expect(sequence).toBeTypeOf("function");
+    expect(workflow).toBeTypeOf("function");
+    expect(serveRuntime).toBeTypeOf("function");
+    expect(serveRuntimeEffect).toBeTypeOf("function");
+    expect(createRuntimeControlApiHandler).toBeTypeOf("function");
+    expect(runtimeControlApi).toBeDefined();
+    const document = runtimeControlOpenApiDocument() as any;
+    expect(document.paths["/runs"].post.operationId).toBe("startRun");
+    expect(new RuntimeHostRequestError({ message: "host failed" }).code).toBe("HOST_REQUEST_FAILED");
+  });
+
+  test("exports typed host capability registration helpers", async () => {
+    const single = defineHostCapability("demo.open", {
+      schemaHash: "sha256:demo",
+      handle: (params: { name: string }) => ({ opened: params.name }),
+    });
+
+    expect(single.id).toBe("demo.open");
+    expect(single.schemaHash).toBe("sha256:demo");
+    expect(single.handle({ name: "workspace" })).toEqual({ opened: "workspace" });
+
+    const [registered] = defineHostCapabilities({
+      "demo.close": {
+        handle: async (params: { sessionId: string }) => ({ closed: params.sessionId }),
+      },
+    });
+
+    expect(registered?.id).toBe("demo.close");
+    await expect(registered?.handle({ sessionId: "session-1" })).resolves.toEqual({ closed: "session-1" });
+  });
+});

package/src/index.ts

@@ -0,0 +1,86 @@
+export { RIGKIT_SDK_VERSION } from "./version.ts";
+
+export {
+  defineConfig,
+  defineProvider,
+  env,
+  isRigkitConfig,
+  isProviderDefinition,
+  isWorkflow,
+  isWorkflowNode,
+  sequence,
+  workflow,
+} from "@rigkit/engine";
+export type * from "@rigkit/engine";
+
+export {
+  createRuntimeControlApiHandler,
+  createRuntimeApp,
+  DEFAULT_IDLE_MS,
+  RIGKIT_RUNTIME_VERSION,
+  createRuntimeStateService,
+  HostCommandRequestEffectSchema,
+  HostCommandRequestSchema,
+  HostCommandResultEffectSchema,
+  HostCommandResultSchema,
+  HostResponseEffectSchema,
+  HostResponseSchema,
+  OkResponseEffectSchema,
+  OperationsManifestEffectSchema,
+  ProjectInfoEffectSchema,
+  RUNTIME_API_VERSION,
+  RUNTIME_PROTOCOL_HASH,
+  RunStartedEffectSchema,
+  RunOperationRequestEffectSchema,
+  RunOperationRequestSchema,
+  RuntimeApiState,
+  RuntimeControlHttpError,
+  RuntimeEngineError,
+  RuntimeHealthEffectSchema,
+  RuntimeHostRequestError,
+  RuntimeMetadataEffectSchema,
+  RuntimeOperationNotFoundError,
+  RuntimeOperationCliEffectSchema,
+  RuntimeOperationEffectSchema,
+  RuntimeOperationValidationError,
+  RuntimeProtocolSchemaError,
+  RuntimeRunEffectSchema,
+  RuntimeRunCancelledError,
+  RuntimeServerError,
+  RunsResponseEffectSchema,
+  SnapshotsResponseEffectSchema,
+  CacheEntryEffectSchema,
+  CacheResponseEffectSchema,
+  CacheClearRequestEffectSchema,
+  CacheClearResponseEffectSchema,
+  WorkflowSummaryEffectSchema,
+  WorkflowsResponseEffectSchema,
+  WorkspaceEffectSchema,
+  WorkspacesResponseEffectSchema,
+  runtimeControlApi,
+  runtimeControlApiErrorMiddlewareLayer,
+  runtimeApiStateLayer,
+  runtimeControlApiHandlersLayer,
+  runtimeControlOpenApiDocument,
+  runtimeControlErrorStatus,
+  isRuntimeRunError,
+  normalizeRuntimeRunError,
+  runtimeFailureBody,
+  serveRuntime,
+  serveRuntimeEffect,
+  type RuntimeFailureCode,
+  type HostCommandRequest,
+  type HostCommandResult,
+  type HostRequestEvent,
+  type HostResponse,
+  type RuntimeAppState,
+  type RuntimeEvent,
+  type HostCapabilitySessionResult,
+  type RuntimeOperation,
+  type RuntimeOperationsManifest,
+  type RuntimeRunError,
+  type RuntimeServer,
+  type RuntimeStateService,
+  type RuntimeStateServiceOptions,
+  type ServeRuntimeOptions,
+} from "./runtime/index.ts";

package/src/runtime/api-handlers.ts

@@ -0,0 +1,174 @@
+import {
+  HttpApiBuilder,
+  HttpApp,
+  HttpServer,
+  HttpServerResponse,
+  type HttpServerRequest,
+} from "@effect/platform";
+import { Cause, Context, Effect, Layer } from "effect";
+import { RIGKIT_ENGINE_VERSION } from "@rigkit/engine";
+import { RIGKIT_RUNTIME_VERSION } from "./version.ts";
+import { runtimeControlApi } from "./api.ts";
+import {
+  RUNTIME_API_VERSION,
+  RUNTIME_PROTOCOL_HASH,
+} from "./protocol.ts";
+import { openApiDocument } from "./openapi.ts";
+import {
+  runtimeControlErrorStatus,
+  runtimeHealth,
+  runtimeMetadata,
+  runtimeOperations,
+  runtimeProject,
+  runtimeRun,
+  runtimeRunEvents,
+  runtimeRuns,
+  runtimeSnapshots,
+  runtimeWorkflows,
+  runtimeWorkspaces,
+  shutdownRuntime,
+  startRuntimeRun,
+  submitHostResponse,
+  runtimeCache,
+  clearRuntimeCache,
+  invalidateRuntimeCache,
+  type RuntimeAppState,
+} from "./control.ts";
+import type { RunStore } from "./runs.ts";
+import type { RuntimeContext } from "./types.ts";
+
+export class RuntimeApiState extends Context.Tag("rigkit/RuntimeApiState")<
+  RuntimeApiState,
+  RuntimeAppState
+>() {}
+
+export function runtimeApiStateLayer(context: RuntimeContext, store: RunStore) {
+  return Layer.succeed(RuntimeApiState, { context, store });
+}
+
+export const runtimeControlApiHandlersLayer = HttpApiBuilder.group(
+  runtimeControlApi,
+  "control",
+  (handlers) =>
+    handlers
+      .handle("health", (request) =>
+        handleControlRequest(request, (state) => runtimeHealth(state.context), { public: true }))
+      .handle("openApi", (request) => handleControlRequest(request, () => openApiDocument()))
+      .handle("runtime", (request) => handleControlRequest(request, () => runtimeMetadata()))
+      .handle("project", (request) => handleControlRequest(request, (state) => runtimeProject(state.context)))
+      .handle("operations", (request) => handleControlRequest(request, (state) => runtimeOperations(state.context)))
+      .handle("workflows", (request) => handleControlRequest(request, (state) => runtimeWorkflows(state.context)))
+      .handle("workspaces", (request) => handleControlRequest(request, (state) => runtimeWorkspaces(state.context)))
+      .handle("snapshots", (request) => handleControlRequest(request, (state) => runtimeSnapshots(state.context)))
+      .handle("cache", (request) => handleControlRequest(request, (state) => runtimeCache(state.context)))
+      .handle("clearCache", (request) =>
+        handleControlRequest(request, (state) => clearRuntimeCache(state.context, request.payload)))
+      .handle("invalidateCache", (request) =>
+        handleControlRequest(request, (state) => invalidateRuntimeCache(state.context, request.payload)))
+      .handle("runs", (request) => handleControlRequest(request, (state) => runtimeRuns(state.store)))
+      .handle("startRun", (request) =>
+        handleControlRequest(request, (state) => startRuntimeRun(state, request.payload)))
+      .handle("run", (request) =>
+        handleControlRequest(request, (state) => runtimeRun(state.store, request.path.runId)))
+      .handle("runEvents", (request) =>
+        handleControlRequest(
+          request,
+          (state) => HttpServerResponse.fromWeb(runtimeRunEvents(state.store, request.path.runId)),
+        ))
+      .handle("hostResponse", (request) =>
+        handleControlRequest(
+          request,
+          (state) => submitHostResponse(state, request.path.requestId, request.payload),
+        ))
+      .handle("shutdown", (request) =>
+        handleControlRequest(request, (state) => shutdownRuntime(state.context))),
+);
+
+export const runtimeControlApiErrorMiddlewareLayer = HttpApiBuilder.middleware(
+  normalizeRuntimeControlErrors,
+);
+
+export function createRuntimeControlApiHandler(context: RuntimeContext, store: RunStore) {
+  const runtimeApiLayer = HttpApiBuilder.api(runtimeControlApi).pipe(
+    Layer.provide(runtimeControlApiHandlersLayer),
+    Layer.provide(runtimeApiStateLayer(context, store)),
+  );
+
+  return HttpApiBuilder.toWebHandler(
+    Layer.mergeAll(
+      runtimeApiLayer,
+      runtimeControlApiErrorMiddlewareLayer,
+      HttpServer.layerContext,
+    ),
+  );
+}
+
+type ControlRequest = {
+  readonly request: HttpServerRequest.HttpServerRequest;
+};
+
+type ControlOptions = {
+  readonly public?: boolean;
+};
+
+function handleControlRequest<A>(
+  request: ControlRequest,
+  run: (state: RuntimeAppState) => A | PromiseLike<A>,
+  options: ControlOptions = {},
+) {
+  return Effect.gen(function* () {
+    const state = yield* RuntimeApiState;
+    yield* appendRuntimeHeaders;
+    if (!options.public && request.request.headers.authorization !== `Bearer ${state.context.token}`) {
+      return jsonError(401, "Unauthorized");
+    }
+    state.context.touch();
+    return yield* Effect.tryPromise({
+      try: async () => run(state),
+      catch: (error) => error,
+    }).pipe(
+      Effect.catchAll((error) => Effect.succeed(errorResponse(error))),
+    );
+  });
+}
+
+const appendRuntimeHeaders = HttpApp.appendPreResponseHandler((_request, response) =>
+  Effect.succeed(HttpServerResponse.setHeaders(response, runtimeHeaders())));
+
+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,
+  };
+}
+
+function errorResponse(error: unknown) {
+  return jsonError(runtimeControlErrorStatus(error), error instanceof Error ? error.message : String(error));
+}
+
+function jsonError(status: number, message: string) {
+  return HttpServerResponse.unsafeJson({ error: { message } }, { status });
+}
+
+function normalizeRuntimeControlErrors(app: HttpApp.Default): HttpApp.Default {
+  return Effect.catchAllCause(app as HttpApp.Default<unknown>, (cause) => {
+    const error = Cause.squash(cause);
+    if (isHttpApiDecodeError(error)) {
+      return Effect.succeed(jsonError(400, error.message));
+    }
+    return Effect.failCause(cause);
+  }) as HttpApp.Default;
+}
+
+function isHttpApiDecodeError(error: unknown): error is { _tag: "HttpApiDecodeError"; message: string } {
+  return Boolean(
+    error &&
+      typeof error === "object" &&
+      "_tag" in error &&
+      error._tag === "HttpApiDecodeError" &&
+      "message" in error &&
+      typeof error.message === "string",
+  );
+}

package/src/runtime/api.ts

@@ -0,0 +1,71 @@
+import { OpenApi } from "@effect/platform";
+import { runtimeControlApi } from "@rigkit/runtime-client";
+
+export {
+  RuntimeControlHealthEffectSchema as RuntimeHealthEffectSchema,
+  RuntimeControlMetadataEffectSchema as RuntimeMetadataEffectSchema,
+  RuntimeControlOkResponseEffectSchema as OkResponseEffectSchema,
+  RuntimeControlOperationCliEffectSchema as RuntimeOperationCliEffectSchema,
+  RuntimeControlOperationEffectSchema as RuntimeOperationEffectSchema,
+  RuntimeControlOperationsManifestEffectSchema as OperationsManifestEffectSchema,
+  RuntimeControlProjectInfoEffectSchema as ProjectInfoEffectSchema,
+  RuntimeControlRunEffectSchema as RuntimeRunEffectSchema,
+  RuntimeControlRunStartedEffectSchema as RunStartedEffectSchema,
+  RuntimeControlRunsResponseEffectSchema as RunsResponseEffectSchema,
+  RuntimeControlSnapshotsResponseEffectSchema as SnapshotsResponseEffectSchema,
+  RuntimeControlCacheEntryEffectSchema as CacheEntryEffectSchema,
+  RuntimeControlCacheResponseEffectSchema as CacheResponseEffectSchema,
+  RuntimeControlCacheClearRequestEffectSchema as CacheClearRequestEffectSchema,
+  RuntimeControlCacheClearResponseEffectSchema as CacheClearResponseEffectSchema,
+  RuntimeControlWorkflowSummaryEffectSchema as WorkflowSummaryEffectSchema,
+  RuntimeControlWorkflowsResponseEffectSchema as WorkflowsResponseEffectSchema,
+  RuntimeControlWorkspaceEffectSchema as WorkspaceEffectSchema,
+  RuntimeControlWorkspacesResponseEffectSchema as WorkspacesResponseEffectSchema,
+  runtimeControlApi,
+} from "@rigkit/runtime-client";
+
+export function runtimeControlOpenApiDocument(): OpenApi.OpenAPISpec {
+  const spec = OpenApi.fromApi(runtimeControlApi, { additionalPropertiesStrategy: "allow" });
+  spec.security = [{ bearerAuth: [] }];
+  spec.components.securitySchemes = {
+    ...spec.components.securitySchemes,
+    bearerAuth: {
+      type: "http",
+      scheme: "bearer",
+    },
+  };
+
+  for (const [path, methods] of Object.entries(spec.paths)) {
+    for (const operation of Object.values(methods)) {
+      operation.security = path === "/health" ? [] : [{ bearerAuth: [] }];
+    }
+  }
+
+  const hostResponseOperation = spec.paths["/host-responses/{requestId}"]?.post as any;
+  const hostResponseSchema = hostResponseOperation?.requestBody?.content?.["application/json"]?.schema;
+  if (hostResponseSchema) {
+    spec.components.schemas.HostResponse = hostResponseSchema;
+    hostResponseOperation.requestBody.content["application/json"].schema = {
+      $ref: "#/components/schemas/HostResponse",
+    };
+  }
+
+  spec.paths["/runs/{runId}/session"] = {
+    get: {
+      tags: ["control"],
+      operationId: "control.runSession",
+      parameters: [{
+        name: "runId",
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+      }],
+      security: [{ bearerAuth: [] }],
+      responses: {
+        "101": { description: "Run WebSocket session" },
+      },
+    },
+  };
+
+  return spec;
+}