@rigkit/sdk 0.2.6 → 0.2.8

package/README.md

@@ -8,9 +8,7 @@ Configs should import authoring helpers from this package:
 import { env, workflow } from "@rigkit/sdk";
 ```
 
-Task handlers receive `step.log(message, options)` for structured step logs. Pass `step.log` to SDKs that accept a logger callback.
-Those events stream over the runtime run session and are rendered by interactive
-hosts such as the `rig` terminal run timeline.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rigkit/sdk",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "type": "module",
   "repository": {
     "type": "git",
@@ -23,8 +23,8 @@
     "@effect/platform": "0.96.1",
     "@effect/platform-bun": "0.89.0",
     "effect": "^3.21.2",
-    "@rigkit/engine": "0.2.6",
-    "@rigkit/runtime-client": "0.2.6"
+    "@rigkit/engine": "0.2.8",
+    "@rigkit/runtime-client": "0.2.8"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/cli.ts

@@ -8,6 +8,7 @@ type ServeArgs = {
   projectDir?: string;
   configPath?: string;
   statePath?: string;
+  globalFragmentRoot?: string;
   sourceJson?: string;
   handlePath?: string;
   tokenPath?: string;
@@ -42,6 +43,7 @@ const runtime = await serveRuntime({
   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!),
@@ -95,6 +97,9 @@ function parseServeArgs(args: string[]): ServeArgs {
       case "--state-path":
         parsed.statePath = readValue();
         break;
+      case "--global-fragment-root":
+        parsed.globalFragmentRoot = readValue();
+        break;
       case "--source-json":
         parsed.sourceJson = readValue();
         break;

package/src/index.test.ts

@@ -16,7 +16,7 @@ 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.2.6");
+    expect(RIGKIT_SDK_VERSION).toBe("0.2.8");
     expect(env).toBeTypeOf("function");
     expect(env.secret).toBeTypeOf("function");
     expect(defineConfig).toBeTypeOf("function");

package/src/index.ts

@@ -49,6 +49,10 @@ export {
   RuntimeServerError,
   RunsResponseEffectSchema,
   SnapshotsResponseEffectSchema,
+  CacheEntryEffectSchema,
+  CacheResponseEffectSchema,
+  CacheClearRequestEffectSchema,
+  CacheClearResponseEffectSchema,
   WorkflowSummaryEffectSchema,
   WorkflowsResponseEffectSchema,
   WorkspaceEffectSchema,

package/src/runtime/api-handlers.ts

@@ -29,6 +29,9 @@ import {
   shutdownRuntime,
   startRuntimeRun,
   submitHostResponse,
+  runtimeCache,
+  clearRuntimeCache,
+  invalidateRuntimeCache,
   type RuntimeAppState,
 } from "./control.ts";
 import type { RunStore } from "./runs.ts";
@@ -57,6 +60,11 @@ export const runtimeControlApiHandlersLayer = HttpApiBuilder.group(
       .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)))

package/src/runtime/api.ts

@@ -13,6 +13,10 @@ export {
   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,

package/src/runtime/control.ts

@@ -39,6 +39,7 @@ export function runtimeHealth(context: RuntimeContext) {
     projectDir: context.projectDir,
     configPath: context.configPath,
     statePath: context.statePath,
+    globalFragmentRoot: context.globalFragmentRoot,
     engineVersion: RIGKIT_ENGINE_VERSION,
     runtimeVersion: RIGKIT_RUNTIME_VERSION,
     expiresAt: context.getExpiresAt(),
@@ -79,6 +80,29 @@ export async function runtimeSnapshots(context: RuntimeContext) {
   return { snapshots: engine.listSnapshots() };
 }
 
+export async function runtimeCache(context: RuntimeContext) {
+  const engine = await loadEngine(context);
+  return await engine.listCache();
+}
+
+export async function clearRuntimeCache(context: RuntimeContext, body: { scope?: "local" | "global" | "all" }) {
+  const engine = await loadEngine(context);
+  const result = await engine.clearCache({ scope: body.scope });
+  return { ok: true, deleted: result.deleted };
+}
+
+export async function invalidateRuntimeCache(
+  context: RuntimeContext,
+  body: { workflow?: string; nodePaths?: readonly string[] },
+) {
+  const engine = await loadEngine(context);
+  const result = await engine.invalidateCache({
+    workflow: body.workflow,
+    nodePaths: body.nodePaths,
+  });
+  return { ok: true, invalidated: result.invalidated };
+}
+
 export function runtimeRuns(store: RunStore) {
   return {
     runs: [...store.runs.values()].map((run) => summarizeRun(run)),

package/src/runtime/errors.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import {
+  RuntimeEngineError,
+  runtimeFailureBody,
+} from "./errors.ts";
+
+describe("runtime failure serialization", () => {
+  test("preserves cause chain details for run logs", () => {
+    const upstream = new Error("INTERNAL_ERROR: Internal server error") as Error & {
+      body: Record<string, unknown>;
+      statusCode: number;
+    };
+    upstream.name = "InternalErrorError";
+    upstream.statusCode = 500;
+    upstream.body = {
+      code: "INTERNAL_ERROR",
+      message: "Internal server error",
+      requestId: "req_123",
+      authorization: "Bearer secret-token",
+    };
+
+    const body = runtimeFailureBody(new RuntimeEngineError({ cause: upstream }));
+
+    expect(body.code).toBe("ENGINE_FAILED");
+    expect(body.message).toBe("INTERNAL_ERROR: Internal server error");
+    expect(body.details?.name).toBe("RuntimeEngineError");
+    expect(body.details?.cause).toMatchObject({
+      name: "InternalErrorError",
+      message: "INTERNAL_ERROR: Internal server error",
+      statusCode: 500,
+      body: {
+        code: "INTERNAL_ERROR",
+        message: "Internal server error",
+        requestId: "req_123",
+        authorization: "[redacted]",
+      },
+    });
+  });
+});

package/src/runtime/errors.ts

@@ -10,6 +10,12 @@ export type RuntimeFailureCode =
   | "OPERATION_VALIDATION_FAILED"
   | "RUN_CANCELLED";
 
+export type RuntimeFailureBody = {
+  code: RuntimeFailureCode;
+  message: string;
+  details?: Record<string, unknown>;
+};
+
 export class RuntimeOperationValidationError extends Error {
   readonly code = "OPERATION_VALIDATION_FAILED" as const;
   readonly operation: string;
@@ -95,14 +101,99 @@ export function normalizeRuntimeRunError(error: unknown): RuntimeRunError {
   return new RuntimeEngineError({ cause: error });
 }
 
-export function runtimeFailureBody(error: unknown): { code: RuntimeFailureCode; message: string } {
+export function runtimeFailureBody(error: unknown): RuntimeFailureBody {
   const normalized = normalizeRuntimeRunError(error);
+  const details = failureDetails(normalized);
   return {
     code: normalized.code,
     message: normalized.message,
+    ...(details ? { details } : {}),
   };
 }
 
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
+
+const MAX_DETAIL_DEPTH = 5;
+const MAX_DETAIL_KEYS = 60;
+const MAX_DETAIL_ITEMS = 40;
+const MAX_DETAIL_STRING = 8_000;
+const SENSITIVE_DETAIL_KEY = /authorization|api[-_]?key|access[-_]?token|refresh[-_]?token|password|secret|credential|cookie/i;
+
+function failureDetails(error: RuntimeRunError): Record<string, unknown> | undefined {
+  const details = errorDetailValue(error, new WeakSet(), 0);
+  return isRecord(details) ? details : undefined;
+}
+
+function errorDetailValue(value: unknown, seen: WeakSet<object>, depth: number): unknown {
+  if (depth > MAX_DETAIL_DEPTH) return "[Max depth exceeded]";
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") return clipDetailString(value);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "symbol" || typeof value === "function") return String(value);
+
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+
+  if (value instanceof Error) {
+    const detail: Record<string, unknown> = {
+      name: value.name,
+      message: value.message,
+    };
+    if (value.stack) detail.stack = clipDetailString(value.stack);
+
+    for (const key of [
+      "code",
+      "status",
+      "statusCode",
+      "requestId",
+      "method",
+      "path",
+      "hostCode",
+      "operation",
+      "reason",
+      "body",
+    ]) {
+      const field = (value as unknown as Record<string, unknown>)[key];
+      if (field !== undefined) detail[key] = redactOrDetail(key, field, seen, depth + 1);
+    }
+
+    const cause = (value as { cause?: unknown }).cause;
+    if (cause !== undefined) detail.cause = errorDetailValue(cause, seen, depth + 1);
+    return detail;
+  }
+
+  if (Array.isArray(value)) {
+    const items = value.slice(0, MAX_DETAIL_ITEMS).map((item) => errorDetailValue(item, seen, depth + 1));
+    if (value.length > MAX_DETAIL_ITEMS) items.push(`[${value.length - MAX_DETAIL_ITEMS} more items]`);
+    return items;
+  }
+
+  if (!isRecord(value)) return String(value);
+
+  const detail: Record<string, unknown> = {};
+  const entries = Object.entries(value).slice(0, MAX_DETAIL_KEYS);
+  for (const [key, field] of entries) {
+    detail[key] = redactOrDetail(key, field, seen, depth + 1);
+  }
+  const extra = Object.keys(value).length - entries.length;
+  if (extra > 0) detail.__truncated = `${extra} more keys`;
+  return detail;
+}
+
+function redactOrDetail(key: string, value: unknown, seen: WeakSet<object>, depth: number): unknown {
+  if (SENSITIVE_DETAIL_KEY.test(key)) return "[redacted]";
+  return errorDetailValue(value, seen, depth);
+}
+
+function clipDetailString(value: string): string {
+  return value.length > MAX_DETAIL_STRING
+    ? `${value.slice(0, MAX_DETAIL_STRING)}... [truncated]`
+    : value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/src/runtime/index.ts

@@ -46,6 +46,10 @@ export {
   RuntimeRunEffectSchema,
   RunsResponseEffectSchema,
   SnapshotsResponseEffectSchema,
+  CacheEntryEffectSchema,
+  CacheResponseEffectSchema,
+  CacheClearRequestEffectSchema,
+  CacheClearResponseEffectSchema,
   WorkflowSummaryEffectSchema,
   WorkflowsResponseEffectSchema,
   WorkspaceEffectSchema,

package/src/runtime/operations.ts

@@ -5,6 +5,7 @@ import {
   type JsonValue,
   type LocalHostCapabilityRequestOptions,
 } from "@rigkit/engine";
+import { join } from "node:path";
 import { normalizeRuntimeRunError } from "./errors.ts";
 import {
   HostCommandResultSchema,
@@ -31,6 +32,7 @@ export type EngineLoadOptions = {
   projectDir: string;
   configPath: string;
   statePath?: string;
+  globalFragmentRoot?: string;
   source?: JsonValue;
 };
 
@@ -46,6 +48,11 @@ export async function loadEngine(input: EngineLoadOptions): Promise<DevMachineEn
       runtimeVersion: RIGKIT_RUNTIME_VERSION,
       source: input.source,
     }),
+    globalFragmentStateLocator: input.globalFragmentRoot
+      ? (fragment) => ({
+        statePath: join(input.globalFragmentRoot!, fragment.hash, "state.sqlite"),
+      })
+      : undefined,
   });
   await engine.load();
   return engine;
@@ -67,6 +74,11 @@ async function executeOperation(run: RunRecord, store: RunStore, options: Engine
       runtimeVersion: RIGKIT_RUNTIME_VERSION,
       source: options.source,
     }),
+    globalFragmentStateLocator: options.globalFragmentRoot
+      ? (fragment) => ({
+        statePath: join(options.globalFragmentRoot!, fragment.hash, "state.sqlite"),
+      })
+      : undefined,
     interaction: {
       present: async (request) => {
         await requestHost(store, run, "open.external", {

package/src/runtime/protocol.ts

@@ -113,7 +113,7 @@ export type RunCompletedEvent = {
 export type RunFailedEvent = {
   type: "run.failed";
   runId: string;
-  error: { code?: string; message: string };
+  error: { code?: string; message: string; details?: Record<string, unknown> };
 };
 
 export type RuntimeEvent =

package/src/runtime/runs.ts

@@ -1,6 +1,7 @@
 import type { RuntimeEvent, RuntimeOperation } from "./protocol.ts";
 import {
   RuntimeHostRequestError,
+  type RuntimeFailureBody,
   runtimeFailureBody,
 } from "./errors.ts";
 
@@ -33,7 +34,7 @@ export type RunRecord = {
   status: RunStatus;
   events: RuntimeEvent[];
   result?: unknown;
-  error?: { code: string; message: string };
+  error?: RuntimeFailureBody;
   pendingHostRequestIds: Set<string>;
   pendingHostCapabilityResourceIds: Set<string>;
   subscribers: Set<ReadableStreamDefaultController<Uint8Array>>;
@@ -48,7 +49,7 @@ export type RuntimeRunSummary = {
   input: unknown;
   status: RunStatus;
   result?: unknown;
-  error?: { code: string; message: string };
+  error?: RuntimeFailureBody;
   createdAt: string;
   updatedAt: string;
 };

package/src/runtime/server.ts

@@ -41,6 +41,7 @@ export async function serveRuntime(options: ServeRuntimeOptions): Promise<Runtim
   const projectDir = resolve(options.projectDir);
   const configPath = resolve(options.configPath);
   const statePath = options.statePath ? resolve(options.statePath) : undefined;
+  const globalFragmentRoot = options.globalFragmentRoot ? resolve(options.globalFragmentRoot) : undefined;
   const host = options.host ?? "127.0.0.1";
   const token = options.token ?? readOrCreateToken(options.tokenPath);
   const idleMs = options.idleMs ?? DEFAULT_IDLE_MS;
@@ -65,6 +66,7 @@ export async function serveRuntime(options: ServeRuntimeOptions): Promise<Runtim
         projectDir,
         configPath,
         statePath,
+        globalFragmentRoot,
         pid: process.pid,
         url,
         tokenPath: options.tokenPath,
@@ -82,6 +84,7 @@ export async function serveRuntime(options: ServeRuntimeOptions): Promise<Runtim
     projectDir,
     configPath,
     statePath,
+    globalFragmentRoot,
     source: options.source,
     token,
     startedAt,

package/src/runtime/types.ts

@@ -6,6 +6,7 @@ export type ServeRuntimeOptions = {
   projectDir: string;
   configPath: string;
   statePath?: string;
+  globalFragmentRoot?: string;
   source?: JsonValue;
   handlePath: string;
   tokenPath: string;
@@ -28,6 +29,7 @@ export type RuntimeContext = {
   readonly projectDir: string;
   readonly configPath: string;
   readonly statePath?: string;
+  readonly globalFragmentRoot?: string;
   readonly source?: JsonValue;
   readonly token: string;
   readonly startedAt: string;

package/src/runtime/version.ts

@@ -1 +1 @@
-export const RIGKIT_RUNTIME_VERSION = "0.2.6";
+export const RIGKIT_RUNTIME_VERSION = "0.2.8";

package/src/version.ts

@@ -1 +1 @@
-export const RIGKIT_SDK_VERSION = "0.2.6";
+export const RIGKIT_SDK_VERSION = "0.2.8";