@unicity-astrid/sdk 0.1.0

package/src/process.ts

@@ -0,0 +1,205 @@
+/**
+ * Host process spawning. Mirrors `astrid_sdk::process`. Capsules need the
+ * `host_process` capability for the specific command being invoked; the
+ * kernel runs the process under platform sandboxing (sandbox-exec on macOS,
+ * bwrap on Linux).
+ *
+ * Per-capsule cap: 8 concurrent background processes. `ProcessHandle` is a
+ * Component Model resource — drop releases the slot and reaps the child.
+ *
+ * **Desktop-kernel only.** Unikernel targets (hermit-rs, etc.) do not implement
+ * this package; capsules importing `astrid:process` will fail to load there.
+ */
+
+import {
+  spawn as hostSpawn,
+  spawnBackground as hostSpawnBackground,
+  type ProcessHandle as WitProcessHandle,
+  type ProcessSignal,
+  type SpawnRequest,
+  type ExitInfo,
+} from "astrid:process/host@1.0.0";
+import { SysError, callHost } from "./errors.js";
+
+export type { ProcessSignal, EnvVar } from "astrid:process/host@1.0.0";
+
+export interface ProcessResult {
+  stdout: string;
+  stderr: string;
+  /** Exit code if exited normally; `undefined` if killed by signal. */
+  exitCode: number | undefined;
+  /** Unix signal number if killed by signal; `undefined` otherwise. */
+  signal: number | undefined;
+}
+
+export interface ProcessLogs {
+  stdout: string;
+  stderr: string;
+  running: boolean;
+  exitCode: number | undefined;
+  signal: number | undefined;
+}
+
+export interface KillResult {
+  killed: boolean;
+  exitCode: number | undefined;
+  signal: number | undefined;
+  stdout: string;
+  stderr: string;
+}
+
+export interface SpawnOptions {
+  /** Working directory relative to the workspace. */
+  cwd?: string;
+  /** Environment variables to pass to the child. */
+  env?: Record<string, string>;
+  /** Stdin bytes piped to the child on spawn. */
+  stdin?: Uint8Array;
+}
+
+function buildSpawnRequest(
+  cmd: string,
+  args: string[],
+  options: SpawnOptions | undefined,
+): SpawnRequest {
+  return {
+    cmd,
+    args,
+    stdin: options?.stdin,
+    env: options?.env
+      ? Object.entries(options.env).map(([key, value]) => ({ key, value }))
+      : [],
+    cwd: options?.cwd,
+  };
+}
+
+function unpackExit(exit: ExitInfo): { exitCode: number | undefined; signal: number | undefined } {
+  return { exitCode: exit.exitCode, signal: exit.signal };
+}
+
+/** Spawn a process and block until it exits. */
+export function spawn(
+  cmd: string,
+  args: string[] = [],
+  options?: SpawnOptions,
+): ProcessResult {
+  const request = buildSpawnRequest(cmd, args, options);
+  const result = callHost(`process.spawn(${JSON.stringify(cmd)})`, () =>
+    hostSpawn(request),
+  );
+  return {
+    stdout: result.stdout,
+    stderr: result.stderr,
+    ...unpackExit(result.exit),
+  };
+}
+
+/** Spawn a background process. Returns a resource handle. */
+export function spawnBackground(
+  cmd: string,
+  args: string[] = [],
+  options?: SpawnOptions,
+): BackgroundProcessHandle {
+  const request = buildSpawnRequest(cmd, args, options);
+  const inner = callHost(`process.spawnBackground(${JSON.stringify(cmd)})`, () =>
+    hostSpawnBackground(request),
+  );
+  return new BackgroundProcessHandle(inner);
+}
+
+export class BackgroundProcessHandle {
+  #inner: WitProcessHandle | undefined;
+
+  constructor(inner: WitProcessHandle) {
+    this.#inner = inner;
+  }
+
+  /** Drain buffered stdout/stderr since the last read. */
+  readLogs(): ProcessLogs {
+    const result = callHost("process.readLogs", () => this.#requireInner().readLogs());
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      running: result.running,
+      exitCode: result.exit?.exitCode,
+      signal: result.exit?.signal,
+    };
+  }
+
+  /** Write to stdin. Returns bytes actually written. */
+  writeStdin(data: Uint8Array): number {
+    return callHost("process.writeStdin", () => this.#requireInner().writeStdin(data));
+  }
+
+  /** Close the stdin pipe (child observes EOF). */
+  closeStdin(): void {
+    callHost("process.closeStdin", () => this.#requireInner().closeStdin());
+  }
+
+  /** Send a signal (fire-and-forget). Use {@link kill} for SIGKILL + log drainage. */
+  signal(sig: ProcessSignal): void {
+    callHost(`process.signal(${sig})`, () => this.#requireInner().signal(sig));
+  }
+
+  /** Send SIGKILL and drain remaining output. */
+  kill(): KillResult {
+    const result = callHost("process.kill", () => this.#requireInner().kill());
+    return {
+      killed: result.killed,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      exitCode: result.exit?.exitCode,
+      signal: result.exit?.signal,
+    };
+  }
+
+  /**
+   * Wait for the process to exit. `timeoutMs = undefined` waits indefinitely;
+   * a bounded value throws `wait-timeout` if the timeout elapses first.
+   */
+  wait(timeoutMs?: number): { exitCode: number | undefined; signal: number | undefined } {
+    const ms = timeoutMs === undefined ? undefined : BigInt(Math.max(0, Math.floor(timeoutMs)));
+    const exit = callHost(`process.wait(${timeoutMs ?? "∞"})`, () =>
+      this.#requireInner().wait(ms),
+    );
+    return unpackExit(exit);
+  }
+
+  /** Wait for the process AND drain remaining stdout/stderr atomically. */
+  waitWithOutput(timeoutMs?: number): ProcessResult {
+    const ms = timeoutMs === undefined ? undefined : BigInt(Math.max(0, Math.floor(timeoutMs)));
+    const result = callHost(`process.waitWithOutput(${timeoutMs ?? "∞"})`, () =>
+      this.#requireInner().waitWithOutput(ms),
+    );
+    return {
+      stdout: result.stdout,
+      stderr: result.stderr,
+      ...unpackExit(result.exit),
+    };
+  }
+
+  /** OS-level PID. Throws if the process has already been reaped. */
+  osPid(): number {
+    return callHost("process.osPid", () => this.#requireInner().osPid());
+  }
+
+  close(): void {
+    if (this.#inner === undefined) return;
+    const inner = this.#inner;
+    this.#inner = undefined;
+    try {
+      inner[Symbol.dispose]();
+    } catch {
+      // already released
+    }
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
+  #requireInner(): WitProcessHandle {
+    if (this.#inner === undefined) throw SysError.api("ProcessHandle is closed");
+    return this.#inner;
+  }
+}

package/src/runtime/bridge.ts

@@ -0,0 +1,374 @@
+/**
+ * Bridge runtime — implements the four WIT guest exports
+ * (`astrid-hook-trigger`, `run`, `astrid-install`, `astrid-upgrade`) on top
+ * of the registry the decorators populated.
+ *
+ * The Rust SDK's `#[capsule]` macro generates this same logic at compile
+ * time. We do it at runtime: walk the registry, dispatch the action,
+ * load/save state for mutable handlers, publish results to IPC, and
+ * produce the `capsule-result` the kernel expects.
+ *
+ * Dispatch table mirrors `sdk-rust/astrid-sdk-macros/src/lib.rs:600–660`:
+ *   - `tool_describe`: aggregate schemas + descriptions, return as `data`.
+ *     Built lazily on first invocation, cached thereafter.
+ *   - `tool_execute_<name>`: parse `ToolExecuteRequest`, optionally load
+ *     state, run handler, publish result to `tool.v1.execute.<name>.result`,
+ *     optionally save state, return `{ action: "continue", data: undefined }`.
+ *   - any other action: check the interceptors map THEN the commands map.
+ *     Their results flow back via `capsule-result.data` directly (no IPC
+ *     publish), matching the Rust macro's behaviour for these paths.
+ *
+ * State key matches Rust: `__state`, JSON-encoded.
+ */
+
+import {
+  getRegistration,
+  type CapsuleRegistration,
+  type ToolEntry,
+  type InterceptorEntry,
+  type CommandEntry,
+} from "./registry.js";
+import * as kv from "../kv.js";
+import * as ipc from "../ipc.js";
+import * as log from "../log.js";
+import { getConfig } from "astrid:sys/host@1.0.0";
+
+const STATE_KEY = "__state";
+
+export interface CapsuleResult {
+  action: string;
+  data: string | undefined;
+}
+
+export interface Bridge {
+  astridHookTrigger(action: string, payload: Uint8Array): CapsuleResult;
+  run(): void;
+  astridInstall(): void;
+  astridUpgrade(): void;
+}
+
+interface ToolExecuteRequest {
+  call_id: string;
+  tool_name: string;
+  arguments: unknown;
+}
+
+const decoder = new TextDecoder();
+
+function denied(reason: string): CapsuleResult {
+  return { action: "deny", data: reason };
+}
+
+function cont(data?: string): CapsuleResult {
+  return { action: "continue", data };
+}
+
+export function createBridge(): Bridge {
+  let toolDescribeCache: string | undefined;
+
+  function reg(): CapsuleRegistration {
+    const r = getRegistration();
+    if (r === undefined) {
+      throw new Error(
+        "No @capsule class registered. The build pipeline emits the entry " +
+          "module after the user's source so decorators have already fired — " +
+          "this means the user code never imported the SDK or never declared " +
+          "a @capsule class.",
+      );
+    }
+    return r;
+  }
+
+  function buildToolDescribe(): string {
+    const r = reg();
+    const tools = Array.from(r.tools.values()).map(toolToDescribeEntry);
+    return JSON.stringify({
+      tools,
+      description: r.description ?? "",
+    });
+  }
+
+  function loadInstance(r: CapsuleRegistration): object {
+    const instance = new r.ctor();
+    const persisted = kv.get<Record<string, unknown>>(STATE_KEY);
+    if (persisted !== undefined && typeof persisted === "object" && persisted !== null) {
+      Object.assign(instance, persisted);
+    }
+    return instance;
+  }
+
+  function persistInstance(instance: object): void {
+    const snapshot: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(instance)) {
+      snapshot[key] = value;
+    }
+    kv.set(STATE_KEY, snapshot);
+  }
+
+  function getInstance(entry: { mutable: boolean }): { instance: object; persist: boolean } {
+    const r = reg();
+    if (entry.mutable) {
+      return { instance: loadInstance(r), persist: true };
+    }
+    return { instance: new r.ctor(), persist: false };
+  }
+
+  function executeTool(entry: ToolEntry, payload: Uint8Array): CapsuleResult {
+    let req: ToolExecuteRequest;
+    try {
+      req = JSON.parse(decoder.decode(payload)) as ToolExecuteRequest;
+    } catch (e) {
+      return denied(`failed to parse tool execute payload: ${(e as Error).message}`);
+    }
+    const callId = req.call_id ?? "";
+
+    let instance: object;
+    let persist: boolean;
+    try {
+      ({ instance, persist } = getInstance(entry));
+    } catch (e) {
+      publishToolError(entry.name, callId, `failed to load state: ${(e as Error).message}`);
+      return cont();
+    }
+
+    let resultPayload: { content: string; isError: boolean };
+    try {
+      const raw = invoke(instance, entry.methodName, req.arguments);
+      resultPayload = { content: stringifyResult(raw), isError: false };
+    } catch (e) {
+      resultPayload = { content: (e as Error).message ?? String(e), isError: true };
+    }
+
+    if (persist && !resultPayload.isError) {
+      try {
+        persistInstance(instance);
+      } catch (e) {
+        publishToolError(entry.name, callId, `failed to save state: ${(e as Error).message}`);
+        return cont();
+      }
+    }
+
+    publishToolResult(entry.name, callId, resultPayload.content, resultPayload.isError);
+    return cont();
+  }
+
+  /**
+   * Dispatch interceptor / command actions. Both kinds share the same
+   * return path: the handler's JSON-serialized result becomes
+   * `capsule-result.data`, the kernel reads it from the hook-trigger
+   * return value. `null` results yield `{ action: "continue", data: undefined }`
+   * so the interceptor chain keeps the original payload (mirrors Rust).
+   */
+  function executeHookHandler(
+    entry: InterceptorEntry | CommandEntry,
+    payload: Uint8Array,
+  ): CapsuleResult {
+    let parsed: unknown = undefined;
+    if (payload.length > 0) {
+      try {
+        parsed = JSON.parse(decoder.decode(payload));
+      } catch (e) {
+        return denied(`failed to parse payload: ${(e as Error).message}`);
+      }
+    }
+
+    let instance: object;
+    let persist: boolean;
+    try {
+      ({ instance, persist } = getInstance(entry));
+    } catch (e) {
+      return denied(`failed to load state: ${(e as Error).message}`);
+    }
+
+    let resultJson: string;
+    try {
+      const raw = invoke(instance, entry.methodName, parsed);
+      resultJson = stringifyResult(raw);
+    } catch (e) {
+      return denied((e as Error).message ?? String(e));
+    }
+
+    if (persist) {
+      try {
+        persistInstance(instance);
+      } catch (e) {
+        return denied(`failed to save state: ${(e as Error).message}`);
+      }
+    }
+
+    if (resultJson === "null") return cont();
+    return cont(resultJson);
+  }
+
+  return {
+    astridHookTrigger(action: string, payload: Uint8Array): CapsuleResult {
+      try {
+        if (action === "tool_describe") {
+          toolDescribeCache ??= buildToolDescribe();
+          return cont(toolDescribeCache);
+        }
+
+        if (action.startsWith("tool_execute_")) {
+          const name = action.slice("tool_execute_".length);
+          const r = reg();
+          const entry = r.tools.get(name);
+          if (entry === undefined) return denied(`unknown tool: ${name}`);
+          return executeTool(entry, payload);
+        }
+
+        const r = reg();
+        const interceptor = r.interceptors.get(action);
+        if (interceptor !== undefined) {
+          return executeHookHandler(interceptor, payload);
+        }
+        const command = r.commands.get(action);
+        if (command !== undefined) {
+          return executeHookHandler(command, payload);
+        }
+
+        return denied(`unknown hook action: ${action}`);
+      } catch (e) {
+        return denied(`bridge panic in astridHookTrigger: ${(e as Error).message ?? String(e)}`);
+      }
+    },
+
+    run(): void {
+      try {
+        const r = reg();
+        if (r.runMethod === undefined) {
+          // Non-runnable capsule: WIT requires the export, but it must
+          // return immediately so the kernel doesn't think we're a daemon.
+          return;
+        }
+        // Runnable capsule. Per Rust macro semantics, run() loads state but
+        // does NOT auto-persist (loops are infinite; explicit kv.set is
+        // the user's responsibility for runnable state).
+        const instance = loadInstance(r);
+        const raw = invoke(instance, r.runMethod, undefined);
+        // For a daemon-style loop, the handler should never resolve. If it
+        // does (or throws), surface via log and return.
+        if (raw instanceof Promise) {
+          syncWait(raw);
+        }
+      } catch (e) {
+        log.error(`run loop exited with error: ${(e as Error).message ?? String(e)}`);
+      }
+    },
+
+    astridInstall(): void {
+      try {
+        const r = reg();
+        if (r.installMethod === undefined) return;
+        const instance = new r.ctor();
+        invoke(instance, r.installMethod, undefined);
+        persistInstance(instance);
+      } catch (e) {
+        log.error(`install hook failed: ${(e as Error).message ?? String(e)}`);
+      }
+    },
+
+    astridUpgrade(): void {
+      try {
+        const r = reg();
+        if (r.upgradeMethod === undefined) return;
+        const prevVersion = safeGetConfig("prev_version");
+        const instance = loadInstance(r);
+        invoke(instance, r.upgradeMethod, prevVersion);
+        persistInstance(instance);
+      } catch (e) {
+        log.error(`upgrade hook failed: ${(e as Error).message ?? String(e)}`);
+      }
+    },
+  };
+}
+
+/**
+ * Call a registered method on an instance. The bridge always passes
+ * either zero or one argument; method signatures with more parameters
+ * are rejected at decorator time.
+ */
+function invoke(instance: object, methodName: string, arg: unknown): unknown {
+  const method = (instance as Record<string, unknown>)[methodName];
+  if (typeof method !== "function") {
+    throw new Error(`method ${methodName} not found on capsule instance`);
+  }
+  const raw = arg === undefined
+    ? (method as Function).call(instance)
+    : (method as Function).call(instance, arg);
+  return raw instanceof Promise ? syncWait(raw) : raw;
+}
+
+function toolToDescribeEntry(entry: ToolEntry): Record<string, unknown> {
+  const schema =
+    entry.inputSchema ?? ({ type: "object", properties: {} } as Record<string, unknown>);
+  // Mirror schemars: `mutable` is a schema extension, not a top-level field.
+  const inputSchema: Record<string, unknown> = { ...schema, mutable: entry.mutable };
+  return {
+    name: entry.name,
+    description: entry.description ?? "",
+    input_schema: inputSchema,
+  };
+}
+
+function publishToolResult(name: string, callId: string, content: string, isError: boolean): void {
+  const topic = `tool.v1.execute.${name}.result`;
+  ipc.publishJson(topic, {
+    type: "tool_execute_result",
+    call_id: callId,
+    result: { call_id: callId, content, is_error: isError },
+  });
+}
+
+function publishToolError(name: string, callId: string, message: string): void {
+  publishToolResult(name, callId, message, true);
+}
+
+function stringifyResult(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "null";
+  try {
+    return JSON.stringify(value);
+  } catch (e) {
+    throw new Error(`failed to serialize tool result: ${(e as Error).message}`);
+  }
+}
+
+function safeGetConfig(key: string): string {
+  try {
+    return getConfig(key) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * StarlingMonkey runs the JS event loop to settle promises returned from
+ * exported functions before returning to the host. Sync handlers
+ * pass-through; async handlers whose promise hasn't resolved by the
+ * engine's microtask drain are surfaced as a clear error.
+ */
+function syncWait<T>(promise: Promise<T>): T {
+  let settled = false;
+  let value: T | undefined;
+  let error: unknown;
+  promise.then(
+    (v) => {
+      settled = true;
+      value = v;
+    },
+    (e) => {
+      settled = true;
+      error = e;
+    },
+  );
+  if (!settled) {
+    throw new Error(
+      "Handler returned a Promise that did not settle synchronously. " +
+        "ComponentizeJS syncifies awaits backed by host imports it knows " +
+        "how to drive — pure setTimeout/setInterval will hang. Use only " +
+        "Astrid SDK calls inside handlers, or make the handler sync.",
+    );
+  }
+  if (error !== undefined) throw error;
+  return value as T;
+}

package/src/runtime/index.ts

@@ -0,0 +1,11 @@
+export { createBridge, type Bridge, type CapsuleResult } from "./bridge.js";
+export {
+  registerCapsule,
+  recordTool,
+  recordInstall,
+  recordUpgrade,
+  getRegistration,
+  __resetRegistry,
+  type CapsuleRegistration,
+  type ToolEntry,
+} from "./registry.js";