@grackle-ai/adapter-sdk 0.132.1 → 0.133.0

package/dist/adapter.d.ts

@@ -1,21 +1,25 @@
-import type { Client } from "@connectrpc/connect";
-import type { powerline } from "@grackle-ai/common";
 import type { AdapterLogger } from "./logger.js";
 import type { IHostTransport } from "./host-transport.js";
-/** Type-safe ConnectRPC client for the PowerLine gRPC service. */
-export type PowerLineClient = Client<typeof powerline.GracklePowerLine>;
-/** An active connection to a PowerLine, including the gRPC client and port info. */
+/** An active connection to a PowerLine. */
 export interface PowerLineConnection {
-    client: PowerLineClient;
     environmentId: string;
     port: number;
     /**
-     * Transport-agnostic host interface (AHP HR8c). One instance per connection,
-     * constructed when the connection is established. Consumers use this
-     * instead of touching `client` directly so the HR8d wire-flip is a
-     * swap of one `IHostTransport` impl for another.
+     * Transport-agnostic host interface. Constructed when the connection is
+     * established and used for all session-level operations.
      */
     transport: IHostTransport;
+    /**
+     * Send a liveness probe to the PowerLine. Resolves on success; rejects on
+     * any transport-layer error.
+     */
+    ping(): Promise<void>;
+    /**
+     * Tear down the underlying transport (WebSocket + pending RPCs). Idempotent.
+     * Adapters MUST call this from `disconnect()` to avoid socket leaks —
+     * under HR8d the AHP transport is persistent and only closes here.
+     */
+    close(): Promise<void>;
 }
 /** Progress event emitted during environment provisioning. */
 export interface ProvisionEvent {

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,SAAS,CAAC,gBAAgB,CAAC,CAAC;AAExE,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,SAAS,EAAE,cAAc,CAAC;CAC3B;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb,0DAA0D;IAC1D,SAAS,CACP,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,GACrB,cAAc,CAAC,cAAc,CAAC,CAAC;IAClC,+EAA+E;IAC/E,OAAO,CACL,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC,uFAAuF;IACvF,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,gFAAgF;IAChF,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,gEAAgE;IAChE,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,0DAA0D;IAC1D,WAAW,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,gGAAgG;IAChG,SAAS,CAAC,CACR,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,GACrB,cAAc,CAAC,cAAc,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAuB,oBAAoB,CACzC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,OAAO,EACrB,KAAK,GAAE,OAAe,EACtB,MAAM,GAAE,aAA6B,GACpC,cAAc,CAAC,cAAc,CAAC,CAgBhC"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IAEb,0DAA0D;IAC1D,SAAS,CACP,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,GACrB,cAAc,CAAC,cAAc,CAAC,CAAC;IAClC,+EAA+E;IAC/E,OAAO,CACL,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChC,uFAAuF;IACvF,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,gFAAgF;IAChF,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,gEAAgE;IAChE,OAAO,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,0DAA0D;IAC1D,WAAW,CAAC,UAAU,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/D,gGAAgG;IAChG,SAAS,CAAC,CACR,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,GACrB,cAAc,CAAC,cAAc,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,wBAAuB,oBAAoB,CACzC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,OAAO,EACrB,KAAK,GAAE,OAAe,EACtB,MAAM,GAAE,aAA6B,GACpC,cAAc,CAAC,cAAc,CAAC,CAgBhC"}

package/dist/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAmErD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,oBAAoB,CACzC,aAAqB,EACrB,OAA2B,EAC3B,MAA+B,EAC/B,cAAsB,EACtB,YAAqB,EACrB,QAAiB,KAAK,EACtB,SAAwB,aAAa;IAErC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC,KAAK,IAAI,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;YAChE,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;gBACrC,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,EAAE,kDAAkD,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAwErD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,oBAAoB,CACzC,aAAqB,EACrB,OAA2B,EAC3B,MAA+B,EAC/B,cAAsB,EACtB,YAAqB,EACrB,QAAiB,KAAK,EACtB,SAAwB,aAAa;IAErC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,CAAC,KAAK,IAAI,YAAY,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;YAChE,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,iBAAiB,EAAE,CAAC;gBACrC,MAAM,GAAG,CAAC;YACZ,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,EAAE,kDAAkD,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IACD,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,KAAK,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/ahp-host-transport.d.ts

@@ -0,0 +1,124 @@
+/**
+ * AHP-backed implementation of {@link IHostTransport} (AHP HR8d / #1336).
+ *
+ * Owns one `AhpClientSocket` per `PowerLineConnection` and routes
+ * inbound `action` notifications to per-session queues via the
+ * {@link reverseMapAction} reverse mapper. Downstream consumers in
+ * `@grackle-ai/core` continue to read `envelope.event` (the synthesized
+ * AgentEventFields), so no consumer code changes — only the wire format does.
+ *
+ * Wire-protocol summary (per #1336):
+ *
+ * - `createSession` (spawn) → AHP `createSession` + `subscribe`
+ * - `createSession` (reanimate) → same, with `config.resumeFromRuntimeSessionId`
+ * - `dispatchInput` → AHP `dispatchAction` notification with `SessionTurnStartedAction`
+ * - `dispose` (kill) → AHP `disposeSession`
+ * - `listSessions` → AHP `listSessions`
+ * - `authenticate` → AHP `authenticate`
+ *
+ * Drain semantics (Option E): PowerLine replays parked events as `action`
+ * notifications immediately after the `subscribe` response, so the consumer
+ * receives them via the same stream — no separate `drainBuffered` RPC.
+ *
+ * @module ahp-host-transport
+ */
+import type { AhpNotification } from "@grackle-ai/ahp";
+import { AhpClientSocket } from "@grackle-ai/ahp-transport";
+import type { AuthenticateParams, CreateSessionParams, CreateSessionResult, HostSessionInfo, IHostTransport, ReanimateParams, ServerActionEnvelope } from "./host-transport.js";
+/**
+ * AHP-backed {@link IHostTransport} for a single environment.
+ *
+ * Lifecycle: one instance per `PowerLineConnection`. Owns one
+ * `AhpClientSocket`; multiplexes session subscriptions over it.
+ *
+ * Construct via {@link createAhpHostTransport} (in `./connect.ts`) which
+ * handles the `socket.open()` handshake. Tests can construct directly with
+ * a pre-opened socket.
+ */
+export declare class AhpHostTransport implements IHostTransport {
+    private readonly socket;
+    private readonly sessions;
+    private nextClientSeq;
+    /**
+     * Construct an AhpHostTransport over a pre-opened `AhpClientSocket`.
+     * The socket MUST already have completed its `initialize` handshake.
+     *
+     * @param socket - The AHP client socket, opened and connected.
+     */
+    constructor(socket: AhpClientSocket);
+    /**
+     * Notification handler that must be supplied to `AhpClientSocket` at
+     * construction time (the socket's `onNotification` option). This is a
+     * static-bound method so it can be passed to the socket constructor.
+     *
+     * Routes inbound `action` notifications to the appropriate per-session
+     * queue, running the reverse mapper to synthesize `AgentEventFields` and
+     * wrapping each into a `ServerActionEnvelope`. Other notification methods
+     * are ignored (no consumers in the wire-only scope of HR8d).
+     *
+     * @param notif - The AHP notification from the wire.
+     */
+    handleNotification(notif: AhpNotification): void;
+    /**
+     * Create a new session via AHP `createSession` + `subscribe`.
+     *
+     * Returns synchronously with the session URI and the live envelope stream.
+     * The actual AHP requests fire in the background; failures push an error
+     * sentinel into the stream and close it (mirroring how gRPC stream errors
+     * surface during iteration).
+     */
+    createSession(params: CreateSessionParams): CreateSessionResult;
+    /**
+     * Reanimate a suspended session. Maps to AHP `createSession` with a
+     * `config.resumeFromRuntimeSessionId` hint that PowerLine interprets as
+     * "spawn a continuation runtime from this prior runtime session."
+     */
+    reanimate(params: ReanimateParams): AsyncIterable<ServerActionEnvelope>;
+    /** Send input text by dispatching a `SessionTurnStartedAction`. */
+    dispatchInput(sessionUri: string, text: string): Promise<void>;
+    /**
+     * Deliver runtime credentials.
+     *
+     * AHP `authenticate` is OAuth-shaped (single `{ resource, token }`) and
+     * Grackle's HR6 authenticate delivers multiple typed tokens (env-var or
+     * file-backed) for one provider. HR8d preserves the AHP-spec wire method
+     * by fanning Grackle's tokens out into N `authenticate` calls. Each call:
+     *
+     * - `resource`: `grackle://provider/{provider}/{name}` — encodes the
+     *   Grackle-side identity. PowerLine recognizes the `grackle://` scheme
+     *   and decodes it.
+     * - `token`: JSON-encoded `{ type, envVar?, filePath?, value }` — carries
+     *   the delivery instructions inside the AHP token field.
+     *
+     * On-spec method, abused field semantics. The contortion is documented in
+     * #1336 and bounded to this single command.
+     */
+    authenticate(params: AuthenticateParams): Promise<void>;
+    /**
+     * Dispose a session via AHP `disposeSession`.
+     *
+     * AHP's `DisposeSessionParams` doesn't carry a `reason` field; the optional
+     * `reason` argument is logged client-side but not delivered to PowerLine.
+     * Acceptable for HR8d — `reason` was informational in the gRPC path too.
+     */
+    dispose(sessionUri: string, _reason?: string): Promise<void>;
+    /** List active sessions via AHP `listSessions`. */
+    listSessions(): Promise<HostSessionInfo[]>;
+    private getOrCreateSession;
+    private closeSession;
+    private runSpawnFlow;
+    private surfaceErrorAndClose;
+}
+/**
+ * Helper to wire {@link AhpHostTransport}'s notification handler into an
+ * `AhpClientSocket` at construction time. The transport's
+ * {@link AhpHostTransport.handleNotification} method must be bound to the
+ * socket BEFORE `socket.open()` so the first inbound `action` notifications
+ * are routed correctly.
+ *
+ * @param transport - The transport whose handler should be bound.
+ * @returns A function suitable for passing as `onNotification` to
+ *   `AhpClientSocket`'s constructor options.
+ */
+export declare function bindNotificationHandler(transport: AhpHostTransport): (n: AhpNotification) => void;
+//# sourceMappingURL=ahp-host-transport.d.ts.map

package/dist/ahp-host-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ahp-host-transport.d.ts","sourceRoot":"","sources":["../src/ahp-host-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAMV,eAAe,EAChB,MAAM,iBAAiB,CAAC;AAQzB,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,KAAK,EACV,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,eAAe,EACf,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AA+F7B;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,aAAa,CAAa;IAElC;;;;;OAKG;gBACgB,MAAM,EAAE,eAAe;IAI1C;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAiBvD;;;;;;;OAOG;IACI,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB;IAStE;;;;OAIG;IACI,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAAC,oBAAoB,CAAC;IA2B9E,mEAAmE;IACtD,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3E;;;;;;;;;;;;;;;;OAgBG;IACU,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBpE;;;;;;OAMG;IACU,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASzE,mDAAmD;IACtC,YAAY,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAevD,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,YAAY;YASN,YAAY;IAmD1B,OAAO,CAAC,oBAAoB;CAS7B;AAsDD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,gBAAgB,GAAG,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,CAEjG"}

package/dist/ahp-host-transport.js

@@ -0,0 +1,413 @@
+/**
+ * AHP-backed implementation of {@link IHostTransport} (AHP HR8d / #1336).
+ *
+ * Owns one `AhpClientSocket` per `PowerLineConnection` and routes
+ * inbound `action` notifications to per-session queues via the
+ * {@link reverseMapAction} reverse mapper. Downstream consumers in
+ * `@grackle-ai/core` continue to read `envelope.event` (the synthesized
+ * AgentEventFields), so no consumer code changes — only the wire format does.
+ *
+ * Wire-protocol summary (per #1336):
+ *
+ * - `createSession` (spawn) → AHP `createSession` + `subscribe`
+ * - `createSession` (reanimate) → same, with `config.resumeFromRuntimeSessionId`
+ * - `dispatchInput` → AHP `dispatchAction` notification with `SessionTurnStartedAction`
+ * - `dispose` (kill) → AHP `disposeSession`
+ * - `listSessions` → AHP `listSessions`
+ * - `authenticate` → AHP `authenticate`
+ *
+ * Drain semantics (Option E): PowerLine replays parked events as `action`
+ * notifications immediately after the `subscribe` response, so the consumer
+ * receives them via the same stream — no separate `drainBuffered` RPC.
+ *
+ * @module ahp-host-transport
+ */
+import { ActionType } from "@grackle-ai/ahp";
+import { newReverseMapperContext, reverseMapAction, } from "@grackle-ai/common";
+const ROOT_CHANNEL = "ahp-root://";
+const SESSION_CHANNEL_PREFIX = "ahp-session:/";
+/** Build the AHP session channel URI for a Grackle session id. */
+function sessionChannel(sessionId) {
+    return `${SESSION_CHANNEL_PREFIX}${sessionId}`;
+}
+/**
+ * Accept either a plain Grackle session id (e.g. `"sess-1"`) or an
+ * already-formed AHP session URI (`"ahp-session:/sess-1"`) and return the
+ * URI form. `IHostTransport`'s `dispatchInput` / `dispose` historically
+ * pass a session id; this helper keeps the boundary forgiving.
+ */
+function toSessionChannel(sessionIdOrUri) {
+    return sessionIdOrUri.startsWith(SESSION_CHANNEL_PREFIX)
+        ? sessionIdOrUri
+        : sessionChannel(sessionIdOrUri);
+}
+/**
+ * Minimal push/pull queue specialized for per-session envelope streaming.
+ * Mirrors `packages/runtime-sdk/src/async-queue.ts:1-48`; inlined here to
+ * avoid a new dep edge on runtime-sdk.
+ *
+ * @internal
+ */
+class EnvelopeQueue {
+    buffer = [];
+    waiters = [];
+    closedFlag = false;
+    push(item) {
+        if (this.closedFlag) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter !== undefined) {
+            waiter(item);
+            return;
+        }
+        this.buffer.push(item);
+    }
+    async shift() {
+        const buffered = this.buffer.shift();
+        if (buffered !== undefined) {
+            return buffered;
+        }
+        if (this.closedFlag) {
+            return undefined;
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    close() {
+        if (this.closedFlag) {
+            return;
+        }
+        this.closedFlag = true;
+        for (const waiter of this.waiters) {
+            waiter(undefined);
+        }
+        this.waiters.length = 0;
+    }
+    get closed() {
+        return this.closedFlag;
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const item = await this.shift();
+            if (item === undefined) {
+                return;
+            }
+            yield item;
+        }
+    }
+}
+/**
+ * AHP-backed {@link IHostTransport} for a single environment.
+ *
+ * Lifecycle: one instance per `PowerLineConnection`. Owns one
+ * `AhpClientSocket`; multiplexes session subscriptions over it.
+ *
+ * Construct via {@link createAhpHostTransport} (in `./connect.ts`) which
+ * handles the `socket.open()` handshake. Tests can construct directly with
+ * a pre-opened socket.
+ */
+export class AhpHostTransport {
+    socket;
+    sessions = new Map();
+    nextClientSeq = 0;
+    /**
+     * Construct an AhpHostTransport over a pre-opened `AhpClientSocket`.
+     * The socket MUST already have completed its `initialize` handshake.
+     *
+     * @param socket - The AHP client socket, opened and connected.
+     */
+    constructor(socket) {
+        this.socket = socket;
+    }
+    /**
+     * Notification handler that must be supplied to `AhpClientSocket` at
+     * construction time (the socket's `onNotification` option). This is a
+     * static-bound method so it can be passed to the socket constructor.
+     *
+     * Routes inbound `action` notifications to the appropriate per-session
+     * queue, running the reverse mapper to synthesize `AgentEventFields` and
+     * wrapping each into a `ServerActionEnvelope`. Other notification methods
+     * are ignored (no consumers in the wire-only scope of HR8d).
+     *
+     * @param notif - The AHP notification from the wire.
+     */
+    handleNotification(notif) {
+        if (notif.method !== "action") {
+            // Other notifications (root/sessionAdded, auth/required, otlp/*, etc.)
+            // are not consumed by Grackle's downstream pipeline; drop silently.
+            return;
+        }
+        const envelope = notif.params;
+        const session = this.sessions.get(envelope.channel);
+        if (session === undefined) {
+            return;
+        }
+        const result = reverseMapAction(envelope, session.context);
+        for (const event of result.events) {
+            session.queue.push({ event, actions: [envelope.action] });
+        }
+    }
+    /**
+     * Create a new session via AHP `createSession` + `subscribe`.
+     *
+     * Returns synchronously with the session URI and the live envelope stream.
+     * The actual AHP requests fire in the background; failures push an error
+     * sentinel into the stream and close it (mirroring how gRPC stream errors
+     * surface during iteration).
+     */
+    createSession(params) {
+        const channel = sessionChannel(params.sessionId);
+        const session = this.getOrCreateSession(channel);
+        void this.runSpawnFlow(channel, params, undefined).catch((err) => {
+            this.surfaceErrorAndClose(session, channel, err);
+        });
+        return { sessionUri: channel, stream: session.queue };
+    }
+    /**
+     * Reanimate a suspended session. Maps to AHP `createSession` with a
+     * `config.resumeFromRuntimeSessionId` hint that PowerLine interprets as
+     * "spawn a continuation runtime from this prior runtime session."
+     */
+    reanimate(params) {
+        const channel = sessionChannel(params.sessionId);
+        const session = this.getOrCreateSession(channel);
+        const reanimateConfig = {
+            sessionId: params.sessionId,
+            runtime: params.runtime,
+            // Reanimate doesn't have prompt/model/etc.; use empty defaults — the
+            // PowerLine handler ignores them when resumeFromRuntimeSessionId is set.
+            prompt: "",
+            model: "",
+            maxTurns: 0,
+            branch: "",
+            workingDirectory: "",
+            systemContext: "",
+            taskId: "",
+            mcpServersJson: "",
+            mcpUrl: "",
+            mcpToken: "",
+        };
+        void this.runSpawnFlow(channel, reanimateConfig, params.runtimeSessionId).catch((err) => {
+            this.surfaceErrorAndClose(session, channel, err);
+        });
+        return session.queue;
+    }
+    /** Send input text by dispatching a `SessionTurnStartedAction`. */
+    async dispatchInput(sessionUri, text) {
+        this.nextClientSeq += 1;
+        const action = {
+            type: ActionType.SessionTurnStarted,
+            turnId: `turn-input-${String(this.nextClientSeq)}`,
+            userMessage: { text },
+        };
+        this.socket.notify("dispatchAction", {
+            channel: toSessionChannel(sessionUri),
+            clientSeq: this.nextClientSeq,
+            action,
+        });
+    }
+    /**
+     * Deliver runtime credentials.
+     *
+     * AHP `authenticate` is OAuth-shaped (single `{ resource, token }`) and
+     * Grackle's HR6 authenticate delivers multiple typed tokens (env-var or
+     * file-backed) for one provider. HR8d preserves the AHP-spec wire method
+     * by fanning Grackle's tokens out into N `authenticate` calls. Each call:
+     *
+     * - `resource`: `grackle://provider/{provider}/{name}` — encodes the
+     *   Grackle-side identity. PowerLine recognizes the `grackle://` scheme
+     *   and decodes it.
+     * - `token`: JSON-encoded `{ type, envVar?, filePath?, value }` — carries
+     *   the delivery instructions inside the AHP token field.
+     *
+     * On-spec method, abused field semantics. The contortion is documented in
+     * #1336 and bounded to this single command.
+     */
+    async authenticate(params) {
+        const settlements = await Promise.allSettled(params.tokens.map((t) => this.socket.request("authenticate", {
+            channel: ROOT_CHANNEL,
+            resource: `grackle://provider/${params.provider}/${t.name}`,
+            token: JSON.stringify({
+                type: t.type,
+                envVar: t.envVar,
+                filePath: t.filePath,
+                value: t.value,
+            }),
+        })));
+        // Surface the first failure (if any) so the caller can log it — matches
+        // the prior gRPC-path "best-effort, log and continue" semantics.
+        const rejection = settlements.find((s) => s.status === "rejected");
+        if (rejection !== undefined && rejection.status === "rejected") {
+            throw rejection.reason;
+        }
+    }
+    /**
+     * Dispose a session via AHP `disposeSession`.
+     *
+     * AHP's `DisposeSessionParams` doesn't carry a `reason` field; the optional
+     * `reason` argument is logged client-side but not delivered to PowerLine.
+     * Acceptable for HR8d — `reason` was informational in the gRPC path too.
+     */
+    async dispose(sessionUri, _reason) {
+        const channel = toSessionChannel(sessionUri);
+        try {
+            await this.socket.request("disposeSession", { channel });
+        }
+        finally {
+            this.closeSession(channel);
+        }
+    }
+    /** List active sessions via AHP `listSessions`. */
+    async listSessions() {
+        const result = (await this.socket.request("listSessions", {
+            channel: ROOT_CHANNEL,
+        }));
+        return result.items.map((s) => ({
+            sessionId: s.resource.replace(/^ahp-session:\//, ""),
+            runtime: s.provider,
+            // SessionStatus is a bitset enum; preserve the numeric value as string
+            // so existing consumers (which treat status as opaque) still work.
+            status: String(s.status),
+        }));
+    }
+    // ─── Internals ────────────────────────────────────────────────────
+    getOrCreateSession(channel) {
+        let session = this.sessions.get(channel);
+        if (session === undefined) {
+            session = { queue: new EnvelopeQueue(), context: newReverseMapperContext() };
+            this.sessions.set(channel, session);
+        }
+        return session;
+    }
+    closeSession(channel) {
+        const session = this.sessions.get(channel);
+        if (session === undefined) {
+            return;
+        }
+        session.queue.close();
+        this.sessions.delete(channel);
+    }
+    async runSpawnFlow(channel, params, resumeFromRuntimeSessionId) {
+        const config = {
+            // Grackle-specific session config — PowerLine handler validates this shape.
+            prompt: params.prompt,
+            model: params.model,
+            maxTurns: params.maxTurns,
+            branch: params.branch,
+            workingDirectory: params.workingDirectory,
+            systemContext: params.systemContext,
+            taskId: params.taskId,
+            mcpServersJson: params.mcpServersJson,
+            mcpUrl: params.mcpUrl,
+            mcpToken: params.mcpToken,
+            ...(params.workspaceId !== undefined ? { workspaceId: params.workspaceId } : {}),
+            ...(params.useWorktrees !== undefined ? { useWorktrees: params.useWorktrees } : {}),
+            ...(params.pipe !== undefined && params.pipe !== "" ? { pipe: params.pipe } : {}),
+            ...(params.scriptContent !== undefined && params.scriptContent !== ""
+                ? { scriptContent: params.scriptContent }
+                : {}),
+            ...(resumeFromRuntimeSessionId !== undefined ? { resumeFromRuntimeSessionId } : {}),
+        };
+        const ahpParams = {
+            channel,
+            provider: params.runtime,
+            config,
+        };
+        const isReanimate = resumeFromRuntimeSessionId !== undefined;
+        try {
+            await this.socket.request("createSession", ahpParams);
+        }
+        catch (err) {
+            // Reanimate path: if the channel is already live on PowerLine (env was
+            // never actually torn down — happens with the local adapter whose
+            // `stop()` is a no-op), the server returns "Session already active".
+            // For reanimate that's success: the underlying runtime never died, we
+            // just need to re-subscribe to its action stream.
+            if (isReanimate && isSessionAlreadyActiveError(err)) {
+                // intentional fall-through to subscribe()
+            }
+            else {
+                throw err;
+            }
+        }
+        await this.socket.request("subscribe", { channel });
+        // After subscribe resolves, PowerLine starts firing action notifications
+        // (including any replayed parked events) — the handleNotification handler
+        // routes them to the session's queue.
+    }
+    surfaceErrorAndClose(session, channel, err) {
+        // Synthesize an error event so the downstream pipeline sees the failure
+        // through the same channel it sees normal events.
+        const message = formatTransportError(err);
+        const errorEvent = { type: "error", content: message };
+        session.queue.push({ event: errorEvent, actions: [] });
+        session.queue.push({ event: { type: "status", content: "failed" }, actions: [] });
+        this.closeSession(channel);
+    }
+}
+/**
+ * True if `err` is the JSON-RPC "Session already active" error PowerLine
+ * returns when `createSession` targets a channel whose underlying session
+ * is still live in the registry. Tested with both message-prefix and
+ * code+message-shape since the error can arrive as a rejected
+ * `TransportError` or a raw JSON-RPC error object depending on the
+ * `request()` path.
+ */
+function isSessionAlreadyActiveError(err) {
+    const message = err instanceof Error
+        ? err.message
+        : err !== null &&
+            typeof err === "object" &&
+            typeof err.message === "string"
+            ? err.message
+            : "";
+    return message.startsWith("Session already active");
+}
+/**
+ * Stringify an unknown error into a readable message for the synthesized
+ * `type: "error"` event surfaced into the downstream pipeline.
+ *
+ * Handles four shapes:
+ * - `Error` (and subclasses, including `TransportError` from
+ *   `@grackle-ai/ahp-transport`): use `.message`.
+ * - JSON-RPC error object `{ code, message }` (what `request()` rejects with
+ *   on a server-returned error): use `.message`, prefix with code if present.
+ *   Without this branch, `String(err)` returns `"[object Object]"` and the
+ *   UI renders an opaque "Error: [object Object]" with no diagnostic value.
+ * - String: pass through.
+ * - Anything else: best-effort `String(err)`.
+ */
+function formatTransportError(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === "string") {
+        return err;
+    }
+    if (err !== null && typeof err === "object") {
+        const obj = err;
+        if (typeof obj.message === "string" && obj.message.length > 0) {
+            return typeof obj.code === "number" || typeof obj.code === "string"
+                ? `JSON-RPC error ${String(obj.code)}: ${obj.message}`
+                : obj.message;
+        }
+    }
+    return String(err);
+}
+/**
+ * Helper to wire {@link AhpHostTransport}'s notification handler into an
+ * `AhpClientSocket` at construction time. The transport's
+ * {@link AhpHostTransport.handleNotification} method must be bound to the
+ * socket BEFORE `socket.open()` so the first inbound `action` notifications
+ * are routed correctly.
+ *
+ * @param transport - The transport whose handler should be bound.
+ * @returns A function suitable for passing as `onNotification` to
+ *   `AhpClientSocket`'s constructor options.
+ */
+export function bindNotificationHandler(transport) {
+    return (n) => transport.handleNotification(n);
+}
+//# sourceMappingURL=ahp-host-transport.js.map

package/dist/ahp-host-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ahp-host-transport.js","sourceRoot":"","sources":["../src/ahp-host-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAEL,uBAAuB,EACvB,gBAAgB,GAEjB,MAAM,oBAAoB,CAAC;AAa5B,MAAM,YAAY,GAAG,aAAsB,CAAC;AAC5C,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAE/C,kEAAkE;AAClE,SAAS,cAAc,CAAC,SAAiB;IACvC,OAAO,GAAG,sBAAsB,GAAG,SAAS,EAAE,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,cAAsB;IAC9C,OAAO,cAAc,CAAC,UAAU,CAAC,sBAAsB,CAAC;QACtD,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,aAAa;IACA,MAAM,GAA2B,EAAE,CAAC;IACpC,OAAO,GAA6D,EAAE,CAAC;IAChF,UAAU,GAAY,KAAK,CAAC;IAE7B,IAAI,CAAC,IAA0B;QACpC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,CAAC;YACb,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAEM,KAAK,CAAC,KAAK;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,IAAI,OAAO,CAAmC,CAAC,OAAO,EAAE,EAAE;YAC/D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC,CAAC,CAAC;IACL,CAAC;IAEM,KAAK;QACV,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,OAAO;QACT,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAClC,MAAM,CAAC,SAAS,CAAC,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,IAAW,MAAM;QACf,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAEM,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAClC,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,OAAO;YACT,CAAC;YACD,MAAM,IAAI,CAAC;QACb,CAAC;IACH,CAAC;CACF;AAYD;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAgB;IACV,MAAM,CAAkB;IACxB,QAAQ,GAA4B,IAAI,GAAG,EAAE,CAAC;IACvD,aAAa,GAAW,CAAC,CAAC;IAElC;;;;;OAKG;IACH,YAAmB,MAAuB;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;OAWG;IACI,kBAAkB,CAAC,KAAsB;QAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC9B,uEAAuE;YACvE,oEAAoE;YACpE,OAAO;QACT,CAAC;QACD,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAwB,CAAC;QAChD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3D,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACI,aAAa,CAAC,MAA2B;QAC9C,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACjD,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACxE,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;QACH,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;IACxD,CAAC;IAED;;;;OAIG;IACI,SAAS,CAAC,MAAuB;QACtC,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjD,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACjD,MAAM,eAAe,GAAwB;YAC3C,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,qEAAqE;YACrE,yEAAyE;YACzE,MAAM,EAAE,EAAE;YACV,KAAK,EAAE,EAAE;YACT,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,EAAE;YACV,gBAAgB,EAAE,EAAE;YACpB,aAAa,EAAE,EAAE;YACjB,MAAM,EAAE,EAAE;YACV,cAAc,EAAE,EAAE;YAClB,MAAM,EAAE,EAAE;YACV,QAAQ,EAAE,EAAE;SACb,CAAC;QACF,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAC,KAAK,CAC7E,CAAC,GAAY,EAAE,EAAE;YACf,IAAI,CAAC,oBAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;QACnD,CAAC,CACF,CAAC;QACF,OAAO,OAAO,CAAC,KAAK,CAAC;IACvB,CAAC;IAED,mEAAmE;IAC5D,KAAK,CAAC,aAAa,CAAC,UAAkB,EAAE,IAAY;QACzD,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;QACxB,MAAM,MAAM,GAAgB;YAC1B,IAAI,EAAE,UAAU,CAAC,kBAAkB;YACnC,MAAM,EAAE,cAAc,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,EAAE;YAClD,WAAW,EAAE,EAAE,IAAI,EAAE;SACtB,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE;YACnC,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC;YACrC,SAAS,EAAE,IAAI,CAAC,aAAa;YAC7B,MAAM;SACP,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACI,KAAK,CAAC,YAAY,CAAC,MAA0B;QAClD,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,UAAU,CAC1C,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACtB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE;YAClC,OAAO,EAAE,YAAY;YACrB,QAAQ,EAAE,sBAAsB,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE;YAC3D,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC;gBACpB,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;gBACpB,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC;SACH,CAAC,CACH,CACF,CAAC;QACF,wEAAwE;QACxE,iEAAiE;QACjE,MAAM,SAAS,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAC;QACnE,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;YAC/D,MAAM,SAAS,CAAC,MAAe,CAAC;QAClC,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAO,CAAC,UAAkB,EAAE,OAAgB;QACvD,MAAM,OAAO,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,gBAAgB,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC3D,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,mDAAmD;IAC5C,KAAK,CAAC,YAAY;QACvB,MAAM,MAAM,GAAG,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,cAAc,EAAE;YACxD,OAAO,EAAE,YAAY;SACtB,CAAC,CAAuB,CAAC;QAC1B,OAAO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9B,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC;YACpD,OAAO,EAAE,CAAC,CAAC,QAAQ;YACnB,uEAAuE;YACvE,mEAAmE;YACnE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;SACzB,CAAC,CAAC,CAAC;IACN,CAAC;IAED,qEAAqE;IAE7D,kBAAkB,CAAC,OAAY;QACrC,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACzC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,GAAG,EAAE,KAAK,EAAE,IAAI,aAAa,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,EAAE,CAAC;YAC7E,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,YAAY,CAAC,OAAY;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO;QACT,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IAEO,KAAK,CAAC,YAAY,CACxB,OAAY,EACZ,MAA2B,EAC3B,0BAA8C;QAE9C,MAAM,MAAM,GAA4B;YACtC,4EAA4E;YAC5E,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChF,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS,IAAI,MAAM,CAAC,aAAa,KAAK,EAAE;gBACnE,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,EAAE;gBACzC,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,0BAA0B,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpF,CAAC;QACF,MAAM,SAAS,GAA2B;YACxC,OAAO;YACP,QAAQ,EAAE,MAAM,CAAC,OAAO;YACxB,MAAM;SACP,CAAC;QACF,MAAM,WAAW,GAAG,0BAA0B,KAAK,SAAS,CAAC;QAC7D,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;QACxD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,uEAAuE;YACvE,kEAAkE;YAClE,qEAAqE;YACrE,sEAAsE;YACtE,kDAAkD;YAClD,IAAI,WAAW,IAAI,2BAA2B,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpD,0CAA0C;YAC5C,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QACpD,yEAAyE;QACzE,0EAA0E;QAC1E,sCAAsC;IACxC,CAAC;IAEO,oBAAoB,CAAC,OAAsB,EAAE,OAAY,EAAE,GAAY;QAC7E,wEAAwE;QACxE,kDAAkD;QAClD,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;QAC1C,MAAM,UAAU,GAAqB,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACzE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QACvD,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,SAAS,2BAA2B,CAAC,GAAY;IAC/C,MAAM,OAAO,GACX,GAAG,YAAY,KAAK;QAClB,CAAC,CAAC,GAAG,CAAC,OAAO;QACb,CAAC,CAAC,GAAG,KAAK,IAAI;YACV,OAAO,GAAG,KAAK,QAAQ;YACvB,OAAQ,GAA6B,CAAC,OAAO,KAAK,QAAQ;YAC5D,CAAC,CAAE,GAA2B,CAAC,OAAO;YACtC,CAAC,CAAC,EAAE,CAAC;IACX,OAAO,OAAO,CAAC,UAAU,CAAC,wBAAwB,CAAC,CAAC;AACtD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,oBAAoB,CAAC,GAAY;IACxC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC,OAAO,CAAC;IACrB,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5C,MAAM,GAAG,GAAG,GAA4C,CAAC;QACzD,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9D,OAAO,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;gBACjE,CAAC,CAAC,kBAAkB,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,OAAO,EAAE;gBACtD,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAA2B;IACjE,OAAO,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC"}

package/dist/connect.d.ts

@@ -1,16 +1,42 @@
-import type { PowerLineClient, PowerLineConnection } from "./adapter.js";
+import { AhpClientSocket } from "@grackle-ai/ahp-transport";
+import type { PowerLineConnection } from "./adapter.js";
+import { AhpHostTransport } from "./ahp-host-transport.js";
 import type { AdapterLogger } from "./logger.js";
 /**
- * Create an authenticated gRPC client for a PowerLine.
- * The PowerLine token is sent as a Bearer token on every request.
- * When `traceId` is provided, it is forwarded as the `x-trace-id` header for request correlation.
+ * Construct an opened {@link AhpHostTransport} for a single PowerLine.
+ *
+ * Opens an `AhpClientSocket` to `${baseUrl}/ahp`, awaits the AHP
+ * `initialize` handshake, and returns the transport ready for use.
+ *
+ * `InMemoryClientIdStore` is used by default — Grackle's adapter
+ * connections are ephemeral (one per provision; reconnect creates a fresh
+ * one). Persistent `clientId` across server restarts is not required for
+ * HR8d. A future optimization (HR8a-followup #1344) would persist for
+ * reconnect-RPC replay efficiency.
+ *
+ * @param baseUrl - Origin URL of the PowerLine (e.g. `ws://127.0.0.1:7433`).
+ *   The helper appends `/ahp` to form the WebSocket URL.
+ * @param powerlineToken - Bearer token sent on the HTTP upgrade.
+ * @param environmentId - Used as the `clientIdKey` to namespace the
+ *   persisted clientId within the store.
+ * @param logger - Optional logger for state transitions.
+ * @returns The opened transport.
  */
-export declare function createPowerLineClient(baseUrl: string, powerlineToken: string, traceId?: string): PowerLineClient;
+export declare function createAhpHostTransport(baseUrl: string, powerlineToken: string, environmentId: string, logger?: AdapterLogger): Promise<{
+    transport: AhpHostTransport;
+    socket: AhpClientSocket;
+}>;
 /**
- * Connect to a PowerLine through a local tunnel port, retrying until the gRPC
- * service responds to a ping.
+ * Connect to a PowerLine through a local tunnel port, retrying until the AHP
+ * `ping` succeeds.
+ *
+ * @param environmentId - Stable identifier for the environment.
+ * @param localPort - Local TCP port the tunnel forwards to the PowerLine.
+ * @param powerlineToken - Bearer token for the PowerLine.
+ * @param logger - Optional logger.
+ * @returns A {@link PowerLineConnection} ready for session operations.
  */
-export declare function connectThroughTunnel(environmentId: string, localPort: number, powerlineToken: string, logger?: AdapterLogger, traceId?: string): Promise<PowerLineConnection>;
+export declare function connectThroughTunnel(environmentId: string, localPort: number, powerlineToken: string, logger?: AdapterLogger): Promise<PowerLineConnection>;
 /** Single-shot TCP port prober used by {@link waitForLocalPort}. */
 export interface PortProber {
     /** Attempt a single TCP connection to `host:port`, returning `true` if it succeeds. */