@unicity-astrid/sdk 0.1.0

package/dist/runtime.js

@@ -0,0 +1,50 @@
+/**
+ * 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";
+/**
+ * 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() {
+    callHost("runtime.signalReady", () => hostSignalReady());
+}
+/** Caller context for the current invocation. */
+export function caller() {
+    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) {
+    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() {
+    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;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,SAAS,IAAI,aAAa,EAC1B,WAAW,IAAI,eAAe,EAC9B,WAAW,IAAI,eAAe,GAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,GAAG,IAAI,MAAM,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAY7D;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;AAC3D,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,MAAM;IACpB,MAAM,GAAG,GAAG,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,CAAC,CAAC;IAC9D,OAAO;QACL,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;KACzB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,QAAQ,CAAC,uBAAuB,MAAM,GAAG,EAAE,GAAG,EAAE,CACrD,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAChC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAChB,MAAM,QAAQ,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,QAAQ,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/time.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/** Current wall-clock time as a JS `Date`. */
+export declare function now(): Date;
+/** Current wall-clock time as a bigint of milliseconds since UNIX epoch. */
+export declare function nowMs(): bigint;
+/**
+ * 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 declare function monotonicNs(): bigint;
+/**
+ * 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 declare function sleepMs(ms: number): void;
+/** Block for `ns` nanoseconds. See {@link sleepMs} for the practical wrapper. */
+export declare function sleepNs(ns: bigint): void;
+//# sourceMappingURL=time.d.ts.map

package/dist/time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.d.ts","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,8CAA8C;AAC9C,wBAAgB,GAAG,IAAI,IAAI,CAG1B;AAED,4EAA4E;AAC5E,wBAAgB,KAAK,IAAI,MAAM,CAE9B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAGxC;AAED,iFAAiF;AACjF,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAExC"}

package/dist/time.js

@@ -0,0 +1,43 @@
+/**
+ * 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() {
+    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() {
+    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() {
+    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) {
+    const ns = BigInt(Math.max(0, Math.floor(ms))) * 1000000n;
+    callHost(`time.sleepMs(${ms})`, () => hostSleepNs(ns));
+}
+/** Block for `ns` nanoseconds. See {@link sleepMs} for the practical wrapper. */
+export function sleepNs(ns) {
+    callHost(`time.sleepNs(${ns})`, () => hostSleepNs(ns));
+}
+//# sourceMappingURL=time.js.map

package/dist/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../src/time.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8CAA8C;AAC9C,MAAM,UAAU,GAAG;IACjB,MAAM,EAAE,GAAG,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACjD,OAAO,IAAI,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,KAAK;IACnB,OAAO,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE,CAAC,gBAAgB,EAAE,CAAC,CAAC;AAChE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,QAAU,CAAC;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/dist/tool.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `@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.
+ */
+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 declare function tool(name: string, options?: ToolOptions): <This extends object, Args, Result>(_value: (this: This, args: Args) => Result | Promise<Result>, context: ClassMethodDecoratorContext<This, (this: This, args: Args) => Result | Promise<Result>>) => void;
+/**
+ * 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 declare function interceptor(topic: string, options?: InterceptorOptions): <This extends object, Payload, Result>(_value: (this: This, payload: Payload) => Result | Promise<Result>, context: ClassMethodDecoratorContext<This, (this: This, payload: Payload) => Result | Promise<Result>>) => void;
+/**
+ * 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 declare function command(name: string, options?: CommandOptions): <This extends object, Payload, Result>(_value: (this: This, payload: Payload) => Result | Promise<Result>, context: ClassMethodDecoratorContext<This, (this: This, payload: Payload) => Result | Promise<Result>>) => void;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sFAAsF;IACtF,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,IAGzC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAChD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAC5D,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAC/F,IAAI,CAeR;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,IAGxD,IAAI,SAAS,MAAM,EAAE,OAAO,EAAE,MAAM,EACnD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAClE,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KACrG,IAAI,CAaR;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,IAG/C,IAAI,SAAS,MAAM,EAAE,OAAO,EAAE,MAAM,EACnD,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAClE,SAAS,2BAA2B,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KACrG,IAAI,CAaR"}

package/dist/tool.js

@@ -0,0 +1,86 @@
+/**
+ * `@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 { recordTool, recordInterceptor, recordCommand, } from "./runtime/registry.js";
+/**
+ * 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, options = {}) {
+    requireName("tool", name);
+    return function (_value, context) {
+        if (context.private || context.static) {
+            throw new Error(`@tool("${name}") must be applied to a public instance method.`);
+        }
+        context.addInitializer(function () {
+            const ctor = this.constructor;
+            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, options = {}) {
+    requireName("interceptor", topic);
+    return function (_value, context) {
+        if (context.private || context.static) {
+            throw new Error(`@interceptor("${topic}") must be applied to a public instance method.`);
+        }
+        context.addInitializer(function () {
+            const ctor = this.constructor;
+            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, options = {}) {
+    requireName("command", name);
+    return function (_value, context) {
+        if (context.private || context.static) {
+            throw new Error(`@command("${name}") must be applied to a public instance method.`);
+        }
+        context.addInitializer(function () {
+            const ctor = this.constructor;
+            recordCommand(ctor, {
+                name,
+                methodName: String(context.name),
+                mutable: options.mutable === true,
+            });
+        });
+    };
+}
+function requireName(kind, name) {
+    if (typeof name !== "string" || name.length === 0) {
+        throw new Error(`@${kind} requires a non-empty name (got ${JSON.stringify(name)})`);
+    }
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,UAAU,EACV,iBAAiB,EACjB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAoB/B;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,IAAY,EAAE,UAAuB,EAAE;IAC1D,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAE1B,OAAO,UACL,MAA4D,EAC5D,OAAgG;QAEhG,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,iDAAiD,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,CAAC,cAAc,CAAC;YACrB,MAAM,IAAI,GAAI,IAAe,CAAC,WAAiC,CAAC;YAChE,UAAU,CAAC,IAAI,EAAE;gBACf,IAAI;gBACJ,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;gBAChC,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,IAAI;gBACjC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa,EAAE,UAA8B,EAAE;IACzE,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;IAElC,OAAO,UACL,MAAkE,EAClE,OAAsG;QAEtG,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,iDAAiD,CAAC,CAAC;QAC3F,CAAC;QACD,OAAO,CAAC,cAAc,CAAC;YACrB,MAAM,IAAI,GAAI,IAAe,CAAC,WAAiC,CAAC;YAChE,iBAAiB,CAAC,IAAI,EAAE;gBACtB,KAAK;gBACL,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;gBAChC,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,IAAI;aAClC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,UAA0B,EAAE;IAChE,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAE7B,OAAO,UACL,MAAkE,EAClE,OAAsG;QAEtG,IAAI,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,iDAAiD,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,CAAC,cAAc,CAAC;YACrB,MAAM,IAAI,GAAI,IAAe,CAAC,WAAiC,CAAC;YAChE,aAAa,CAAC,IAAI,EAAE;gBAClB,IAAI;gBACJ,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;gBAChC,OAAO,EAAE,OAAO,CAAC,OAAO,KAAK,IAAI;aAClC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,mCAAmC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtF,CAAC;AACH,CAAC"}

package/dist/uplink.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type UplinkProfile } from "astrid:uplink/host@1.0.0";
+export type { UplinkProfile } from "astrid:uplink/host@1.0.0";
+export declare class UplinkId {
+    readonly value: string;
+    constructor(value: string);
+    toString(): string;
+}
+/**
+ * Register an uplink. `profile` is one of `"chat"` / `"interactive"` /
+ * `"notify"` / `"bridge"`. Returns the assigned uplink UUID wrapped in
+ * {@link UplinkId}.
+ */
+export declare function register(name: string, platform: string, profile: UplinkProfile): UplinkId;
+/**
+ * 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 declare function send(uplink: UplinkId, platformUserId: string, content: string): boolean;
+//# sourceMappingURL=uplink.d.ts.map

package/dist/uplink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uplink.d.ts","sourceRoot":"","sources":["../src/uplink.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAC;AAGlC,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D,qBAAa,QAAQ;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBACX,KAAK,EAAE,MAAM;IAGzB,QAAQ,IAAI,MAAM;CAGnB;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,QAAQ,CAKzF;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAIvF"}

package/dist/uplink.js

@@ -0,0 +1,36 @@
+/**
+ * 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, } from "astrid:uplink/host@1.0.0";
+import { callHost } from "./errors.js";
+export class UplinkId {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    toString() {
+        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, platform, profile) {
+    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, platformUserId, content) {
+    return callHost(`uplink.send(${uplink.value})`, () => uplinkSend(uplink.value, platformUserId, content));
+}
+//# sourceMappingURL=uplink.js.map

package/dist/uplink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uplink.js","sourceRoot":"","sources":["../src/uplink.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,cAAc,EACd,UAAU,GAEX,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC,MAAM,OAAO,QAAQ;IACV,KAAK,CAAS;IACvB,YAAY,KAAa;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IACD,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAgB,EAAE,OAAsB;IAC7E,MAAM,EAAE,GAAG,QAAQ,CAAC,mBAAmB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CACnE,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CACxC,CAAC;IACF,OAAO,IAAI,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,MAAgB,EAAE,cAAsB,EAAE,OAAe;IAC5E,OAAO,QAAQ,CAAC,eAAe,MAAM,CAAC,KAAK,GAAG,EAAE,GAAG,EAAE,CACnD,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,cAAc,EAAE,OAAO,CAAC,CAClD,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@unicity-astrid/sdk",
+  "version": "0.1.0",
+  "description": "System SDK for building user-space capsules for Astrid OS in JavaScript and TypeScript.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "wit-contracts"
+  ],
+  "scripts": {
+    "prebuild": "node scripts/generate-contracts.mjs",
+    "build": "tsc -b",
+    "clean": "rm -rf dist src/contracts.ts"
+  },
+  "devDependencies": {
+    "@unicity-astrid/build": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/approval.ts

@@ -0,0 +1,38 @@
+/**
+ * Human-in-the-loop approval. Mirrors `astrid_sdk::approval`.
+ *
+ * The capsule declares the action and target resource. The kernel classifies
+ * risk, checks any pre-approved allowances, and either auto-approves or
+ * prompts the frontend user. The capsule sees the specific decision class
+ * (one-shot / session / always / allowance-hit / denied), not just
+ * approved/denied — UI can communicate WHY (e.g. "stored as always-approve")
+ * for transparency.
+ */
+
+import {
+  requestApproval as hostRequestApproval,
+  type ApprovalDecision,
+} from "astrid:approval/host@1.0.0";
+import { callHost } from "./errors.js";
+
+export type { ApprovalDecision } from "astrid:approval/host@1.0.0";
+
+/**
+ * Request approval for a sensitive action. Returns `true` if approved (any
+ * approval variant), `false` if denied. Blocks until the user responds or
+ * the request times out (60s).
+ *
+ * For the specific decision class, use {@link requestDecision}.
+ */
+export function request(action: string, resource: string): boolean {
+  const decision = requestDecision(action, resource);
+  return decision !== "denied";
+}
+
+/** Request approval and return the specific decision class. */
+export function requestDecision(action: string, resource: string): ApprovalDecision {
+  const resp = callHost(`approval.request(${JSON.stringify(action)})`, () =>
+    hostRequestApproval({ action, targetResource: resource }),
+  );
+  return resp.decision;
+}

package/src/capabilities.ts

@@ -0,0 +1,22 @@
+/**
+ * Cross-capsule capability queries. Mirrors `astrid_sdk::capabilities`.
+ *
+ * Allows a capsule to check whether another capsule (identified by its IPC
+ * session UUID) has a specific manifest capability. Used by the prompt
+ * builder to enforce `allow_prompt_injection` gating, for example.
+ *
+ * Fail-closed: returns `false` for unknown UUIDs, unknown capabilities, or
+ * registry-unavailable conditions (the host returns `registry-unavailable`,
+ * which `callHost` raises as a SysError — capsule code that wants to swallow
+ * registry outages should wrap the call).
+ */
+
+import { checkCapsuleCapability } from "astrid:sys/host@1.0.0";
+import { callHost } from "./errors.js";
+
+export function check(sourceUuid: string, capability: string): boolean {
+  const resp = callHost(`capabilities.check(${JSON.stringify(capability)})`, () =>
+    checkCapsuleCapability({ sourceUuid, capability }),
+  );
+  return resp.allowed;
+}

package/src/capsule.ts

@@ -0,0 +1,90 @@
+/**
+ * Capsule + lifecycle decorators. Mirrors `#[capsule]` / `#[astrid::install]`
+ * / `#[astrid::upgrade]` from the Rust SDK.
+ *
+ * TypeScript standard decorators (TC39 Stage 3 / TS 5.0+). Class-method
+ * decorators are the most stable subset of the spec; we deliberately use
+ * only that subset to minimize churn risk.
+ */
+
+import {
+  type CapsuleConstructor,
+  registerCapsule,
+  recordInstall,
+  recordUpgrade,
+  recordRun,
+  adoptPending,
+} from "./runtime/registry.js";
+
+/**
+ * Class decorator marking the entry-point of the capsule. The decorated
+ * class must have a no-arg constructor (state defaults via field initializers).
+ *
+ * Exactly one `@capsule` class per compiled WASM module.
+ */
+export function capsule<T extends CapsuleConstructor>(
+  target: T,
+  _context: ClassDecoratorContext<T>,
+): T {
+  registerCapsule(target);
+  adoptPending(target);
+  return target;
+}
+
+/**
+ * Method decorator marking the first-time install lifecycle hook. The
+ * method receives no arguments and may be async. It runs once before any
+ * tool dispatch.
+ */
+export function install<This extends object>(
+  _value: (this: This) => unknown,
+  context: ClassMethodDecoratorContext<This, (this: This) => unknown>,
+): void {
+  if (context.private || context.static) {
+    throw new Error("@install must be applied to a public instance method.");
+  }
+  context.addInitializer(function () {
+    const ctor = (this as object).constructor as CapsuleConstructor;
+    recordInstall(ctor, String(context.name));
+  });
+}
+
+/**
+ * Method decorator marking the upgrade lifecycle hook. The method receives
+ * the previous version string and may be async.
+ */
+export function upgrade<This extends object>(
+  _value: (this: This, prevVersion: string) => unknown,
+  context: ClassMethodDecoratorContext<This, (this: This, prevVersion: string) => unknown>,
+): void {
+  if (context.private || context.static) {
+    throw new Error("@upgrade must be applied to a public instance method.");
+  }
+  context.addInitializer(function () {
+    const ctor = (this as object).constructor as CapsuleConstructor;
+    recordUpgrade(ctor, String(context.name));
+  });
+}
+
+/**
+ * Method decorator marking the long-running background loop. The method
+ * receives no arguments, may be async, and is expected NEVER to return
+ * (it is the capsule's daemon loop). Mirror of `#[astrid::run]`.
+ *
+ * Capsules that declare `@run` are "runnable" capsules: the kernel
+ * spawns them as background tasks and the WIT `run` export blocks until
+ * the loop exits. Capsules without `@run` are hook-driven and the `run`
+ * export is a no-op.
+ */
+export function run<This extends object>(
+  _value: (this: This) => unknown,
+  context: ClassMethodDecoratorContext<This, (this: This) => unknown>,
+): void {
+  if (context.private || context.static) {
+    throw new Error("@run must be applied to a public instance method.");
+  }
+  context.addInitializer(function () {
+    const ctor = (this as object).constructor as CapsuleConstructor;
+    recordRun(ctor, String(context.name));
+  });
+}