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

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;AAWH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,6BAA6B,CAAC;AAwBrC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,oBAAoB,CAAC,gBAAgB,CAAC,CAAC;IAC5F,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;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,kBAAkB,CAAC;IACzC,SAAS,EAAE,MAAM,kBAAkB,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,IAAI,CAAC,0BAA0B,EAAE,aAAa,GAAG,eAAe,CAAC,EACvE,eAAe,EAAE,sBAAsB,GACtC,kBAAkB,CAKpB;AAED,qBAAa,mBAAmB;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqC;IACzD,OAAO,CAAC,IAAI,CAAuD;IACnE,OAAO,CAAC,KAAK,CAAQ;IACrB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAS;IAEvB,OAAO;IAIP;;;;;;;;OAQG;WACW,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,GAAG,mBAAmB;IAoBhG;;;;OAIG;YACW,eAAe;IAc7B;;OAEG;IACI,KAAK,IAAI,IAAI;IAQpB,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,IAAI;IASZ,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,cAAc;IAMtB;;;;;;;;;;OAUG;IACU,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB/E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAInC,WAAW,IAAI,OAAO;IAI7B;;OAEG;IACI,KAAK,IAAI,IAAI;CAMrB"}

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/dist/types/wrappers/index.d.ts

@@ -1,3 +1,3 @@
 export { withAssembly } from "./with-assembly.js";
-export type { WithAssemblyOptions } from "./with-assembly.js";
+export type { OpControl, WithAssemblyOptions } from "./with-assembly.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/wrappers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/wrappers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/wrappers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/types/wrappers/with-assembly.d.ts

@@ -1,9 +1,34 @@
 import type { GatewayClient } from "../gateway/client.js";
 import type { ToolMap } from "../types/tool-map.js";
+/**
+ * Narrow seam onto the live op-control consumer (AAASM-3491).
+ *
+ * The wrapper only needs to *wait until an op is runnable* — a pause blocks
+ * here cooperatively, a terminate rejects with {@link OpTerminatedError}.
+ * Depending on this strip rather than the concrete `OpControlSubscriber` keeps
+ * the wrapper decoupled from the gRPC transport and lets tests drive it without
+ * a live stream; the real `OpControlSubscriber` satisfies it structurally. This
+ * mirrors the Python companion's `build_governance_interceptor(op_control=...)`
+ * seam.
+ */
+export interface OpControl {
+    waitForOp(opId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+}
 export interface WithAssemblyOptions {
     gatewayClient: GatewayClient;
     agentId?: string;
     approvalTimeoutMs?: number;
+    /**
+     * Live op-control consumer. When supplied, the gateway kill switch
+     * (AAASM-3491) is honored *in this tool path*: before the pre-exec gateway
+     * check, a terminated op fast-fails the call and a paused op blocks
+     * cooperatively until the gateway resumes it. Optional — without it the tool
+     * path behaves exactly as before (gateway check + approval only), and op
+     * control reaches the agent solely via the native runtime's own stream.
+     */
+    opControl?: OpControl;
 }
 export declare function withAssembly<TTool, TTools extends ToolMap<TTool>>(tools: TTools, options: WithAssemblyOptions): TTools;
 //# sourceMappingURL=with-assembly.d.ts.map

package/dist/types/wrappers/with-assembly.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-assembly.d.ts","sourceRoot":"","sources":["../../../src/wrappers/with-assembly.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AA+GD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,KAAK,CAAC,EAC/D,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,GAC3B,MAAM,CAKR"}
+{"version":3,"file":"with-assembly.d.ts","sourceRoot":"","sources":["../../../src/wrappers/with-assembly.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAsKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,SAAS,OAAO,CAAC,KAAK,CAAC,EAC/D,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,mBAAmB,GAC3B,MAAM,CAKR"}

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

@@ -15,8 +15,15 @@ export declare class ClientHandle {
  * Socket resolution, the background IPC thread, and the wire codec are all
  * delegated to `aa-sdk-client`; this shim only validates the argument and
  * wraps the resulting client.
+ *
+ * `agentId` is the agent identity the background thread signs the runtime
+ * session handshake with (AAASM-3587). `sdkVersion` is the user-facing npm
+ * package version (`@agent-assembly/sdk`) the JS layer forwards so it — not the
+ * shared `aa-sdk-client` crate version — is what gets signed into the handshake
+ * proof (AAASM-3683); `undefined` falls back to the crate version (no
+ * regression vs AAASM-3666).
  */
-export declare function connect(socketPath: string): Promise<ClientHandle>
+export declare function connect(socketPath: string, agentId?: string | undefined | null, sdkVersion?: string | undefined | null): Promise<ClientHandle>
 
 /**
  * Shut down the session and join the background IPC thread.
@@ -27,6 +34,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.5",
   "description": "TypeScript SDK for Agent Assembly",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,12 +30,24 @@
   },
   "peerDependencies": {
     "@langchain/core": ">=0.3.0",
+    "@langchain/langgraph": ">=1.0.0",
+    "ai": ">=5.0.0",
+    "@mastra/core": ">=0.20.0",
     "@openai/agents": ">=0.1.0"
   },
   "peerDependenciesMeta": {
     "@langchain/core": {
       "optional": true
     },
+    "@langchain/langgraph": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "@mastra/core": {
+      "optional": true
+    },
     "@openai/agents": {
       "optional": true
     }
@@ -46,6 +58,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.9.1",
     "@vitest/coverage-v8": "^3.2.6",
+    "ai": "^6.0.0",
     "blocked-at": "^1.2.0",
     "eslint": "^10.4.1",
     "grpc-tools": "^1.13.1",
@@ -64,10 +77,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.5",
+    "@agent-assembly/runtime-darwin-x64": "0.0.1-beta.5",
+    "@agent-assembly/runtime-linux-arm64": "0.0.1-beta.5",
+    "@agent-assembly/runtime-linux-x64": "0.0.1-beta.5"
   },
   "files": [
     "dist/",