@agent-assembly/sdk 0.0.1-alpha.3

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

@@ -0,0 +1,85 @@
+/**
+ * Gateway → SDK op-control consumer (AAASM-1422 PR-F / AAASM-1655).
+ *
+ * Subscribes to `PolicyService.OpControlStream` and exposes a per-`op_id`
+ * cooperative-pause / fast-fail-terminate state machine through
+ * {@link OpControlSubscriber.waitForOp}.
+ *
+ * State machine per op_id:
+ * - `OP_CONTROL_SIGNAL_PAUSE`     → `waitForOp` blocks until RESUME arrives.
+ * - `OP_CONTROL_SIGNAL_RESUME`    → `waitForOp` resolves immediately.
+ * - `OP_CONTROL_SIGNAL_TERMINATE` → `waitForOp` rejects with `OpTerminatedError`.
+ *
+ * Signals that arrive for an `op_id` no one is currently awaiting are
+ * buffered into the per-op slot so the next `waitForOp` sees them.
+ *
+ * Out of scope for PR-F (deferred):
+ *   - Reconnection / heartbeat on stream close (caller observes
+ *     `streamAlive` and re-instantiates if desired).
+ *   - Auto-wiring into the existing `GatewayClient` / adapter hooks
+ *     (separate sub-task when the adapter surface is stable).
+ */
+import { type ChannelCredentials, type ClientReadableStream } from "@grpc/grpc-js";
+import type { AgentId } from "./proto/generated/common.js";
+import { OpControlMessage } from "./proto/generated/policy.js";
+/** Strip of the gRPC stub method the subscriber actually needs. Lets tests
+ * mock the gRPC layer without standing up a server.
+ */
+export interface OpControlClient {
+    opControlStream: (request: {
+        agentId?: AgentId;
+    }) => ClientReadableStream<OpControlMessage>;
+    close?: () => void;
+}
+export interface OpControlSubscriberOptions {
+    /** Composite identity of the subscribing agent. */
+    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.
+     */
+    credentials?: ChannelCredentials;
+    /** Test seam — when supplied, skips opening a real gRPC channel and uses
+     * this client directly. Used by the vitest tests.
+     */
+    clientFactory?: () => OpControlClient;
+}
+export declare class OpControlSubscriber {
+    private readonly client;
+    private readonly agent;
+    private readonly ops;
+    private call;
+    private alive;
+    private constructor();
+    /** Open the gRPC channel + subscription stream and start the reader. */
+    static connect(gatewayUrl: string, opts: OpControlSubscriberOptions): OpControlSubscriber;
+    /** Open the stream and wire reader handlers. Public so tests can call
+     * directly after constructing with a hand-rolled client.
+     */
+    start(): void;
+    private dispatch;
+    private slot;
+    private flushResolvers;
+    private markStreamDead;
+    /**
+     * Block until `opId` is runnable, or reject on terminate.
+     *
+     * Resolves immediately when the op is not currently paused. When paused,
+     * waits up to `timeoutMs` for a resume signal. Rejects with
+     * {@link OpTerminatedError} if the op has been (or becomes) terminated.
+     *
+     * A timeout resolves normally — the caller can inspect {@link isPaused}
+     * or retry. Matches the cooperative-pause expectation in the architecture
+     * doc (the SDK yields, it doesn't deadline-enforce).
+     */
+    waitForOp(opId: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    isPaused(opId: string): boolean;
+    isTerminated(opId: string): boolean;
+    streamAlive(): boolean;
+    /** Cancel the stream and clean up. */
+    close(): void;
+}
+//# sourceMappingURL=op-control.d.ts.map

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

@@ -0,0 +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"}

package/dist/types/proto/generated/common.d.ts

@@ -0,0 +1,90 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+export declare const protobufPackage = "assembly.common.v1";
+/**
+ * Decision is the outcome of a policy evaluation. Used by policy.proto and
+ * mirrored in audit.proto to keep audit self-contained.
+ */
+export declare enum Decision {
+    DECISION_UNSPECIFIED = 0,
+    /** ALLOW - Action is permitted immediately. */
+    ALLOW = 1,
+    /** DENY - Action is blocked; no further recourse. */
+    DENY = 2,
+    /** PENDING - Action is held — a human reviewer must approve or reject it. */
+    PENDING = 3,
+    /** REDACT - Action is permitted but sensitive fields must be redacted first. */
+    REDACT = 4,
+    UNRECOGNIZED = -1
+}
+export declare function decisionFromJSON(object: any): Decision;
+export declare function decisionToJSON(object: Decision): string;
+/**
+ * ActionType classifies what kind of operation the agent is attempting.
+ * Drives both policy rule matching and audit event categorisation.
+ */
+export declare enum ActionType {
+    ACTION_UNSPECIFIED = 0,
+    /** LLM_CALL - Call a large-language model (e.g. GPT-4o, Claude, Gemini). */
+    LLM_CALL = 1,
+    /** TOOL_CALL - Invoke a tool or MCP server function. */
+    TOOL_CALL = 2,
+    /** FILE_OPERATION - Read, write, delete, or create a local file. */
+    FILE_OPERATION = 3,
+    /** NETWORK_CALL - Make an outbound network request. */
+    NETWORK_CALL = 4,
+    /** PROCESS_EXEC - Execute a subprocess. */
+    PROCESS_EXEC = 5,
+    /** AGENT_SPAWN - Spawn a child agent. */
+    AGENT_SPAWN = 6,
+    UNRECOGNIZED = -1
+}
+export declare function actionTypeFromJSON(object: any): ActionType;
+export declare function actionTypeToJSON(object: ActionType): string;
+/** RiskTier classifies an agent or policy by the risk level it operates at. */
+export declare enum RiskTier {
+    RISK_UNSPECIFIED = 0,
+    /** LOW - Low risk: log-only enforcement; no blocking. */
+    LOW = 1,
+    /** MEDIUM - Medium risk: block-and-optionally-approve enforcement. */
+    MEDIUM = 2,
+    /** HIGH - High risk: always block; human review mandatory. */
+    HIGH = 3,
+    /** CRITICAL - Critical risk: immediate kill + incident escalation. */
+    CRITICAL = 4,
+    UNRECOGNIZED = -1
+}
+export declare function riskTierFromJSON(object: any): RiskTier;
+export declare function riskTierToJSON(object: RiskTier): string;
+/**
+ * AgentId is a composite identity used in every gRPC message.
+ * Using a message (not a flat string) lets the gateway enforce org/team scoping
+ * and issue scoped credentials without changing downstream message shapes.
+ */
+export interface AgentId {
+    /** Organisation identifier. */
+    orgId: string;
+    /** Team within the organisation. */
+    teamId: string;
+    /** The agent's own unique ID (DID-style; assigned at registration). */
+    agentId: string;
+}
+/** Timestamp uses Unix milliseconds for precision without proto well-known type imports. */
+export interface Timestamp {
+    unixMs: number;
+}
+export declare const AgentId: MessageFns<AgentId>;
+export declare const Timestamp: MessageFns<Timestamp>;
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+export {};
+//# sourceMappingURL=common.d.ts.map

package/dist/types/proto/generated/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../../src/proto/generated/common.ts"],"names":[],"mappings":"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"}

package/dist/types/proto/generated/policy.d.ts

@@ -0,0 +1,298 @@
+import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
+import { type CallOptions, type ChannelCredentials, Client, type ClientOptions, type ClientReadableStream, type ClientUnaryCall, type handleServerStreamingCall, type handleUnaryCall, type Metadata, type ServiceError, type UntypedServiceImplementation } from "@grpc/grpc-js";
+import { ActionType, AgentId, Decision } from "./common.js";
+export declare const protobufPackage = "assembly.policy.v1";
+/**
+ * OpControlSignal classifies the lifecycle action the gateway is pushing to
+ * the SDK. Mirrors the OpsRegistry transitions in aa-gateway/src/ops/mod.rs.
+ */
+export declare enum OpControlSignal {
+    /** OP_CONTROL_SIGNAL_UNSPECIFIED - Default — never wired; treated as a malformed message by the SDK. */
+    OP_CONTROL_SIGNAL_UNSPECIFIED = 0,
+    /**
+     * OP_CONTROL_SIGNAL_PAUSE - Operator paused the op via POST /api/v1/ops/{id}/pause. SDK should
+     * cooperatively yield at the next interruption point and block on resume.
+     */
+    OP_CONTROL_SIGNAL_PAUSE = 1,
+    /** OP_CONTROL_SIGNAL_RESUME - Operator resumed the op via POST /api/v1/ops/{id}/resume. SDK unblocks. */
+    OP_CONTROL_SIGNAL_RESUME = 2,
+    /**
+     * OP_CONTROL_SIGNAL_TERMINATE - Operator (or policy deny) terminated the op. SDK fast-fails the in-flight
+     * action with an OpTerminatedError.
+     */
+    OP_CONTROL_SIGNAL_TERMINATE = 3,
+    UNRECOGNIZED = -1
+}
+export declare function opControlSignalFromJSON(object: any): OpControlSignal;
+export declare function opControlSignalToJSON(object: OpControlSignal): string;
+export interface CheckActionRequest {
+    /** Composite identity of the agent requesting the check. */
+    agentId: AgentId | undefined;
+    /** Credential token issued at registration; validated on every call. */
+    credentialToken: string;
+    /** Run-level trace ID for distributed tracing correlation. */
+    traceId: string;
+    /** Action-level span ID. */
+    spanId: string;
+    /** High-level action category — determines which policy rules are evaluated. */
+    actionType: ActionType;
+    /** Detailed context for the specific action type. */
+    context: ActionContext | undefined;
+}
+/**
+ * ActionContext carries type-specific details for the action under evaluation.
+ * Exactly one field must be set; the populated field must match action_type.
+ */
+export interface ActionContext {
+    llmCall?: LLMCallContext | undefined;
+    toolCall?: ToolCallContext | undefined;
+    fileOp?: FileOpContext | undefined;
+    networkCall?: NetworkCallContext | undefined;
+    processExec?: ProcessExecContext | undefined;
+}
+/** LLMCallContext carries details about a call to a large-language model. */
+export interface LLMCallContext {
+    /** Model identifier (e.g. "gpt-4o", "claude-3-5-sonnet", "gemini-1.5-pro"). */
+    model: string;
+    /** Estimated prompt token count (pre-execution estimate from the SDK layer). */
+    promptTokens: number;
+    /** Whether the SDK-layer PII scan flagged sensitive data in the prompt. */
+    containsPii: boolean;
+}
+/** ToolCallContext carries details about a tool or MCP server invocation. */
+export interface ToolCallContext {
+    /** Registered tool name (e.g. "web_search", "run_python"). */
+    toolName: string;
+    /** Source system ("mcp", "langchain", "function"). */
+    toolSource: string;
+    /** JSON-encoded argument map; policy engine can inspect individual fields. */
+    argsJson: Buffer;
+    /** Target URL if the tool makes an HTTP request. */
+    targetUrl: string;
+}
+/** FileOpContext carries details about a filesystem operation. */
+export interface FileOpContext {
+    /** Operation type: "read", "write", "delete", or "create". */
+    operation: string;
+    /** Absolute path of the file being accessed. */
+    path: string;
+    /** Whether the eBPF layer flagged this path as sensitive (e.g. /etc, ~/.ssh). */
+    isSensitivePath: boolean;
+}
+/** NetworkCallContext carries details about an outbound network request. */
+export interface NetworkCallContext {
+    /** Target hostname. */
+    host: string;
+    /** Target port. */
+    port: number;
+    /** Protocol: "https", "grpc", "ws", "tcp". */
+    protocol: string;
+    /** Whether the target host is in the org-level network allowlist. */
+    inAllowlist: boolean;
+}
+/** ProcessExecContext carries details about a subprocess execution attempt. */
+export interface ProcessExecContext {
+    /** Command to execute. */
+    command: string;
+    /** Arguments passed to the command. */
+    args: string[];
+}
+/** CheckActionResponse is the policy engine's verdict for the submitted action. */
+export interface CheckActionResponse {
+    /** The enforcement decision. */
+    decision: Decision;
+    /** Human-readable explanation of the decision (included in audit log). */
+    reason: string;
+    /** Identifier of the policy rule that triggered this decision. */
+    policyRule: string;
+    /** Populated only when decision = PENDING; identifies the approval queue item. */
+    approvalId: string;
+    /** Populated only when decision = REDACT; describes which fields to redact. */
+    redact: RedactInstructions | undefined;
+    /** Gateway decision latency in microseconds — used for p99 SLO monitoring. */
+    decisionLatencyUs: number;
+}
+/** RedactInstructions lists the fields that must be redacted before the action proceeds. */
+export interface RedactInstructions {
+    rules: RedactRule[];
+}
+/** RedactRule specifies one field redaction to apply. */
+export interface RedactRule {
+    /** JSONPath of the field to redact (e.g. "$.args.api_key"). */
+    fieldPath: string;
+    /** Replacement string (e.g. "[REDACTED]", "[PII]"). */
+    replacement: string;
+}
+/** BatchCheckRequest pre-warms the policy cache with a set of anticipated actions. */
+export interface BatchCheckRequest {
+    requests: CheckActionRequest[];
+}
+/** BatchCheckResponse returns one verdict per submitted request, in order. */
+export interface BatchCheckResponse {
+    responses: CheckActionResponse[];
+}
+/**
+ * OpControlSubscribeRequest is the unary half of OpControlStream — the SDK
+ * opens the stream keyed by its own agent id; the gateway sends only the
+ * messages whose op_id belongs to that agent.
+ */
+export interface OpControlSubscribeRequest {
+    /**
+     * Composite identity of the subscribing agent. Matches the agent_id on
+     * its CheckActionRequests so the gateway can filter the broadcast.
+     */
+    agentId: AgentId | undefined;
+}
+/**
+ * OpControlMessage is one push from the gateway over the OpControlStream.
+ * The SDK routes by op_id; sequence is a monotonic counter the SDK uses
+ * for at-least-once delivery dedup if the channel reconnects.
+ */
+export interface OpControlMessage {
+    /**
+     * Stable identifier of the op — "{trace_id}:{span_id}", same form the
+     * dashboard uses to key live-ops rows.
+     */
+    opId: string;
+    /** The lifecycle signal to apply. */
+    signal: OpControlSignal;
+    /**
+     * Per-publisher monotonic sequence number. Restarts at 0 each gateway
+     * boot; SDK consumers should treat it as advisory, not as a global
+     * ordering guarantee across publishers.
+     */
+    sequence: number;
+}
+export declare const CheckActionRequest: MessageFns<CheckActionRequest>;
+export declare const ActionContext: MessageFns<ActionContext>;
+export declare const LLMCallContext: MessageFns<LLMCallContext>;
+export declare const ToolCallContext: MessageFns<ToolCallContext>;
+export declare const FileOpContext: MessageFns<FileOpContext>;
+export declare const NetworkCallContext: MessageFns<NetworkCallContext>;
+export declare const ProcessExecContext: MessageFns<ProcessExecContext>;
+export declare const CheckActionResponse: MessageFns<CheckActionResponse>;
+export declare const RedactInstructions: MessageFns<RedactInstructions>;
+export declare const RedactRule: MessageFns<RedactRule>;
+export declare const BatchCheckRequest: MessageFns<BatchCheckRequest>;
+export declare const BatchCheckResponse: MessageFns<BatchCheckResponse>;
+export declare const OpControlSubscribeRequest: MessageFns<OpControlSubscribeRequest>;
+export declare const OpControlMessage: MessageFns<OpControlMessage>;
+/**
+ * PolicyService handles path ② (runtime → gateway) — the hot path for every
+ * agent action. Target latency: < 5 ms p99.
+ *
+ * Consumed by: aa-runtime/src/gateway_client.rs (client side)
+ *              aa-gateway/src/policy_engine.rs   (server side)
+ */
+export type PolicyServiceService = typeof PolicyServiceService;
+export declare const PolicyServiceService: {
+    /**
+     * CheckAction evaluates a single action before the agent dispatches it.
+     * Called on every intercepted action — must be as fast as possible.
+     */
+    readonly checkAction: {
+        readonly path: "/assembly.policy.v1.PolicyService/CheckAction";
+        readonly requestStream: false;
+        readonly responseStream: false;
+        readonly requestSerialize: (value: CheckActionRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => CheckActionRequest;
+        readonly responseSerialize: (value: CheckActionResponse) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => CheckActionResponse;
+    };
+    /**
+     * BatchCheck pre-warms the policy cache for a set of anticipated actions.
+     * Called at agent startup or when entering a new task context.
+     */
+    readonly batchCheck: {
+        readonly path: "/assembly.policy.v1.PolicyService/BatchCheck";
+        readonly requestStream: false;
+        readonly responseStream: false;
+        readonly requestSerialize: (value: BatchCheckRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => BatchCheckRequest;
+        readonly responseSerialize: (value: BatchCheckResponse) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => BatchCheckResponse;
+    };
+    /**
+     * OpControlStream is the gateway → SDK push channel for op-lifecycle
+     * signals (pause / resume / terminate). The SDK opens the stream once
+     * per agent process at startup; the gateway pushes one OpControlMessage
+     * per OpsRegistry transition matching the subscriber's agent_id. See
+     * AAASM-1653 (PR-D of AAASM-1422); SDK-side consumers ship in PR-E
+     * (Python), PR-F (Node), and PR-G (Go).
+     */
+    readonly opControlStream: {
+        readonly path: "/assembly.policy.v1.PolicyService/OpControlStream";
+        readonly requestStream: false;
+        readonly responseStream: true;
+        readonly requestSerialize: (value: OpControlSubscribeRequest) => Buffer;
+        readonly requestDeserialize: (value: Buffer) => OpControlSubscribeRequest;
+        readonly responseSerialize: (value: OpControlMessage) => Buffer;
+        readonly responseDeserialize: (value: Buffer) => OpControlMessage;
+    };
+};
+export interface PolicyServiceServer extends UntypedServiceImplementation {
+    /**
+     * CheckAction evaluates a single action before the agent dispatches it.
+     * Called on every intercepted action — must be as fast as possible.
+     */
+    checkAction: handleUnaryCall<CheckActionRequest, CheckActionResponse>;
+    /**
+     * BatchCheck pre-warms the policy cache for a set of anticipated actions.
+     * Called at agent startup or when entering a new task context.
+     */
+    batchCheck: handleUnaryCall<BatchCheckRequest, BatchCheckResponse>;
+    /**
+     * OpControlStream is the gateway → SDK push channel for op-lifecycle
+     * signals (pause / resume / terminate). The SDK opens the stream once
+     * per agent process at startup; the gateway pushes one OpControlMessage
+     * per OpsRegistry transition matching the subscriber's agent_id. See
+     * AAASM-1653 (PR-D of AAASM-1422); SDK-side consumers ship in PR-E
+     * (Python), PR-F (Node), and PR-G (Go).
+     */
+    opControlStream: handleServerStreamingCall<OpControlSubscribeRequest, OpControlMessage>;
+}
+export interface PolicyServiceClient extends Client {
+    /**
+     * CheckAction evaluates a single action before the agent dispatches it.
+     * Called on every intercepted action — must be as fast as possible.
+     */
+    checkAction(request: CheckActionRequest, callback: (error: ServiceError | null, response: CheckActionResponse) => void): ClientUnaryCall;
+    checkAction(request: CheckActionRequest, metadata: Metadata, callback: (error: ServiceError | null, response: CheckActionResponse) => void): ClientUnaryCall;
+    checkAction(request: CheckActionRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: CheckActionResponse) => void): ClientUnaryCall;
+    /**
+     * BatchCheck pre-warms the policy cache for a set of anticipated actions.
+     * Called at agent startup or when entering a new task context.
+     */
+    batchCheck(request: BatchCheckRequest, callback: (error: ServiceError | null, response: BatchCheckResponse) => void): ClientUnaryCall;
+    batchCheck(request: BatchCheckRequest, metadata: Metadata, callback: (error: ServiceError | null, response: BatchCheckResponse) => void): ClientUnaryCall;
+    batchCheck(request: BatchCheckRequest, metadata: Metadata, options: Partial<CallOptions>, callback: (error: ServiceError | null, response: BatchCheckResponse) => void): ClientUnaryCall;
+    /**
+     * OpControlStream is the gateway → SDK push channel for op-lifecycle
+     * signals (pause / resume / terminate). The SDK opens the stream once
+     * per agent process at startup; the gateway pushes one OpControlMessage
+     * per OpsRegistry transition matching the subscriber's agent_id. See
+     * AAASM-1653 (PR-D of AAASM-1422); SDK-side consumers ship in PR-E
+     * (Python), PR-F (Node), and PR-G (Go).
+     */
+    opControlStream(request: OpControlSubscribeRequest, options?: Partial<CallOptions>): ClientReadableStream<OpControlMessage>;
+    opControlStream(request: OpControlSubscribeRequest, metadata?: Metadata, options?: Partial<CallOptions>): ClientReadableStream<OpControlMessage>;
+}
+export declare const PolicyServiceClient: {
+    new (address: string, credentials: ChannelCredentials, options?: Partial<ClientOptions>): PolicyServiceClient;
+    service: typeof PolicyServiceService;
+    serviceName: string;
+};
+type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
+export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : Partial<T>;
+export interface MessageFns<T> {
+    encode(message: T, writer?: BinaryWriter): BinaryWriter;
+    decode(input: BinaryReader | Uint8Array, length?: number): T;
+    fromJSON(object: any): T;
+    toJSON(message: T): unknown;
+    create(base?: DeepPartial<T>): T;
+    fromPartial(object: DeepPartial<T>): T;
+}
+export {};
+//# sourceMappingURL=policy.d.ts.map

package/dist/types/proto/generated/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../../src/proto/generated/policy.ts"],"names":[],"mappings":"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"}

package/dist/types/runtime.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime auto-detection and lifecycle management for the `aasm` sidecar
+ * (F115 / AAASM-1205).
+ *
+ * The `initAssembly()` exported here is intentionally NOT re-exported from
+ * `@agent-assembly/sdk` at the top level: the existing gateway-based
+ * `initAssembly(config)` keeps its meaning. Opt in to the runtime-managed
+ * flow with `import { initAssembly } from "@agent-assembly/sdk/runtime"`.
+ */
+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";
+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";
+/** npm sub-package name for the bundled platform binary (esbuild pattern). */
+export declare const RUNTIME_SUBPACKAGE: string;
+export declare const INSTALL_HINT: string;
+/**
+ * Locate the `aasm` binary across the 4 supported install paths.
+ *
+ * Search order: `$PATH` (Homebrew, cargo install) → `~/.local/bin/aasm`
+ * (curl installer) → `node_modules/@agent-assembly/runtime-{platform}-{arch}/bin/aasm`
+ * (npm optionalDependency) → `/usr/local/bin/aasm` (Docker base image).
+ * Returns the first existing match, or `null` when none exist.
+ */
+export declare function findAasmBinary(): string | null;
+/**
+ * Resolve to `true` iff a local TCP listener accepts a connect on
+ * `host:port` within 100 ms. Any socket error (refused, timeout,
+ * unreachable) resolves to `false` and is treated as no sidecar.
+ */
+export declare function isRunning(port?: number, host?: string): Promise<boolean>;
+/**
+ * Spawn `aasm serve --port <port>` as a detached background subprocess.
+ *
+ * Stdout/stderr are appended to `<logDir>/.aasm-runtime.log` (default
+ * `process.cwd()`) so the sidecar outlives the parent. `detached: true`
+ * + `child.unref()` releases the event loop so the Node process can
+ * exit independently of the sidecar.
+ */
+export declare function startRuntime(binaryPath: string, port?: number, logDir?: string): ChildProcess;
+/**
+ * Ensure the local `aasm` sidecar is running, starting it if necessary.
+ *
+ * Lifecycle per F115 / AAASM-1205:
+ *  1. Probe `host:port` via {@link isRunning}; return early if already up.
+ *  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.
+ *
+ * Throws `Error` with {@link INSTALL_HINT} when no binary is found.
+ */
+export declare function initAssembly(agentId?: string, port?: number): Promise<void>;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,47 @@
+import type { GatewayClient } from "../gateway/client.js";
+import type { LangChainAdapterConfig } from "./langchain-adapter.js";
+import type { AssemblyMode } from "./assembly-mode.js";
+import type { EnforcementMode } from "./enforcement-mode.js";
+export interface AssemblyConfig {
+    /**
+     * Gateway URL. When omitted, ``initAssembly`` resolves it via
+     * AAASM_GATEWAY_URL, ~/.aasm/config.yaml, or the local default
+     * (http://localhost:7391, auto-started if absent). See
+     * ``agent_assembly/core/gateway-resolver`` for the precedence chain.
+     */
+    gatewayUrl?: string;
+    /**
+     * API key. When omitted, ``initAssembly`` resolves it via
+     * AAASM_API_KEY, the config file, or defaults to an empty string
+     * (local mode is unauth-accepting).
+     */
+    apiKey?: string;
+    agentId?: string;
+    mode?: AssemblyMode;
+    gatewayClient?: GatewayClient;
+    langchain?: LangChainAdapterConfig;
+    /** ID of the parent agent that delegated work to this agent. */
+    parentAgentId?: string;
+    /** Team this agent belongs to for budget and policy scoping. */
+    teamId?: string;
+    /**
+     * Human-readable explanation for why this agent was delegated to.
+     * Must be ≤ 256 characters; throws `RangeError` otherwise.
+     */
+    delegationReason?: string;
+    /** Name of the tool that spawned this agent, if applicable. */
+    spawnedByTool?: string;
+    /**
+     * Per-agent governance posture override sent to the gateway at registration.
+     *
+     * When omitted, the field is left off the registration body and the gateway
+     * applies its server-side default (live `"enforce"`) — the pre-feature wire
+     * shape is preserved. Pass `"observe"` to register this agent in dry-run /
+     * sandbox mode (every action proceeds; the gateway records would-be
+     * violations as shadow audit events surfaced by `aa audit list --dry-run-only`).
+     *
+     * Unknown string values are rejected at runtime with a `RangeError`.
+     */
+    enforcementMode?: EnforcementMode;
+}
+//# sourceMappingURL=assembly-config.d.ts.map

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

@@ -0,0 +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;;;;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"}

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

@@ -0,0 +1,12 @@
+import type { EnforcementMode } from "./enforcement-mode.js";
+export interface AssemblyContext {
+    readonly activeAdapters: readonly string[];
+    readonly parentAgentId?: string;
+    readonly teamId?: string;
+    readonly delegationReason?: string;
+    readonly spawnedByTool?: string;
+    /** Echo of the per-agent governance posture sent at registration, when set. */
+    readonly enforcementMode?: EnforcementMode;
+    shutdown: () => Promise<void>;
+}
+//# sourceMappingURL=assembly-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assembly-context.d.ts","sourceRoot":"","sources":["../../../src/types/assembly-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;IAC3C,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B"}

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

@@ -0,0 +1,2 @@
+export type AssemblyMode = "auto" | "sdk-only" | "grpc-sidecar" | "napi-inprocess";
+//# sourceMappingURL=assembly-mode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assembly-mode.d.ts","sourceRoot":"","sources":["../../../src/types/assembly-mode.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,UAAU,GAAG,cAAc,GAAG,gBAAgB,CAAC"}