@agent-assembly/sdk 0.0.1-beta.3 → 0.0.1-beta.4

package/dist/types/native/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/native/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAqBD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,oBAAiB;CAC/B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,uBAAoB;CAClC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,yBAAsB;CACpC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,uBAAoB;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAAC;IACjD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,WAAW,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACzD;AAgED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAyF7E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/native/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAaD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAsBD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,oBAAiB;CAC/B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,uBAAoB;CAClC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,yBAAsB;CACpC;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,qBAAkB;CAChC;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,uBAAoB;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAAC;IACjD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,WAAW,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACxD;;;;;;;;;;OAUG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACzD;AAmFD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CA6G7E"}

package/dist/types/op-control.d.ts

@@ -36,15 +36,42 @@ export interface OpControlSubscriberOptions {
     orgId: string;
     teamId: string;
     agentId: string;
-    /** Optional credentials override; defaults to insecure (matches PR-D's
-     * dev-mode gateway). Use `grpc.credentials.createSsl(...)` in prod.
+    /** Explicit credentials override. When supplied it is used verbatim and the
+     * loopback / `allowInsecure` defaulting below is bypassed — the caller has
+     * taken full responsibility for the transport (e.g. `createSsl(...)` with a
+     * custom CA, or `createInsecure()` for an in-cluster sidecar).
      */
     credentials?: ChannelCredentials;
+    /**
+     * Permit a plaintext (`createInsecure`) channel to a **non-loopback**
+     * gateway. Off by default: control-plane signals (pause / terminate) and the
+     * agent identity triple travel this stream, so an unencrypted channel to a
+     * remote host is opt-in only. Loopback targets stay plaintext without this
+     * flag (local dev-mode gateway). Ignored when `credentials` is set.
+     */
+    allowInsecure?: boolean;
     /** Test seam — when supplied, skips opening a real gRPC channel and uses
      * this client directly. Used by the vitest tests.
      */
     clientFactory?: () => OpControlClient;
 }
+/**
+ * Extract the bare host from a gRPC target (`host:port`, a bare host, or a
+ * URL-style `scheme://host:port`). Returns the lowercased host with any
+ * surrounding IPv6 brackets preserved so it can be matched against
+ * {@link LOOPBACK_HOSTS}.
+ */
+export declare function gatewayHostOf(gatewayUrl: string): string;
+/**
+ * Pick channel credentials for the op-control stream, secure by default.
+ *
+ * Precedence: an explicit `credentials` override wins; otherwise a loopback
+ * target gets plaintext (local dev gateway), a remote target gets TLS, and a
+ * remote target is only allowed plaintext when the caller sets `allowInsecure`.
+ *
+ * @throws never — returns the chosen {@link ChannelCredentials}.
+ */
+export declare function resolveOpControlCredentials(gatewayUrl: string, opts: Pick<OpControlSubscriberOptions, "credentials" | "allowInsecure">): ChannelCredentials;
 export declare class OpControlSubscriber {
     private readonly client;
     private readonly agent;

package/dist/types/op-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"op-control.d.ts","sourceRoot":"","sources":["../../src/op-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAIjB,MAAM,6BAA6B,CAAC;AAUrC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,CACf,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAC3B,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,eAAe,CAAC;CACvC;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,IAAI,CAAuD;IACnE,OAAO,CAAC,KAAK,CAAQ;IAErB,OAAO;IAKP,wEAAwE;WAC1D,OAAO,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,0BAA0B,GAC/B,mBAAmB;IAiBtB;;OAEG;IACI,KAAK,IAAI,IAAI;IAOpB,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,cAAc;IAMtB;;;;;;;;;;OAUG;IACU,SAAS,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC,IAAI,CAAC;IAwBT,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,IAAI,OAAO;IAI7B,sCAAsC;IAC/B,KAAK,IAAI,IAAI;CAKrB"}
+{"version":3,"file":"op-control.d.ts","sourceRoot":"","sources":["../../src/op-control.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EAE1B,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,EACL,gBAAgB,EAIjB,MAAM,6BAA6B,CAAC;AAUrC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,CACf,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAC3B,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IAC5C,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,eAAe,CAAC;CACvC;AASD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAexD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,IAAI,CAAC,0BAA0B,EAAE,aAAa,GAAG,eAAe,CAAC,GACtE,kBAAkB,CAKpB;AAED,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,IAAI,CAAuD;IACnE,OAAO,CAAC,KAAK,CAAQ;IAErB,OAAO;IAKP,wEAAwE;WAC1D,OAAO,CACnB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,0BAA0B,GAC/B,mBAAmB;IAiBtB;;OAEG;IACI,KAAK,IAAI,IAAI;IAOpB,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,cAAc;IAMtB;;;;;;;;;;OAUG;IACU,SAAS,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,OAAO,CAAC,IAAI,CAAC;IAwBT,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,IAAI,OAAO;IAI7B,sCAAsC;IAC/B,KAAK,IAAI,IAAI;CAKrB"}

package/dist/types/runtime.d.ts

@@ -11,6 +11,13 @@ import { type ChildProcess } from "node:child_process";
 export declare const BINARY_NAME = "aasm";
 export declare const DEFAULT_PORT = 7878;
 export declare const DEFAULT_RUNTIME_HOST = "127.0.0.1";
+/**
+ * Opt-in gate for spawning the `aasm` sidecar. Auto-start runs a binary
+ * discovered from `$PATH` / the filesystem, so it is a privileged side effect
+ * that must be explicitly enabled rather than triggered silently by every
+ * `initAssembly()` call. Set to `1`/`true`/`yes` to permit auto-start.
+ */
+export declare const ENV_AUTO_START = "AA_AUTO_START";
 export declare const USER_LOCAL_BIN: string;
 export declare const DOCKER_BASE_BIN = "/usr/local/bin";
 export declare const RUNTIME_LOG_FILENAME = ".aasm-runtime.log";
@@ -32,6 +39,14 @@ export declare function findAasmBinary(): string | null;
  * unreachable) resolves to `false` and is treated as no sidecar.
  */
 export declare function isRunning(port?: number, host?: string): Promise<boolean>;
+/**
+ * Throw `Error` unless `binaryPath` is safe to spawn: it must be absolute and
+ * either resolve inside an allow-listed install dir (see
+ * {@link allowedInstallDirs}) or be the npm-bundled runtime binary. This is the
+ * integrity gate for the auto-start subprocess — without it the SDK would
+ * execute whatever `aasm` happened to be first on `$PATH`.
+ */
+export declare function assertSafeBinaryPath(binaryPath: string): void;
 /**
  * Spawn `aasm serve --port <port>` as a detached background subprocess.
  *
@@ -49,11 +64,18 @@ export declare function startRuntime(binaryPath: string, port?: number, logDir?:
  *  2. Resolve the binary via {@link findAasmBinary}.
  *  3. Spawn the sidecar via {@link startRuntime}.
  *
- * `agentId` is accepted to keep the ticket-specified signature stable;
- * actual register-and-connect is performed by the existing gateway-aware
- * `@agent-assembly/sdk` `initAssembly` once the sidecar is reachable.
+ * `_agentId` is accepted to keep the ticket-specified signature stable but is
+ * intentionally not consumed at this lifecycle layer; actual register-and-connect
+ * is performed by the existing gateway-aware `@agent-assembly/sdk` `initAssembly`
+ * once the sidecar is reachable.
+ *
+ * Auto-start is **opt-in**: when the sidecar is not already running, this
+ * throws unless `AA_AUTO_START` is enabled. When it does spawn, the resolved
+ * binary path is logged and integrity-checked via {@link assertSafeBinaryPath}.
  *
- * Throws `Error` with {@link INSTALL_HINT} when no binary is found.
+ * Throws `Error` with {@link INSTALL_HINT} when no binary is found, and a
+ * descriptive `Error` when auto-start is not opted in or the resolved binary
+ * fails the integrity check.
  */
-export declare function initAssembly(agentId?: string, port?: number): Promise<void>;
+export declare function initAssembly(_agentId?: string, port?: number): Promise<void>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/types/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAQ9D,eAAO,MAAM,WAAW,SAAS,CAAC;AAClC,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,eAAO,MAAM,cAAc,EAAE,MAAyC,CAAC;AACvE,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,MAA0C,CAAC;AAE5E,eAAO,MAAM,YAAY,EAAE,MAKf,CAAC;AAsBb;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAa9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,GAAE,MAAqB,EAC3B,IAAI,GAAE,MAA6B,GAClC,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAqB,EAC3B,MAAM,GAAE,MAAc,GACrB,YAAY,CASd;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,YAAY,CAChC,OAAO,CAAC,EAAE,MAAM,EAChB,IAAI,GAAE,MAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAQf"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAS,MAAM,oBAAoB,CAAC;AAQ9D,eAAO,MAAM,WAAW,SAAS,CAAC;AAClC,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,kBAAkB,CAAC;AAE9C,eAAO,MAAM,cAAc,EAAE,MAAyC,CAAC;AACvE,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,8EAA8E;AAC9E,eAAO,MAAM,kBAAkB,EAAE,MAA0C,CAAC;AAE5E,eAAO,MAAM,YAAY,EAAE,MAKf,CAAC;AAsBb;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,MAAM,GAAG,IAAI,CAa9C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,GAAE,MAAqB,EAC3B,IAAI,GAAE,MAA6B,GAClC,OAAO,CAAC,OAAO,CAAC,CAYlB;AA4BD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAc7D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,MAAqB,EAC3B,MAAM,GAAE,MAAc,GACrB,YAAY,CASd;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CAChC,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,GAAE,MAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/types/types/assembly-config.d.ts

@@ -25,6 +25,12 @@ export interface AssemblyConfig {
      */
     apiKey?: string;
     agentId?: string;
+    /**
+     * Human-readable agent name recorded by the gateway at registration
+     * (AAASM-3400). Descriptive metadata only; when omitted it falls back to
+     * ``agentId``.
+     */
+    name?: string;
     mode?: AssemblyMode;
     gatewayClient?: GatewayClient;
     langchain?: LangChainAdapterConfig;

package/dist/types/types/assembly-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assembly-config.d.ts","sourceRoot":"","sources":["../../../src/types/assembly-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC"}
+{"version":3,"file":"assembly-config.d.ts","sourceRoot":"","sources":["../../../src/types/assembly-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC"}

package/native/aa-ffi-node/index.d.ts

@@ -27,6 +27,80 @@ export declare function connect(socketPath: string): Promise<ClientHandle>
  */
 export declare function disconnect(handle: ClientHandle): Promise<void>
 
+/**
+ * A policy verdict returned to JS.
+ *
+ * `decision` is one of `"allow"`, `"deny"`, `"pending"`, `"redact"`; `reason`
+ * is the human-readable explanation from the policy engine (or the fail-open
+ * note when the runtime did not answer).
+ */
+export interface PolicyDecision {
+  decision: string
+  reason: string
+}
+
+/**
+ * Query the runtime for a policy decision on an action.
+ *
+ * The JS query object is translated into a `CheckActionRequest` (agent id,
+ * action type, and — for tool calls — tool name / source / args) and handed
+ * to [`AssemblyClient::query_policy`], which blocks its calling thread for up
+ * to 5s waiting on the runtime's `CheckActionResponse`. That blocking call is
+ * run on a `spawn_blocking` task — exactly like [`disconnect`] — so the napi
+ * async runtime stays free and the **Node event loop is never blocked** while
+ * a slow runtime is answering.
+ *
+ * **Fail-open:** the SDK is advisory, not a security boundary. When the
+ * runtime does not return a decision — it is too slow or the connection
+ * closed ([`SdkClientError::QueryFailed`]), or it was never reachable so the
+ * IPC channel is closed / the session is shut down — this returns a non-deny
+ * `"allow"` so a missing or degraded runtime never blocks the agent (the
+ * proxy / eBPF layers remain authoritative). Only a genuine local fault
+ * (a poisoned lock) surfaces as a typed error.
+ */
+export declare function queryPolicy(handle: ClientHandle, query: any): Promise<PolicyDecision>
+
+/**
+ * Register this agent with the governance gateway and store the issued
+ * credential token on the session.
+ *
+ * This is the **only** direct SDK→gateway gRPC call (per ADR 0004);
+ * `CheckAction` still flows through `aa-runtime`. The token the gateway issues
+ * is stored inside the shared [`AssemblyClient`] and then attached to every
+ * subsequent [`query_policy`] request so the gateway's
+ * `validate_credential_token` does not deny a registered agent.
+ *
+ * Delegates to [`AssemblyClient::register`], an async tonic call, so this napi
+ * function is itself `async` and awaits it without blocking the Node event
+ * loop. Returns the assigned policy id reported by the gateway. A failed
+ * registration — gateway unreachable, identity rejected — surfaces as a typed
+ * error so the caller can decide whether to proceed unregistered.
+ */
+export declare function register(handle: ClientHandle, options: RegisterOptions): Promise<string>
+
+/**
+ * Parameters for [`register`].
+ *
+ * `agentId` is the agent identity the gateway registers (derived into a
+ * `did:key` + Ed25519 public key by the shared client). `name` and `framework`
+ * are descriptive metadata the gateway records. `gatewayEndpoint` overrides the
+ * gateway gRPC endpoint (default resolved from `AA_GATEWAY_ENDPOINT` or
+ * `http://127.0.0.1:50051`).
+ *
+ * `teamId` and `parentAgentId` carry the agent's lineage/team scoping to the
+ * gateway on register (AAASM-3415): `teamId` drives team-budget attribution
+ * and `parentAgentId` the topology graph. Both are optional — omit for a
+ * team-unscoped / root agent.
+ */
+export interface RegisterOptions {
+  agentId: string
+  name: string
+  framework: string
+  gatewayEndpoint?: string
+  teamId?: string
+  parentAgentId?: string
+}
+
 /**
  * Ship a captured event to the runtime.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-assembly/sdk",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.1-beta.4",
   "description": "TypeScript SDK for Agent Assembly",
   "license": "Apache-2.0",
   "type": "module",
@@ -64,10 +64,10 @@
     "nodejs"
   ],
   "optionalDependencies": {
-    "@agent-assembly/runtime-darwin-arm64": "0.0.1-beta.3",
-    "@agent-assembly/runtime-darwin-x64": "0.0.1-beta.3",
-    "@agent-assembly/runtime-linux-arm64": "0.0.1-beta.3",
-    "@agent-assembly/runtime-linux-x64": "0.0.1-beta.3"
+    "@agent-assembly/runtime-darwin-arm64": "0.0.1-beta.4",
+    "@agent-assembly/runtime-darwin-x64": "0.0.1-beta.4",
+    "@agent-assembly/runtime-linux-arm64": "0.0.1-beta.4",
+    "@agent-assembly/runtime-linux-x64": "0.0.1-beta.4"
   },
   "files": [
     "dist/",