@apnex/network-adapter 0.1.0

package/dist/kernel/poll-backstop.d.ts

@@ -0,0 +1,108 @@
+/**
+ * poll-backstop.ts — adapter-side hybrid poll backstop (mission-56 W3.3).
+ *
+ * Periodic `list_messages({target.role, status: "new", since: <last-seen>})`
+ * poll at LONG cadence — the SAFETY NET behind the W1a SSE push pipeline.
+ * Per Design v1.2 commitment #5: push is the primary path; polling fills
+ * the gaps caused by adapter restart, transient SSE drop between
+ * reconnect-replay (W1b) windows, and any push-edge dropped events the
+ * adapter didn't see.
+ *
+ * Anti-pattern guard (per architect-issued W3 directive): poll cadence
+ * MUST be measurably longer than push latency. Default 5min
+ * (`OIS_ADAPTER_POLL_BACKSTOP_S=300`); 60s minimum (1min) for tests.
+ *
+ * Cursor persistence: last-seen Message ID is persisted across adapter
+ * restarts so the poll fetches only the delta on each tick. Default
+ * cursor file: `~/.ois/poll-cursor-<role>-<agentId>.json`. The
+ * `since` cursor is REQUIRED on every poll — initial-state (no cursor
+ * file) sends `since` undefined and treats the first poll's results as
+ * the cold-start baseline (which the seen-id LRU dedup in the
+ * MessageRouter de-collides against any concurrent push delivery of
+ * the same Message IDs).
+ *
+ * Each surfaced Message is routed through the host-supplied callback
+ * (the same `onActionableEvent` shape used by the SSE inline path).
+ * The W2.1 `@apnex/message-router` seen-id LRU catches the push+poll
+ * race overlap so a Message that arrived via SSE in the last 5min
+ * window is not double-rendered when the next poll-tick sees it too.
+ */
+import type { IAgentClient, AgentEvent } from "./agent-client.js";
+export interface PollBackstopOptions {
+    /**
+     * Role this adapter polls for (e.g. "engineer", "architect"). Becomes
+     * the `target.role` filter on each `list_messages` call.
+     */
+    role: string;
+    /**
+     * Poll cadence in seconds. Defaults to `OIS_ADAPTER_POLL_BACKSTOP_S`
+     * env var (parsed as integer), falling back to 300 (5 minutes).
+     * Floored at `MIN_CADENCE_SECONDS` (60) to enforce the
+     * "measurably longer than push latency" anti-pattern guard.
+     */
+    cadenceSeconds?: number;
+    /**
+     * Override cursor-file location. Defaults to
+     * `~/.ois/poll-cursor-<role>-<agentId>.json`. Tests inject a
+     * temp path here; production callers can override to land cursors
+     * in workspace-local state (e.g. `.ois/poll-cursor.json`).
+     */
+    cursorFile?: string;
+    /**
+     * Diagnostic logger. No-op default. Mirrors the dispatcher's `log`
+     * convention.
+     */
+    log?: (msg: string) => void;
+    /**
+     * Hook fired for each Message surfaced by the poll. Same shape as
+     * `DispatcherNotificationHooks.onActionableEvent` so the dispatcher
+     * can wire poll output through the same MessageRouter as the SSE
+     * inline path (preserving seen-id LRU dedup across both paths).
+     */
+    onPolledMessage: (event: AgentEvent) => void;
+}
+/**
+ * Resolve the cursor file path. Defaults to
+ * `~/.ois/poll-cursor-<role>-<agentId>.json`. The agentId is
+ * stable across restarts (mission-19 Agent identity) so a single
+ * adapter instance always writes/reads the same cursor file.
+ */
+export declare function defaultCursorFile(role: string, agentId: string): string;
+/**
+ * Read the persisted cursor (or undefined if no cursor file exists).
+ * Corruption-tolerant: returns undefined on parse failure (cold-start
+ * recovery — the seen-id LRU absorbs any double-delivery from the
+ * resulting full replay).
+ */
+export declare function readCursor(path: string): string | undefined;
+/**
+ * Write the cursor atomically (writeFileSync; same pattern as the
+ * tool-catalog cache). Best-effort on failure (poll continues on the
+ * in-process cursor; restart will re-read whatever last persisted).
+ */
+export declare function writeCursor(path: string, lastSeenId: string | undefined, log?: (msg: string) => void): void;
+/**
+ * The PollBackstop runs the periodic `list_messages` tick loop and
+ * surfaces each delta Message via the `onPolledMessage` hook.
+ *
+ * Lifecycle: `start(getAgent)` begins the timer; `stop()` cancels it
+ * cleanly. Idempotent — start while already-started is a no-op; stop
+ * while not-started is a no-op.
+ */
+export declare class PollBackstop {
+    private readonly opts;
+    private timer;
+    private resolvedCursorFile;
+    private inFlight;
+    constructor(opts: PollBackstopOptions);
+    /** Start the periodic poll. Idempotent. */
+    start(getAgent: () => IAgentClient | null): void;
+    /** Stop the periodic poll. Idempotent. */
+    stop(): void;
+    /**
+     * Single poll iteration. Exposed for tests + diagnostic operators
+     * (e.g. force-tick on demand). Reentrant-safe via in-flight guard
+     * — concurrent ticks coalesce on the in-flight one.
+     */
+    tick(getAgent: () => IAgentClient | null): Promise<void>;
+}

package/dist/kernel/poll-backstop.js

@@ -0,0 +1,243 @@
+/**
+ * poll-backstop.ts — adapter-side hybrid poll backstop (mission-56 W3.3).
+ *
+ * Periodic `list_messages({target.role, status: "new", since: <last-seen>})`
+ * poll at LONG cadence — the SAFETY NET behind the W1a SSE push pipeline.
+ * Per Design v1.2 commitment #5: push is the primary path; polling fills
+ * the gaps caused by adapter restart, transient SSE drop between
+ * reconnect-replay (W1b) windows, and any push-edge dropped events the
+ * adapter didn't see.
+ *
+ * Anti-pattern guard (per architect-issued W3 directive): poll cadence
+ * MUST be measurably longer than push latency. Default 5min
+ * (`OIS_ADAPTER_POLL_BACKSTOP_S=300`); 60s minimum (1min) for tests.
+ *
+ * Cursor persistence: last-seen Message ID is persisted across adapter
+ * restarts so the poll fetches only the delta on each tick. Default
+ * cursor file: `~/.ois/poll-cursor-<role>-<agentId>.json`. The
+ * `since` cursor is REQUIRED on every poll — initial-state (no cursor
+ * file) sends `since` undefined and treats the first poll's results as
+ * the cold-start baseline (which the seen-id LRU dedup in the
+ * MessageRouter de-collides against any concurrent push delivery of
+ * the same Message IDs).
+ *
+ * Each surfaced Message is routed through the host-supplied callback
+ * (the same `onActionableEvent` shape used by the SSE inline path).
+ * The W2.1 `@apnex/message-router` seen-id LRU catches the push+poll
+ * race overlap so a Message that arrived via SSE in the last 5min
+ * window is not double-rendered when the next poll-tick sees it too.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_CADENCE_SECONDS = 300; // 5 minutes
+const MIN_CADENCE_SECONDS = 60; // 1 minute floor — anti-pattern guard
+/**
+ * Resolve the cursor file path. Defaults to
+ * `~/.ois/poll-cursor-<role>-<agentId>.json`. The agentId is
+ * stable across restarts (mission-19 Agent identity) so a single
+ * adapter instance always writes/reads the same cursor file.
+ */
+export function defaultCursorFile(role, agentId) {
+    return join(homedir(), ".ois", `poll-cursor-${role}-${agentId}.json`);
+}
+/**
+ * Read the persisted cursor (or undefined if no cursor file exists).
+ * Corruption-tolerant: returns undefined on parse failure (cold-start
+ * recovery — the seen-id LRU absorbs any double-delivery from the
+ * resulting full replay).
+ */
+export function readCursor(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            (parsed.lastSeenId === undefined || typeof parsed.lastSeenId === "string")) {
+            return parsed.lastSeenId;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write the cursor atomically (writeFileSync; same pattern as the
+ * tool-catalog cache). Best-effort on failure (poll continues on the
+ * in-process cursor; restart will re-read whatever last persisted).
+ */
+export function writeCursor(path, lastSeenId, log = () => { }) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        try {
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+        catch (err) {
+            log(`[poll-backstop] mkdirSync(${dir}) failed: ${err}`);
+            return;
+        }
+    }
+    const body = {
+        lastSeenId,
+        updatedAt: new Date().toISOString(),
+        version: 1,
+    };
+    try {
+        writeFileSync(path, JSON.stringify(body, null, 2), { mode: 0o600 });
+    }
+    catch (err) {
+        log(`[poll-backstop] writeFileSync(${path}) failed: ${err}`);
+    }
+}
+function parseListMessagesResult(raw) {
+    const env = raw;
+    if (!env || !env.content || !env.content[0] || env.isError)
+        return null;
+    try {
+        return JSON.parse(env.content[0].text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The PollBackstop runs the periodic `list_messages` tick loop and
+ * surfaces each delta Message via the `onPolledMessage` hook.
+ *
+ * Lifecycle: `start(getAgent)` begins the timer; `stop()` cancels it
+ * cleanly. Idempotent — start while already-started is a no-op; stop
+ * while not-started is a no-op.
+ */
+export class PollBackstop {
+    opts;
+    timer = null;
+    resolvedCursorFile = null;
+    inFlight = false;
+    constructor(opts) {
+        const fromEnv = parseInt(process.env.OIS_ADAPTER_POLL_BACKSTOP_S ?? "", 10);
+        const cadence = Math.max(MIN_CADENCE_SECONDS, opts.cadenceSeconds ??
+            (Number.isFinite(fromEnv) ? fromEnv : DEFAULT_CADENCE_SECONDS));
+        this.opts = {
+            role: opts.role,
+            cadenceSeconds: cadence,
+            cursorFile: opts.cursorFile,
+            log: opts.log ?? (() => { }),
+            onPolledMessage: opts.onPolledMessage,
+        };
+    }
+    /** Start the periodic poll. Idempotent. */
+    start(getAgent) {
+        if (this.timer)
+            return;
+        const cadenceMs = this.opts.cadenceSeconds * 1000;
+        this.opts.log(`[poll-backstop] starting (role=${this.opts.role}, cadenceS=${this.opts.cadenceSeconds})`);
+        this.timer = setInterval(() => {
+            // Fire-and-forget; tick() handles its own errors.
+            void this.tick(getAgent);
+        }, cadenceMs);
+        if (this.timer.unref)
+            this.timer.unref();
+    }
+    /** Stop the periodic poll. Idempotent. */
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+        this.opts.log("[poll-backstop] stopped");
+    }
+    /**
+     * Single poll iteration. Exposed for tests + diagnostic operators
+     * (e.g. force-tick on demand). Reentrant-safe via in-flight guard
+     * — concurrent ticks coalesce on the in-flight one.
+     */
+    async tick(getAgent) {
+        if (this.inFlight)
+            return;
+        this.inFlight = true;
+        try {
+            const agent = getAgent();
+            if (!agent || agent.state !== "streaming")
+                return;
+            // Cursor file resolution: lazy on first tick (agentId only
+            // becomes known post-handshake).
+            if (!this.resolvedCursorFile) {
+                if (this.opts.cursorFile) {
+                    this.resolvedCursorFile = this.opts.cursorFile;
+                }
+                else {
+                    const agentId = agent.getSessionId() ?? "unknown";
+                    // Prefer `getMetrics().agentId` when available — it's the
+                    // post-handshake stable Agent identity, distinct from the
+                    // session id which cycles on reconnect.
+                    const metrics = agent.getMetrics?.();
+                    const id = metrics?.agentId ?? agentId;
+                    this.resolvedCursorFile = defaultCursorFile(this.opts.role, id);
+                }
+            }
+            const cursorFile = this.resolvedCursorFile;
+            const since = readCursor(cursorFile);
+            const args = {
+                targetRole: this.opts.role,
+                status: "new",
+            };
+            if (since !== undefined)
+                args.since = since;
+            let raw;
+            try {
+                raw = await agent.call("list_messages", args);
+            }
+            catch (err) {
+                this.opts.log(`[poll-backstop] list_messages failed (non-fatal): ${err?.message ?? String(err)}`);
+                return;
+            }
+            const body = parseListMessagesResult(raw);
+            if (!body || !Array.isArray(body.messages)) {
+                this.opts.log(`[poll-backstop] unexpected list_messages result shape; skipping tick`);
+                return;
+            }
+            if (body.messages.length === 0) {
+                // No delta — keep the existing cursor (no need to rewrite the
+                // file with an unchanged value).
+                return;
+            }
+            // Surface each delta Message through the host hook. Mirrors the
+            // SSE `message_arrived` envelope shape so the MessageRouter +
+            // host hooks don't need a separate code path.
+            let maxId = since ?? "";
+            for (const message of body.messages) {
+                if (!message || typeof message.id !== "string")
+                    continue;
+                if (message.id > maxId)
+                    maxId = message.id;
+                const event = {
+                    event: "message_arrived",
+                    data: { message },
+                    // The SSE envelope id is the W1b Last-Event-ID surface; for
+                    // poll-sourced events we use the Message ID itself so the
+                    // MessageRouter's seen-id LRU dedup catches push+poll race.
+                    id: message.id,
+                };
+                try {
+                    this.opts.onPolledMessage(event);
+                }
+                catch (err) {
+                    this.opts.log(`[poll-backstop] onPolledMessage handler threw (non-fatal): ${err?.message ?? String(err)}`);
+                }
+            }
+            // Persist the cursor advance only if we observed strictly newer IDs
+            // (defensive: if some weirdness made every returned id <= since,
+            // don't regress the cursor).
+            if (since === undefined || maxId > since) {
+                writeCursor(cursorFile, maxId, this.opts.log);
+            }
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+}
+//# sourceMappingURL=poll-backstop.js.map

package/dist/kernel/poll-backstop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"poll-backstop.js","sourceRoot":"","sources":["../../src/kernel/poll-backstop.ts"],"names":[],"mappings":"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"}

package/dist/kernel/session-claim.d.ts

@@ -0,0 +1,67 @@
+/**
+ * session-claim.ts — explicit session-claim warmup helpers.
+ *
+ * Pure helpers for the eager-claim path: when a real adapter session
+ * (vs probe spawn) starts, it sets `OIS_EAGER_SESSION_CLAIM=1` to
+ * declare intent to claim a Hub session synchronously rather than
+ * waiting for the lazy auto-claim path.
+ *
+ *   - isEagerWarmupEnabled(env): tests the env hint.
+ *   - parseClaimSessionResponse(wrapper): defensively unwraps the MCP
+ *     tool-call response for `claim_session`.
+ *   - formatSessionClaimedLogLine(parsed): structured-parseable
+ *     [Handshake] log line for diagnostic tooling.
+ *
+ * Renamed from `eager-claim.ts` in mission-55 cleanup — the module
+ * owns claim-session helpers regardless of eager-mode usage; the
+ * old name implied an eager-only scope that no longer fits.
+ */
+/**
+ * Surface fields the adapter consumes from `claim_session` response.
+ * mission-63 W3: flattened from the canonical wire envelope per Design
+ * v1.0 §3.2 + ADR-028 (`{ok, agent: {id, ...}, session: {epoch, claimed,
+ * trigger, displacedPriorSession?}, message?}`). Adapter doesn't carry
+ * the full canonical nested shape — flatten at parse-time.
+ */
+export interface ClaimSessionParsed {
+    agentId?: string;
+    sessionEpoch?: number;
+    sessionClaimed?: boolean;
+    displacedPriorSession?: {
+        sessionId: string;
+        epoch: number;
+    };
+}
+/**
+ * True iff `OIS_EAGER_SESSION_CLAIM` is set to the literal string
+ * `"1"`. Any other value (unset, "0", "true", whitespace, etc.) is
+ * lazy-mode. Strict on purpose — a typo doesn't accidentally land on
+ * eager mode.
+ */
+export declare function isEagerWarmupEnabled(env: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
+/**
+ * Defensively parse the `claim_session` MCP tool-call response.
+ * Handles the three wrapper shapes seen in the wild:
+ *   - string (JSON-encoded payload)
+ *   - { content: [{ text: JSON_STRING }] } (canonical MCP result)
+ *   - already-parsed object
+ *
+ * mission-63 W3: reads canonical envelope per Design §3.2 — `body.agent.id`
+ * + `body.session.{epoch, claimed, trigger, displacedPriorSession?}`.
+ * Flattens the nested shape into ClaimSessionParsed for adapter consumers
+ * that don't need the full canonical nesting. Returns an empty object on
+ * any parse failure (callers fall back to "unknown" / "none" when emitting
+ * the [Handshake] log line).
+ */
+export declare function parseClaimSessionResponse(wrapper: unknown): ClaimSessionParsed;
+/**
+ * Format the `[Handshake] Session claimed` log line in
+ * structured-parseable form for dashboard / diagnostic tooling.
+ *
+ *   `[Handshake] Session claimed: epoch=<N> (displaced prior: <session-id|none>)`
+ *
+ * Used in eager mode after `claim_session` returns. Lazy mode does
+ * not log this line — the Hub-side auto-claim happens server-side
+ * and the adapter has no synchronous response to format.
+ */
+export declare function formatSessionClaimedLogLine(parsed: ClaimSessionParsed): string;

package/dist/kernel/session-claim.js

@@ -0,0 +1,106 @@
+/**
+ * session-claim.ts — explicit session-claim warmup helpers.
+ *
+ * Pure helpers for the eager-claim path: when a real adapter session
+ * (vs probe spawn) starts, it sets `OIS_EAGER_SESSION_CLAIM=1` to
+ * declare intent to claim a Hub session synchronously rather than
+ * waiting for the lazy auto-claim path.
+ *
+ *   - isEagerWarmupEnabled(env): tests the env hint.
+ *   - parseClaimSessionResponse(wrapper): defensively unwraps the MCP
+ *     tool-call response for `claim_session`.
+ *   - formatSessionClaimedLogLine(parsed): structured-parseable
+ *     [Handshake] log line for diagnostic tooling.
+ *
+ * Renamed from `eager-claim.ts` in mission-55 cleanup — the module
+ * owns claim-session helpers regardless of eager-mode usage; the
+ * old name implied an eager-only scope that no longer fits.
+ */
+/**
+ * True iff `OIS_EAGER_SESSION_CLAIM` is set to the literal string
+ * `"1"`. Any other value (unset, "0", "true", whitespace, etc.) is
+ * lazy-mode. Strict on purpose — a typo doesn't accidentally land on
+ * eager mode.
+ */
+export function isEagerWarmupEnabled(env) {
+    return env.OIS_EAGER_SESSION_CLAIM === "1";
+}
+/**
+ * Defensively parse the `claim_session` MCP tool-call response.
+ * Handles the three wrapper shapes seen in the wild:
+ *   - string (JSON-encoded payload)
+ *   - { content: [{ text: JSON_STRING }] } (canonical MCP result)
+ *   - already-parsed object
+ *
+ * mission-63 W3: reads canonical envelope per Design §3.2 — `body.agent.id`
+ * + `body.session.{epoch, claimed, trigger, displacedPriorSession?}`.
+ * Flattens the nested shape into ClaimSessionParsed for adapter consumers
+ * that don't need the full canonical nesting. Returns an empty object on
+ * any parse failure (callers fall back to "unknown" / "none" when emitting
+ * the [Handshake] log line).
+ */
+export function parseClaimSessionResponse(wrapper) {
+    if (wrapper === null || wrapper === undefined)
+        return {};
+    try {
+        let body;
+        if (typeof wrapper === "string") {
+            body = JSON.parse(wrapper);
+        }
+        else if (typeof wrapper === "object") {
+            const w = wrapper;
+            if (Array.isArray(w.content) &&
+                w.content[0]?.text &&
+                typeof w.content[0].text === "string") {
+                body = JSON.parse(w.content[0].text);
+            }
+            else {
+                body = wrapper;
+            }
+        }
+        else {
+            return {};
+        }
+        if (typeof body !== "object" || body === null)
+            return {};
+        const b = body;
+        const agent = b.agent;
+        const session = b.session;
+        const out = {};
+        if (agent && typeof agent.id === "string")
+            out.agentId = agent.id;
+        if (session) {
+            if (typeof session.epoch === "number")
+                out.sessionEpoch = session.epoch;
+            if (typeof session.claimed === "boolean")
+                out.sessionClaimed = session.claimed;
+            const dps = session.displacedPriorSession;
+            if (dps &&
+                typeof dps.sessionId === "string" &&
+                typeof dps.epoch === "number") {
+                out.displacedPriorSession = { sessionId: dps.sessionId, epoch: dps.epoch };
+            }
+        }
+        return out;
+    }
+    catch {
+        /* fall through to empty */
+    }
+    return {};
+}
+/**
+ * Format the `[Handshake] Session claimed` log line in
+ * structured-parseable form for dashboard / diagnostic tooling.
+ *
+ *   `[Handshake] Session claimed: epoch=<N> (displaced prior: <session-id|none>)`
+ *
+ * Used in eager mode after `claim_session` returns. Lazy mode does
+ * not log this line — the Hub-side auto-claim happens server-side
+ * and the adapter has no synchronous response to format.
+ */
+export function formatSessionClaimedLogLine(parsed) {
+    const epoch = parsed.sessionEpoch ?? "unknown";
+    const displacedPrior = parsed.displacedPriorSession?.sessionId ?? "none";
+    return `[Handshake] Session claimed: epoch=${epoch} (displaced prior: ${displacedPrior})`;
+}
+//# sourceMappingURL=session-claim.js.map

package/dist/kernel/session-claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-claim.js","sourceRoot":"","sources":["../../src/kernel/session-claim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAA2D;IAE3D,OAAO,GAAG,CAAC,uBAAuB,KAAK,GAAG,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAgB;IACxD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACzD,IAAI,CAAC;QACH,IAAI,IAAa,CAAC;QAClB,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,OAAiD,CAAC;YAC5D,IACE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;gBACxB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI;gBAClB,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,EACrC,CAAC;gBACD,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACN,IAAI,GAAG,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,EAAE,CAAC;QACzD,MAAM,CAAC,GAAG,IAA+B,CAAC;QAC1C,MAAM,KAAK,GAAG,CAAC,CAAC,KAA4C,CAAC;QAC7D,MAAM,OAAO,GAAG,CAAC,CAAC,OAA8C,CAAC;QACjE,MAAM,GAAG,GAAuB,EAAE,CAAC;QACnC,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;YAAE,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC;QAClE,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ;gBAAE,GAAG,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC;YACxE,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,SAAS;gBAAE,GAAG,CAAC,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;YAC/E,MAAM,GAAG,GAAG,OAAO,CAAC,qBAEP,CAAC;YACd,IACE,GAAG;gBACH,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;gBACjC,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAC7B,CAAC;gBACD,GAAG,CAAC,qBAAqB,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;YAC7E,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,2BAA2B;IAC7B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CACzC,MAA0B;IAE1B,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,IAAI,SAAS,CAAC;IAC/C,MAAM,cAAc,GAAG,MAAM,CAAC,qBAAqB,EAAE,SAAS,IAAI,MAAM,CAAC;IACzE,OAAO,sCAAsC,KAAK,sBAAsB,cAAc,GAAG,CAAC;AAC5F,CAAC"}

package/dist/kernel/state-sync.d.ts

@@ -0,0 +1,43 @@
+/**
+ * State sync — called on entry to the `synchronizing` phase.
+ *
+ * Runs `get_task` + `get_pending_actions` in parallel, then calls
+ * `completeSync()` to transition to `streaming` and flush buffered events.
+ *
+ * The enriched handshake is NOT called here — `McpAgentClient.runHandshake`
+ * invokes it before this function runs, so `state-sync.ts` can assume the
+ * engineer has its canonical agentId by the time it queries pending state.
+ */
+import type { ILogger, LegacyStringLogger } from "../logger.js";
+/**
+ * A PendingActionItem as returned by `drain_pending_actions` (ADR-017).
+ * Adapter-facing shape — subset of the Hub's canonical type that's
+ * relevant for consumption. `id` is the queue item's surrogate ID which
+ * MUST be passed back as `sourceQueueItemId` on the settling tool call
+ * (e.g., create_thread_reply) for completion-ACK.
+ */
+export interface DrainedPendingAction {
+    id: string;
+    dispatchType: string;
+    entityRef: string;
+    payload: Record<string, unknown>;
+}
+export interface StateSyncContext {
+    executeTool: (name: string, args: Record<string, unknown>) => Promise<unknown>;
+    completeSync: () => void;
+    /** Structured logger. A legacy `(msg: string) => void` is auto-bridged. */
+    log: ILogger | LegacyStringLogger;
+    /** Optional hook for per-engineer logging of pending directives. */
+    onPendingTask?: (task: Record<string, unknown>) => void;
+    /**
+     * ADR-017 drain-on-wake. Called once per item returned from
+     * `drain_pending_actions`. The adapter is responsible for:
+     *   1. Processing the item (LLM reasoning, user surface, etc.)
+     *   2. Threading `item.id` as `sourceQueueItemId` when it issues the
+     *      settling tool call (create_thread_reply, create_review, …)
+     * Missing this hook means the queue items drain without consumer —
+     * the Hub's watchdog will eventually escalate to Director.
+     */
+    onPendingActionItem?: (item: DrainedPendingAction) => void;
+}
+export declare function performStateSync(ctx: StateSyncContext): Promise<void>;

package/dist/kernel/state-sync.js

@@ -0,0 +1,85 @@
+/**
+ * State sync — called on entry to the `synchronizing` phase.
+ *
+ * Runs `get_task` + `get_pending_actions` in parallel, then calls
+ * `completeSync()` to transition to `streaming` and flush buffered events.
+ *
+ * The enriched handshake is NOT called here — `McpAgentClient.runHandshake`
+ * invokes it before this function runs, so `state-sync.ts` can assume the
+ * engineer has its canonical agentId by the time it queries pending state.
+ */
+import { normalizeToILogger } from "../logger.js";
+export async function performStateSync(ctx) {
+    const log = normalizeToILogger(ctx.log, "StateSync");
+    log.log("agent.sync.start", undefined, "[StateSync] Starting state sync...");
+    try {
+        // ADR-017 additive: drain_pending_actions runs alongside the legacy
+        // surface. Hubs that don't expose the tool yet (pre-ADR-017) return
+        // an error here which we swallow — the other two calls still land.
+        const [directive, pendingActions, drainedRaw] = await Promise.all([
+            ctx.executeTool("get_task", {}).catch((err) => {
+                log.log("agent.sync.get_task.failed", { error: String(err) }, `[StateSync] get_task: ${err}`);
+                return null;
+            }),
+            ctx.executeTool("get_pending_actions", {}).catch((err) => {
+                log.log("agent.sync.get_pending_actions.failed", { error: String(err) }, `[StateSync] get_pending_actions: ${err}`);
+                return null;
+            }),
+            ctx.executeTool("drain_pending_actions", {}).catch((err) => {
+                log.log("agent.sync.drain_pending_actions.failed", { error: String(err) }, `[StateSync] drain_pending_actions: ${err}`);
+                return null;
+            }),
+        ]);
+        if (directive && typeof directive === "object") {
+            const d = directive;
+            if (d.task && typeof d.task === "object") {
+                const task = d.task;
+                log.log("agent.sync.pending_task", { taskId: String(task.taskId ?? "unknown") }, `[StateSync] Pending task: ${task.taskId ?? "unknown"}`);
+                if (ctx.onPendingTask)
+                    ctx.onPendingTask(task);
+            }
+        }
+        if (pendingActions && typeof pendingActions === "object") {
+            const pa = pendingActions;
+            log.log("agent.sync.pending_actions", { totalPending: Number(pa.totalPending ?? 0) }, `[StateSync] Pending actions: ${pa.totalPending ?? 0}`);
+        }
+        // ADR-017: dispatch drained queue items to the adapter's handler.
+        // Shape: { items: PendingActionItem[] }. Tool returns isError=true
+        // when no agent is bound to the session — the adapter catch above
+        // already swallowed; here we just ensure the items array is safe.
+        if (drainedRaw && typeof drainedRaw === "object") {
+            const d = drainedRaw;
+            const items = Array.isArray(d.items) ? d.items : [];
+            if (items.length > 0) {
+                log.log("agent.sync.drained_items", { count: items.length }, `[StateSync] Drained ${items.length} pending action item(s)`);
+            }
+            if (ctx.onPendingActionItem) {
+                for (const raw of items) {
+                    if (!raw || typeof raw !== "object")
+                        continue;
+                    const item = raw;
+                    if (typeof item.id !== "string")
+                        continue;
+                    ctx.onPendingActionItem({
+                        id: item.id,
+                        dispatchType: String(item.dispatchType ?? ""),
+                        entityRef: String(item.entityRef ?? ""),
+                        payload: item.payload ?? {},
+                    });
+                }
+            }
+        }
+        ctx.completeSync();
+        log.log("agent.sync.complete", undefined, "[StateSync] Sync complete — now streaming");
+    }
+    catch (err) {
+        log.log("agent.sync.failed", { error: String(err) }, `[StateSync] Failed: ${err}`);
+        try {
+            ctx.completeSync();
+        }
+        catch {
+            log.log("agent.sync.complete_failed", undefined, "[StateSync] completeSync() also failed");
+        }
+    }
+}
+//# sourceMappingURL=state-sync.js.map