@unicity-astrid/sdk 0.1.0

package/src/runtime/registry.ts

@@ -0,0 +1,178 @@
+/**
+ * Module-scoped registry populated by the @capsule, @tool, @install,
+ * @upgrade, @interceptor, @command, @run decorators. The bridge reads from
+ * this registry to dispatch host export calls.
+ *
+ * Decorators run during class evaluation, which happens at module init.
+ * The bridge is constructed AFTER all decorators have populated the
+ * registry, so reads are safe.
+ */
+
+export type CapsuleConstructor = new () => object;
+
+export interface ToolEntry {
+  /** Name exposed to the LLM / kernel — matches `tool_execute_<name>` action. */
+  name: string;
+  /** TS method name on the class. */
+  methodName: string;
+  /** If true, the bridge loads state before and saves after on success. */
+  mutable: boolean;
+  /** Human-readable description from decorator or TSDoc. */
+  description: string | undefined;
+  /** JSON Schema for the tool's input. Built-time codegen fills this in. */
+  inputSchema: Record<string, unknown> | undefined;
+}
+
+export interface InterceptorEntry {
+  /** Topic pattern the interceptor reacts to (also the hook action name). */
+  topic: string;
+  methodName: string;
+  mutable: boolean;
+}
+
+export interface CommandEntry {
+  /** Command name (= hook action name, registered alongside interceptors). */
+  name: string;
+  methodName: string;
+  mutable: boolean;
+}
+
+export interface CapsuleRegistration {
+  ctor: CapsuleConstructor;
+  tools: Map<string, ToolEntry>;
+  interceptors: Map<string, InterceptorEntry>;
+  commands: Map<string, CommandEntry>;
+  installMethod: string | undefined;
+  upgradeMethod: string | undefined;
+  runMethod: string | undefined;
+  description: string | undefined;
+}
+
+let registration: CapsuleRegistration | undefined;
+
+function newRegistration(ctor: CapsuleConstructor, description: string | undefined): CapsuleRegistration {
+  return {
+    ctor,
+    tools: new Map(),
+    interceptors: new Map(),
+    commands: new Map(),
+    installMethod: undefined,
+    upgradeMethod: undefined,
+    runMethod: undefined,
+    description,
+  };
+}
+
+export function registerCapsule(ctor: CapsuleConstructor, description?: string): void {
+  if (registration !== undefined && registration.ctor !== ctor) {
+    throw new Error(
+      `Only one @capsule class may be registered per WASM module. ` +
+        `Already have ${registration.ctor.name}; refusing to register ${ctor.name}.`,
+    );
+  }
+  if (registration === undefined) {
+    registration = newRegistration(ctor, description);
+  } else if (description !== undefined && registration.description === undefined) {
+    registration.description = description;
+  }
+}
+
+/**
+ * Decorators may run before `@capsule` if class fields appear before the
+ * class itself in source. Buffer pending entries on the constructor so the
+ * eventual @capsule call picks them up.
+ */
+const pendingByCtor = new WeakMap<CapsuleConstructor, CapsuleRegistration>();
+
+function ensureRegistration(ctor: CapsuleConstructor): CapsuleRegistration {
+  if (registration !== undefined && registration.ctor === ctor) {
+    return registration;
+  }
+  let pending = pendingByCtor.get(ctor);
+  if (pending === undefined) {
+    pending = newRegistration(ctor, undefined);
+    pendingByCtor.set(ctor, pending);
+  }
+  return pending;
+}
+
+/** Adopt any decorator entries buffered before @capsule fired. */
+export function adoptPending(ctor: CapsuleConstructor): void {
+  if (registration === undefined || registration.ctor !== ctor) return;
+  const pending = pendingByCtor.get(ctor);
+  if (pending === undefined) return;
+  for (const [name, entry] of pending.tools) registration.tools.set(name, entry);
+  for (const [topic, entry] of pending.interceptors) registration.interceptors.set(topic, entry);
+  for (const [name, entry] of pending.commands) registration.commands.set(name, entry);
+  if (pending.installMethod !== undefined && registration.installMethod === undefined) {
+    registration.installMethod = pending.installMethod;
+  }
+  if (pending.upgradeMethod !== undefined && registration.upgradeMethod === undefined) {
+    registration.upgradeMethod = pending.upgradeMethod;
+  }
+  if (pending.runMethod !== undefined && registration.runMethod === undefined) {
+    registration.runMethod = pending.runMethod;
+  }
+  if (pending.description !== undefined && registration.description === undefined) {
+    registration.description = pending.description;
+  }
+  pendingByCtor.delete(ctor);
+}
+
+export function recordTool(ctor: CapsuleConstructor, entry: ToolEntry): void {
+  const target = ensureRegistration(ctor);
+  if (target.tools.has(entry.name)) {
+    throw new Error(`@tool("${entry.name}") declared twice on ${ctor.name}.`);
+  }
+  target.tools.set(entry.name, entry);
+}
+
+export function recordInterceptor(ctor: CapsuleConstructor, entry: InterceptorEntry): void {
+  const target = ensureRegistration(ctor);
+  if (target.interceptors.has(entry.topic)) {
+    throw new Error(`@interceptor("${entry.topic}") declared twice on ${ctor.name}.`);
+  }
+  target.interceptors.set(entry.topic, entry);
+}
+
+export function recordCommand(ctor: CapsuleConstructor, entry: CommandEntry): void {
+  const target = ensureRegistration(ctor);
+  if (target.commands.has(entry.name)) {
+    throw new Error(`@command("${entry.name}") declared twice on ${ctor.name}.`);
+  }
+  target.commands.set(entry.name, entry);
+}
+
+export function recordInstall(ctor: CapsuleConstructor, methodName: string): void {
+  const target = ensureRegistration(ctor);
+  if (target.installMethod !== undefined) {
+    throw new Error(`Only one @install method allowed on ${ctor.name}.`);
+  }
+  target.installMethod = methodName;
+}
+
+export function recordUpgrade(ctor: CapsuleConstructor, methodName: string): void {
+  const target = ensureRegistration(ctor);
+  if (target.upgradeMethod !== undefined) {
+    throw new Error(`Only one @upgrade method allowed on ${ctor.name}.`);
+  }
+  target.upgradeMethod = methodName;
+}
+
+export function recordRun(ctor: CapsuleConstructor, methodName: string): void {
+  const target = ensureRegistration(ctor);
+  if (target.runMethod !== undefined) {
+    throw new Error(`Only one @run method allowed on ${ctor.name}.`);
+  }
+  target.runMethod = methodName;
+}
+
+/** Returns the registered capsule, or undefined if none has been declared. */
+export function getRegistration(): CapsuleRegistration | undefined {
+  return registration;
+}
+
+/** Test-only: reset the registry to a clean state. */
+export function __resetRegistry(): void {
+  registration = undefined;
+}

package/src/runtime.ts

@@ -0,0 +1,70 @@
+/**
+ * OS runtime introspection + signaling. Mirrors `astrid_sdk::runtime`.
+ *
+ * Also surfaces {@link randomBytes} (cryptographically secure host entropy
+ * via `sys::random-bytes`) for capsules that need an audit-traced CSPRNG —
+ * `globalThis.crypto.getRandomValues` works inside StarlingMonkey but
+ * bypasses the host audit trail.
+ */
+
+import {
+  getCaller as hostGetCaller,
+  signalReady as hostSignalReady,
+  randomBytes as hostRandomBytes,
+} from "astrid:sys/host@1.0.0";
+import { SysError, callHost } from "./errors.js";
+import { get as getEnv, CONFIG_SOCKET_PATH } from "./env.js";
+
+/** Information about the caller that triggered the current execution. */
+export interface CallerContext {
+  /** UUID of the capsule that originated the IPC message. */
+  sourceId: string;
+  /** The acting principal (user ID), if available. */
+  principal: string | undefined;
+  /** ISO 8601 timestamp of the originating message. */
+  timestamp: string;
+}
+
+/**
+ * Signal that the capsule's run loop is ready. Call after setting up IPC
+ * subscriptions inside `@run`; the kernel waits for this before loading
+ * dependent capsules.
+ */
+export function signalReady(): void {
+  callHost("runtime.signalReady", () => hostSignalReady());
+}
+
+/** Caller context for the current invocation. */
+export function caller(): CallerContext {
+  const ctx = callHost("runtime.caller", () => hostGetCaller());
+  return {
+    sourceId: ctx.sourceId,
+    principal: ctx.principal,
+    timestamp: ctx.timestamp,
+  };
+}
+
+/**
+ * Fill `length` bytes with cryptographically secure random data from the
+ * host's OS-level CSPRNG. Capped at 4096 bytes per call.
+ */
+export function randomBytes(length: number): Uint8Array {
+  return callHost(`runtime.randomBytes(${length})`, () =>
+    hostRandomBytes(BigInt(length)),
+  );
+}
+
+/**
+ * Kernel's Unix domain socket path, injected via the well-known
+ * `ASTRID_SOCKET_PATH` config key.
+ */
+export function socketPath(): string {
+  const path = getEnv(CONFIG_SOCKET_PATH);
+  if (path === "") {
+    throw SysError.api("ASTRID_SOCKET_PATH config key is empty");
+  }
+  if (path.indexOf("\0") >= 0) {
+    throw SysError.api("ASTRID_SOCKET_PATH contains null byte");
+  }
+  return path;
+}

package/src/time.ts

@@ -0,0 +1,48 @@
+/**
+ * Wall-clock and monotonic time — mirrors `astrid_sdk::time`.
+ *
+ * The WASM guest has no direct access to the system clock; all time comes
+ * through the `sys` host package. {@link now} / {@link nowMs} return wall
+ * clock (subject to NTP adjustments); {@link monotonicNs} returns a host
+ * monotonic reading suitable for measuring elapsed time within a single
+ * capsule lifetime.
+ */
+
+import { clockMs, clockMonotonicNs, sleepNs as hostSleepNs } from "astrid:sys/host@1.0.0";
+import { callHost } from "./errors.js";
+
+/** Current wall-clock time as a JS `Date`. */
+export function now(): Date {
+  const ms = callHost("time.now", () => clockMs());
+  return new Date(Number(ms));
+}
+
+/** Current wall-clock time as a bigint of milliseconds since UNIX epoch. */
+export function nowMs(): bigint {
+  return callHost("time.nowMs", () => clockMs());
+}
+
+/**
+ * Current monotonic clock reading in nanoseconds. Suitable for measuring
+ * elapsed time; the absolute value is meaningless across processes or capsule
+ * reloads — only differences are.
+ */
+export function monotonicNs(): bigint {
+  return callHost("time.monotonicNs", () => clockMonotonicNs());
+}
+
+/**
+ * Block the calling task for the given duration in milliseconds.
+ *
+ * Capped at 60_000 ms (60 s) per call by the host. Throws `cancelled` if
+ * the capsule unloads mid-sleep.
+ */
+export function sleepMs(ms: number): void {
+  const ns = BigInt(Math.max(0, Math.floor(ms))) * 1_000_000n;
+  callHost(`time.sleepMs(${ms})`, () => hostSleepNs(ns));
+}
+
+/** Block for `ns` nanoseconds. See {@link sleepMs} for the practical wrapper. */
+export function sleepNs(ns: bigint): void {
+  callHost(`time.sleepNs(${ns})`, () => hostSleepNs(ns));
+}

package/src/tool.ts

@@ -0,0 +1,125 @@
+/**
+ * `@tool`, `@interceptor`, `@command` method decorators — mirror
+ * `#[astrid::tool]`, `#[astrid::interceptor]`, `#[astrid::command]` from the
+ * Rust SDK.
+ *
+ * Unlike Rust, JS has no `&mut self` signal at decoration time, so
+ * mutability is opt-in via the options bag. Without `mutable: true`, the
+ * bridge will not load or save `__state` around the call.
+ */
+
+import {
+  type CapsuleConstructor,
+  recordTool,
+  recordInterceptor,
+  recordCommand,
+} from "./runtime/registry.js";
+
+export interface ToolOptions {
+  /** If true, the bridge auto-loads + auto-persists capsule state via KV `__state`. */
+  mutable?: boolean;
+  /** Human-readable tool description. If omitted, build-time codegen extracts from TSDoc. */
+  description?: string;
+  /** Pre-computed JSON Schema. If omitted, build-time codegen derives from TS types. */
+  inputSchema?: Record<string, unknown>;
+}
+
+export interface InterceptorOptions {
+  /** Mirror @tool: opt-in state load/save for handlers that mutate `this`. */
+  mutable?: boolean;
+}
+
+export interface CommandOptions {
+  mutable?: boolean;
+}
+
+/**
+ * Declares a method as an Astrid tool. The decorator records the tool in
+ * the registry; the bridge dispatches `tool_execute_<name>` hook actions
+ * to it.
+ */
+export function tool(name: string, options: ToolOptions = {}) {
+  requireName("tool", name);
+
+  return function <This extends object, Args, Result>(
+    _value: (this: This, args: Args) => Result | Promise<Result>,
+    context: ClassMethodDecoratorContext<This, (this: This, args: Args) => Result | Promise<Result>>,
+  ): void {
+    if (context.private || context.static) {
+      throw new Error(`@tool("${name}") must be applied to a public instance method.`);
+    }
+    context.addInitializer(function () {
+      const ctor = (this as object).constructor as CapsuleConstructor;
+      recordTool(ctor, {
+        name,
+        methodName: String(context.name),
+        mutable: options.mutable === true,
+        description: options.description,
+        inputSchema: options.inputSchema,
+      });
+    });
+  };
+}
+
+/**
+ * Declares a method as an interceptor on a specific IPC topic. The bridge
+ * routes hook-trigger actions named exactly `<topic>` to this method.
+ *
+ * Topic patterns follow IPC subscription rules (exact match or
+ * trailing-suffix wildcard). The kernel pre-registers the subscription
+ * when the capsule has both `@run` and `@interceptor` — for purely
+ * hook-driven (non-runnable) capsules the kernel dispatches directly.
+ */
+export function interceptor(topic: string, options: InterceptorOptions = {}) {
+  requireName("interceptor", topic);
+
+  return function <This extends object, Payload, Result>(
+    _value: (this: This, payload: Payload) => Result | Promise<Result>,
+    context: ClassMethodDecoratorContext<This, (this: This, payload: Payload) => Result | Promise<Result>>,
+  ): void {
+    if (context.private || context.static) {
+      throw new Error(`@interceptor("${topic}") must be applied to a public instance method.`);
+    }
+    context.addInitializer(function () {
+      const ctor = (this as object).constructor as CapsuleConstructor;
+      recordInterceptor(ctor, {
+        topic,
+        methodName: String(context.name),
+        mutable: options.mutable === true,
+      });
+    });
+  };
+}
+
+/**
+ * Declares a method as an RPC-style command. Commands and interceptors
+ * share the same dispatch table on the kernel side — the only difference
+ * is intent (commands are invoked directly by name, interceptors fire on
+ * topic matches).
+ */
+export function command(name: string, options: CommandOptions = {}) {
+  requireName("command", name);
+
+  return function <This extends object, Payload, Result>(
+    _value: (this: This, payload: Payload) => Result | Promise<Result>,
+    context: ClassMethodDecoratorContext<This, (this: This, payload: Payload) => Result | Promise<Result>>,
+  ): void {
+    if (context.private || context.static) {
+      throw new Error(`@command("${name}") must be applied to a public instance method.`);
+    }
+    context.addInitializer(function () {
+      const ctor = (this as object).constructor as CapsuleConstructor;
+      recordCommand(ctor, {
+        name,
+        methodName: String(context.name),
+        mutable: options.mutable === true,
+      });
+    });
+  };
+}
+
+function requireName(kind: string, name: string): void {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error(`@${kind} requires a non-empty name (got ${JSON.stringify(name)})`);
+  }
+}

package/src/uplink.ts

@@ -0,0 +1,49 @@
+/**
+ * Direct frontend messaging. Mirrors `astrid_sdk::uplink`.
+ *
+ * Capsules register uplinks (named endpoints) for platforms they bridge —
+ * Discord, Slack, Telegram, CLI proxy — and then forward inbound user
+ * messages to the kernel's processing pipeline.
+ */
+
+import {
+  uplinkRegister,
+  uplinkSend,
+  type UplinkProfile,
+} from "astrid:uplink/host@1.0.0";
+import { callHost } from "./errors.js";
+
+export type { UplinkProfile } from "astrid:uplink/host@1.0.0";
+
+export class UplinkId {
+  readonly value: string;
+  constructor(value: string) {
+    this.value = value;
+  }
+  toString(): string {
+    return this.value;
+  }
+}
+
+/**
+ * Register an uplink. `profile` is one of `"chat"` / `"interactive"` /
+ * `"notify"` / `"bridge"`. Returns the assigned uplink UUID wrapped in
+ * {@link UplinkId}.
+ */
+export function register(name: string, platform: string, profile: UplinkProfile): UplinkId {
+  const id = callHost(`uplink.register(${JSON.stringify(name)})`, () =>
+    uplinkRegister(name, platform, profile),
+  );
+  return new UplinkId(id);
+}
+
+/**
+ * Forward an inbound message through a registered uplink. Returns `true` if
+ * sent, `false` if intentionally dropped (e.g. no active session for the
+ * principal).
+ */
+export function send(uplink: UplinkId, platformUserId: string, content: string): boolean {
+  return callHost(`uplink.send(${uplink.value})`, () =>
+    uplinkSend(uplink.value, platformUserId, content),
+  );
+}