@chorus-aidlc/chorus-openclaw-plugin 0.5.3 → 0.11.0

package/dist/connection-state.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A read accessor for the live connection identity. This is the exact shape the
+ * shared `daemon-rest-client` (`getConnectionUuid?: () => string|null`) and the
+ * control handler consume, so a single `ConnectionState` instance can be passed
+ * to both.
+ */
+export interface ConnectionStateReader {
+    /** The connection uuid this stream registered as, or null before handshake. */
+    getConnectionUuid: () => string | null;
+}
+/**
+ * Mutable connection identity. One instance per plugin process; the SSE
+ * listener's `onConnectionId` writes it, the rest client + control handler read
+ * it. Not a singleton export — the entry owns the instance and injects it — so
+ * tests can construct an isolated state per case.
+ */
+export declare class ConnectionState implements ConnectionStateReader {
+    private connectionUuid;
+    /** The current connection identity, or null before the first handshake. */
+    getConnectionUuid(): string | null;
+    /**
+     * Record (or refresh) the connection identity. Called from the SSE listener's
+     * `onConnectionId` on every `connection_registered` event, so a reconnect that
+     * registers a new DaemonConnection overwrites the previous uuid rather than
+     * leaving a stale one that could mis-route a control command.
+     */
+    setConnectionUuid(connectionUuid: string): void;
+    /**
+     * Forget the connection identity (e.g. on a clean disconnect). After this,
+     * `getConnectionUuid()` returns null so the control handler's double-check
+     * treats every command as "not ours" until a fresh handshake re-registers.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=connection-state.d.ts.map

package/dist/connection-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-state.d.ts","sourceRoot":"","sources":["../src/connection-state.ts"],"names":[],"mappings":"AAsBA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,qBAAqB;IAC3D,OAAO,CAAC,cAAc,CAAuB;IAE7C,2EAA2E;IAC3E,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAIlC;;;;;OAKG;IACH,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAI/C;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/connection-state.js

@@ -0,0 +1,52 @@
+// packages/openclaw-plugin/src/connection-state.ts
+// Holds the live DaemonConnection identity for this OpenClaw plugin process —
+// the `connectionUuid` the server assigns post-handshake and reports via the
+// `connection_registered` SSE data event (see api/events/notifications/route.ts).
+//
+// WHY A DEDICATED MODULE: the connectionUuid is captured in ONE place (the SSE
+// listener, via onConnectionId) but READ in several (the daemon REST client to
+// attribute execution-state / turn-advance, and the control handler to do its
+// `targetConnectionUuid === my uuid` double-check). Threading it through every
+// constructor would couple those modules to the listener's lifecycle; instead
+// the listener writes it here and the consumers read it through a stable
+// `getConnectionUuid()` accessor — the same accessor shape the shared
+// `daemon-rest-client` already expects (`getConnectionUuid?: () => string|null`).
+//
+// The value is refreshed on every `connection_registered` (so a reconnect that
+// registers a NEW DaemonConnection overwrites the stale uuid), and is the single
+// source of truth for "which connection am I" across the plugin.
+//
+// This mirrors the CLI host's `SseListener.connectionUuid` field
+// (cli/sse-listener.mjs), lifted into a module so the OpenClaw plugin's separate
+// modules can share one identity without a circular import on the listener.
+/**
+ * Mutable connection identity. One instance per plugin process; the SSE
+ * listener's `onConnectionId` writes it, the rest client + control handler read
+ * it. Not a singleton export — the entry owns the instance and injects it — so
+ * tests can construct an isolated state per case.
+ */
+export class ConnectionState {
+    connectionUuid = null;
+    /** The current connection identity, or null before the first handshake. */
+    getConnectionUuid() {
+        return this.connectionUuid;
+    }
+    /**
+     * Record (or refresh) the connection identity. Called from the SSE listener's
+     * `onConnectionId` on every `connection_registered` event, so a reconnect that
+     * registers a new DaemonConnection overwrites the previous uuid rather than
+     * leaving a stale one that could mis-route a control command.
+     */
+    setConnectionUuid(connectionUuid) {
+        this.connectionUuid = connectionUuid;
+    }
+    /**
+     * Forget the connection identity (e.g. on a clean disconnect). After this,
+     * `getConnectionUuid()` returns null so the control handler's double-check
+     * treats every command as "not ours" until a fresh handshake re-registers.
+     */
+    clear() {
+        this.connectionUuid = null;
+    }
+}
+//# sourceMappingURL=connection-state.js.map

package/dist/connection-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-state.js","sourceRoot":"","sources":["../src/connection-state.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,8EAA8E;AAC9E,6EAA6E;AAC7E,kFAAkF;AAClF,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAC9E,yEAAyE;AACzE,sEAAsE;AACtE,kFAAkF;AAClF,EAAE;AACF,+EAA+E;AAC/E,iFAAiF;AACjF,iEAAiE;AACjE,EAAE;AACF,iEAAiE;AACjE,iFAAiF;AACjF,4EAA4E;AAa5E;;;;;GAKG;AACH,MAAM,OAAO,eAAe;IAClB,cAAc,GAAkB,IAAI,CAAC;IAE7C,2EAA2E;IAC3E,iBAAiB;QACf,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,cAAsB;QACtC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/dist/control-handler.d.ts

@@ -0,0 +1,73 @@
+import type { ConnectionStateReader } from "./connection-state.js";
+/**
+ * The control event shape the server publishes on `control:{connectionUuid}` and
+ * forwards verbatim as a `type:"control"` SSE data event. Mirrors the server's
+ * `ControlEvent` (src/lib/event-bus.ts). `entityType`/`entityUuid` are present for
+ * `interrupt`/`resume`; `turnUuid` is present only for `deliver_turn`.
+ */
+export interface ControlEvent {
+    type: string;
+    command?: string;
+    targetConnectionUuid?: string;
+    entityType?: string;
+    entityUuid?: string;
+    turnUuid?: string;
+}
+/**
+ * Injected behavior hooks. These are the seams the openclaw-daemon-client task
+ * (T4) fills with the real abort / re-dispatch / pending-turns-sweep. This task
+ * (T3) only ROUTES verified commands to them — it does not implement the
+ * behaviors. All hooks are optional so a partially-wired host (or a test) can
+ * verify routing without every behavior present.
+ */
+export interface ControlBehaviorHooks {
+    /**
+     * Whether this plugin currently holds a RUNNING embedded-agent run for the
+     * entity — the OpenClaw analog of the CLI host's "execution registry holds a
+     * running child" check. Gates `interrupt` (Check 2). Defaults to "nothing is
+     * running" (always false) when absent, so an interrupt with no registry is a
+     * safe no-op rather than a blind abort.
+     */
+    isEntityRunning?: (entityType: string, entityUuid: string) => boolean;
+    /**
+     * Abort the matching in-flight run for the entity (true mid-run stop via the
+     * run's AbortController). Invoked only after BOTH checks pass. (T4)
+     */
+    onInterrupt?: (entityType: string, entityUuid: string) => void;
+    /**
+     * Re-dispatch the entity's wake to continue the same session — the synthetic
+     * "resume" wake. Invoked after Check 1 only (no running-entity requirement —
+     * the run is gone). (T4)
+     */
+    onResume?: (entityType: string, entityUuid: string) => void;
+    /**
+     * Run the connection-scoped pending turn(s). With a `turnUuid` (origin-only
+     * live delivery) run PRECISELY that one turn; without one (older server /
+     * reconnect) sweep all pending turns. Invoked after Check 1 only. (T4)
+     */
+    onDeliverTurn?: (turnUuid?: string) => void;
+}
+export interface ControlHandlerOptions {
+    /** Live connection identity (connection-state). Provides Check 1's "my uuid". */
+    connectionState: ConnectionStateReader;
+    /** Injected behavior hooks (filled by T4). */
+    hooks: ControlBehaviorHooks;
+    logger: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+/**
+ * Build the `onControl(event)` callback the SSE listener invokes for a
+ * `type:"control"` event. The returned function is synchronous and non-throwing:
+ * it performs the double-check and routes to the (injected) behavior hook,
+ * returning immediately so the SSE consumer never blocks.
+ *
+ * A control event NEVER enqueues a wake or spawns a run for the control event
+ * itself — that structural guarantee is owned by the SSE listener fork (the
+ * control event never reaches `onEvent` / the wake router) and reinforced here
+ * by routing ONLY to the abort/resume/deliver hooks, never to the wake path.
+ */
+export declare function createControlHandler(opts: ControlHandlerOptions): (event: ControlEvent) => void;
+//# sourceMappingURL=control-handler.d.ts.map

package/dist/control-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-handler.d.ts","sourceRoot":"","sources":["../src/control-handler.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAK3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAEtE;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAE/D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAE5D;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,qBAAqB;IACpC,iFAAiF;IACjF,eAAe,EAAE,qBAAqB,CAAC;IACvC,8CAA8C;IAC9C,KAAK,EAAE,oBAAoB,CAAC;IAC5B,MAAM,EAAE;QAAE,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CACpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAqG/F"}

package/dist/control-handler.js

@@ -0,0 +1,135 @@
+// packages/openclaw-plugin/src/control-handler.ts
+// OpenClaw-host handler for reverse (server→daemon) control commands — the
+// in-process analog of cli/control-handler.mjs. The SSE listener forks a
+// `type:"control"` SSE event here (NOT to the wake router — see sse-listener.ts),
+// so a control command can NEVER spawn a new embedded-agent run for the control
+// event itself. This module is the ROUTING + DOUBLE-CHECK layer only; the actual
+// abort / re-dispatch / pending-turns-sweep BEHAVIORS are injected (filled by the
+// openclaw-daemon-client task, T4).
+//
+// The single safety property this module enforces is the DOUBLE-CHECK, identical
+// to the CLI host (cli/control-handler.mjs): act ONLY when —
+//   Check 1 (every command): event.targetConnectionUuid === this plugin's OWN
+//            registered connectionUuid (from connection-state). On mismatch — a
+//            stale/recycled uuid, another connection's command, or a handshake not
+//            yet complete — IGNORE + LOG. This is what stops a recycled connection
+//            uuid from aborting the wrong run (Tech Design "Risks": mis-kill after
+//            a reconnect).
+//   Check 2 (interrupt only): the injected `isEntityRunning(entityType, entityUuid)`
+//            predicate returns true — i.e. this plugin currently holds a running
+//            embedded-agent run for that entity. (In the CLI host this is "the
+//            execution registry holds a running child"; here it is an injected
+//            predicate the daemon client backs with its AbortController registry.)
+//            On mismatch — only queued, never ran, or already finished — IGNORE + LOG.
+//
+// `resume` and `deliver_turn` carry NO running-entity requirement (mirroring the
+// CLI host): the run for a resumed entity is already gone, and a `deliver_turn`
+// resolves its turn by uuid from the persisted turn table. They only require
+// Check 1.
+//
+// The three verbs route to injected behavior hooks (the seams T4 plugs into):
+//   - interrupt    → onInterrupt(entityType, entityUuid)
+//   - resume       → onResume(entityType, entityUuid)
+//   - deliver_turn → onDeliverTurn(turnUuid?)   (turnUuid present = precise single
+//                    turn; absent = older server, full connection sweep fallback)
+//
+// Non-throwing: a control event must NEVER crash the SSE loop, so the whole body
+// is wrapped in a try/catch backstop and the hooks' own throws are caught + logged
+// (memory: no-silent-errors — every ignore/failure is logged, never swallowed).
+/**
+ * Build the `onControl(event)` callback the SSE listener invokes for a
+ * `type:"control"` event. The returned function is synchronous and non-throwing:
+ * it performs the double-check and routes to the (injected) behavior hook,
+ * returning immediately so the SSE consumer never blocks.
+ *
+ * A control event NEVER enqueues a wake or spawns a run for the control event
+ * itself — that structural guarantee is owned by the SSE listener fork (the
+ * control event never reaches `onEvent` / the wake router) and reinforced here
+ * by routing ONLY to the abort/resume/deliver hooks, never to the wake path.
+ */
+export function createControlHandler(opts) {
+    const { connectionState, hooks, logger } = opts;
+    const isEntityRunning = hooks.isEntityRunning ?? (() => false);
+    return function onControl(event) {
+        try {
+            if (!event || event.type !== "control") {
+                logger.warn(`[Chorus] control-handler received non-control event; ignoring`);
+                return;
+            }
+            if (event.command !== "interrupt" &&
+                event.command !== "resume" &&
+                event.command !== "deliver_turn") {
+                // Forward-compatible: the wire enum may grow. Unknown command → ignore + log.
+                logger.warn(`[Chorus] control command "${event.command}" not supported; ignoring`);
+                return;
+            }
+            const { command, targetConnectionUuid, entityType, entityUuid } = event;
+            // --- Check 1: connection-uuid match (applies to EVERY command) ---
+            const myConnectionUuid = connectionState.getConnectionUuid();
+            if (!myConnectionUuid || targetConnectionUuid !== myConnectionUuid) {
+                // Not ours (stale/recycled uuid, another connection, or handshake not yet
+                // complete). Ignore — never abort/resume/deliver for a command that isn't ours.
+                logger.info(`[Chorus] control: ignoring ${command} for connection ${targetConnectionUuid} ` +
+                    `(this plugin is ${myConnectionUuid ?? "<unregistered>"})`);
+                return;
+            }
+            // --- deliver_turn: origin-only live delivery. No entity on the wire (the
+            //     turn is read by uuid) and NO running-entity requirement (mirrors
+            //     resume). With a turnUuid, run PRECISELY that turn; without one (older
+            //     server), the hook falls back to a full connection sweep. ---
+            if (command === "deliver_turn") {
+                const turnUuid = typeof event.turnUuid === "string" ? event.turnUuid : undefined;
+                logger.info(`[Chorus] control: deliver_turn for connection ${targetConnectionUuid} ` +
+                    (turnUuid ? `(turn ${turnUuid})` : "(no turnUuid — full sweep fallback)"));
+                try {
+                    hooks.onDeliverTurn?.(turnUuid);
+                }
+                catch (err) {
+                    logger.warn(`[Chorus] control: deliver_turn hook failed: ${err}`);
+                }
+                return;
+            }
+            // interrupt / resume both target a specific entity — require both fields.
+            if (typeof entityType !== "string" || typeof entityUuid !== "string") {
+                logger.warn(`[Chorus] control: ${command} missing entityType/entityUuid; ignoring`);
+                return;
+            }
+            // --- resume: re-dispatch the wake for this entity. No running-entity check —
+            //     the run is gone (it was interrupted); the wake path re-enters the same
+            //     session. Check 1 already passed. ---
+            if (command === "resume") {
+                logger.info(`[Chorus] control: resuming ${entityType}:${entityUuid} (re-dispatch wake)`);
+                try {
+                    hooks.onResume?.(entityType, entityUuid);
+                }
+                catch (err) {
+                    logger.warn(`[Chorus] control: resume re-dispatch failed for ${entityType}:${entityUuid}: ${err}`);
+                }
+                return;
+            }
+            // --- interrupt path: Check 2 — this plugin must hold a RUNNING run for the
+            //     entity. The injected predicate is backed by the daemon client's
+            //     AbortController registry (T4). ---
+            if (!isEntityRunning(entityType, entityUuid)) {
+                // Either we never ran this entity, it's only queued, or the run already
+                // finished (race: interrupt arrived after completion). Safe no-op.
+                logger.info(`[Chorus] control: no running embedded-agent run for ${entityType}:${entityUuid} ` +
+                    `on this plugin; ignoring interrupt`);
+                return;
+            }
+            // --- Both checks passed: route to the abort hook (true mid-run stop). ---
+            logger.info(`[Chorus] control: interrupting running run for ${entityType}:${entityUuid}`);
+            try {
+                hooks.onInterrupt?.(entityType, entityUuid);
+            }
+            catch (err) {
+                logger.warn(`[Chorus] control: interrupt hook failed for ${entityType}:${entityUuid}: ${err}`);
+            }
+        }
+        catch (err) {
+            // Absolute backstop — a control event must never crash the SSE loop.
+            logger.error(`[Chorus] control-handler unexpected error: ${err}`);
+        }
+    };
+}
+//# sourceMappingURL=control-handler.js.map

package/dist/control-handler.js.map

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

package/dist/daemon-client.d.ts

@@ -0,0 +1,203 @@
+import type { OpenClawRuntimeAgent, OpenClawBlockReplyPayload } from "openclaw/plugin-sdk/plugin-entry";
+import type { DaemonRestClient, DaemonTranscriptMessage, DaemonPendingTurn } from "./daemon-rest-client.js";
+export interface DaemonClientLogger {
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+}
+/**
+ * The host knobs the run needs, resolved per-wake by the entry/wake layer. These are
+ * the OpenClaw runtime-derived values (workspace dir, timeout, model, …) that wake.ts
+ * already knows how to resolve from `api.config`. The daemon client takes them as a
+ * resolver so it never reaches into `api` directly (keeps it host-API-agnostic + testable).
+ */
+export interface WakeRunContext {
+    /** The `runtime.agent` surface to run the turn with. */
+    agent: OpenClawRuntimeAgent;
+    /** The OpenClaw session key for this wake's main agent (e.g. `agent:main:main`). */
+    sessionKey: string;
+    /** The resolved default agent id (session/workspace resolvers are agent-scoped). */
+    agentId: string;
+    /** The opaque `api.config` snapshot passed through to runEmbeddedAgent. */
+    config: unknown;
+    /** Resolved agent workspace dir. */
+    workspaceDir: string;
+    /** Resolved agent dir (optional — omitted when the host has none). */
+    agentDir?: string;
+    /** Resolved per-agent timeout. */
+    timeoutMs: number;
+    /** Resolved `{ provider, model }` override, or null to use the host default. */
+    modelRef: {
+        provider: string;
+        model: string;
+    } | null;
+}
+/**
+ * Per-wake attribution + prompt. `entityType`/`entityUuid` identify the resource the
+ * execution row keys on; `directIdeaUuid`/`rootIdeaUuid` come from the lineage resolve
+ * (the two-id contract: directIdea = session anchor, rootIdea = snapshot attribution).
+ * `contextKey` is the router's dedupe/log key. `turnUuid` is set for a delivered turn.
+ */
+export interface WakeRequest {
+    prompt: string;
+    contextKey: string;
+    entityType?: string | null;
+    entityUuid?: string | null;
+    directIdeaUuid?: string | null;
+    rootIdeaUuid?: string | null;
+    /** When this wake runs a specific pending turn (deliver_turn / backfill). */
+    turnUuid?: string | null;
+}
+export interface OpenClawDaemonClientOptions {
+    /** The shared REST client (turnAdvance/transcript/executionState/reportInterrupt/readPendingTurns). */
+    restClient: DaemonRestClient;
+    /**
+     * Resolve the host run context for a wake (workspace/timeout/model/agent/session
+     * key). Returns null when the wake must be DROPPED (no resolvable session/agent on
+     * this host) — mirrors wake.ts's graceful-drop. Errors thrown here are caught.
+     */
+    resolveRunContext: () => WakeRunContext | null;
+    /**
+     * Re-dispatch a wake for an entity (the synthetic resume / pending-turn path). Built
+     * by the entry from the router so a resume / delivered turn rides the SAME wake path
+     * (continuing the same session). Receives the full WakeRequest.
+     */
+    redispatch: (req: WakeRequest) => void;
+    /**
+     * Read this connection's unstarted (pending) turns and feed each to `redispatch`.
+     * The client owns the seen-set dedup + the optional single-turn filter; the entry
+     * just provides the prompt builder via `buildTurnPrompt`.
+     */
+    buildTurnPrompt: (turn: DaemonPendingTurn) => string;
+    logger?: DaemonClientLogger;
+}
+/**
+ * Extract finalized assistant VISIBLE text from an `onBlockReply` payload, or null to
+ * skip. Mirrors the CLI host's stream-json filter (upload-hooks.mjs
+ * `extractTranscriptText`): keep only finalized assistant text; DROP reasoning/thinking
+ * (`isReasoning`) — verified the flag exists at ../openclaw/src/agents/
+ * embedded-agent-payloads.ts:7 and is set true for reasoning blocks
+ * (embedded-agent-subscribe.handlers.messages.ts:915). Tool internals never reach here
+ * (they arrive on `onToolResult`, which the client does not post). Never throws.
+ */
+export declare function extractBlockReplyText(payload: OpenClawBlockReplyPayload | undefined | null): DaemonTranscriptMessage | null;
+/**
+ * The OpenClaw in-process daemon client. One instance per plugin process; the entry
+ * injects the shared REST client + the host run-context resolver + the re-dispatch
+ * hook, and wires this client's `controlHooks` into the control handler.
+ */
+export declare class OpenClawDaemonClient {
+    private readonly restClient;
+    private readonly resolveRunContext;
+    private readonly redispatch;
+    private readonly buildTurnPrompt;
+    private readonly logger;
+    /** AbortController per in-flight run, keyed `entityType:entityUuid`. */
+    private readonly aborts;
+    /** Execution snapshot source — one entry per running/queued resource. */
+    private readonly executions;
+    /**
+     * At-most-once turn dedup, keyed `turn:<uuid>`. Shared by the live deliver_turn
+     * path and the reconnect backfill so a turn observed by either runs at most once
+     * (mirrors the CLI host's `seen` set; backfill.mjs).
+     */
+    private readonly seenTurns;
+    private runCounter;
+    constructor(opts: OpenClawDaemonClientOptions);
+    /**
+     * The behavior hooks the control handler routes verified commands to. The handler
+     * owns the double-check (own connection + held entity); these implement the actual
+     * abort / re-dispatch / pending-turns-sweep.
+     */
+    get controlHooks(): {
+        isEntityRunning: (entityType: string, entityUuid: string) => boolean;
+        onInterrupt: (entityType: string, entityUuid: string) => void;
+        onResume: (entityType: string, entityUuid: string) => void;
+        onDeliverTurn: (turnUuid?: string) => void;
+    };
+    /**
+     * Abort the matching in-flight run (true mid-run stop via abortSignal) and mark it
+     * `interrupting` so the run's settle path reports reason=user (not crash). No-op when
+     * no run is registered (the handler's Check 2 already gates this, but we re-check so a
+     * direct caller is safe). Never throws.
+     */
+    interrupt(entityType: string, entityUuid: string): void;
+    /**
+     * Re-dispatch a wake for the entity to continue the SAME session (the run is gone;
+     * resolveRunContext re-derives the same sessionKey → getSessionEntry resolves the
+     * existing sessionId). The control handler has no prompt; we synthesize a minimal
+     * resume prompt. Continues under the same business key (directIdea/entity).
+     */
+    resume(entityType: string, entityUuid: string): void;
+    /**
+     * Read connection-scoped pending turns and run the unstarted human_instruction turn.
+     * With a `turnUuid` run PRECISELY that one (live deliver_turn); without one sweep all
+     * (reconnect backfill). Idempotent via the shared `seenTurns` set keyed `turn:<uuid>`.
+     * Never throws into the caller. Mirrors backfill.mjs `backfillPendingTurns`.
+     */
+    deliverTurn(onlyTurnUuid?: string): Promise<void>;
+    /** Reconnect backfill: full connection-scoped pending-turns sweep (no single-turn filter). */
+    onReconnect(): Promise<void>;
+    /**
+     * Run one wake via runEmbeddedAgent with full daemon reporting. Never throws — a
+     * wake failure is logged + reported (crash), never propagated (the SSE service must
+     * stay alive). Fire-and-forget from the caller's perspective; returns a promise the
+     * tests can await.
+     *
+     * Lifecycle (mirrors waker.mjs):
+     *   1. resolve run context (drop on null);
+     *   2. derive sessionKey from the business key → getSessionEntry → sessionId/sessionFile;
+     *   3. register the AbortController + mark the execution running → turnAdvance(running)
+     *      + execution-state snapshot;
+     *   4. run with transcript callbacks (onBlockReply → post {role:"assistant", text});
+     *   5. on settle → turnAdvance(ended) + snapshot; classify interrupt(user) vs crash;
+     *   6. finally → deregister the controller + drop the execution row + snapshot.
+     */
+    runWake(req: WakeRequest): Promise<void>;
+    /**
+     * Mark a resource QUEUED and emit a snapshot. Called before a wake actually runs
+     * (e.g. when it sits behind a same-session run) so the server sees it waiting. The
+     * running transition in `runWake` overwrites it. Never throws.
+     */
+    markQueued(req: WakeRequest): void;
+    private buildExecutionSnapshot;
+    /** Fire-and-forget execution-state snapshot. Never throws. */
+    private emitExecutionSnapshot;
+    private advanceTurn;
+    private postTranscript;
+    private report;
+    private nextRunId;
+}
+/** Registry key for an entity. */
+export declare function execKey(entityType: string, entityUuid: string): string;
+/**
+ * The reportable resource for a wake — `{ entityType, entityUuid }` — or null when it
+ * has no recognized target (mirrors waker.mjs `#entityOf`).
+ */
+export declare function entityOf(req: {
+    entityType?: string | null;
+    entityUuid?: string | null;
+}): {
+    entityType: string;
+    entityUuid: string;
+} | null;
+/**
+ * The session BUSINESS KEY used in all reports (turn-advance/transcript): the
+ * directIdeaUuid when the entity has an idea ancestor, else the entity uuid. Mirrors
+ * the CLI host's `sessionId = directIdeaUuid ?? notification.entityUuid` (waker.mjs:286).
+ */
+export declare function deriveSessionId(req: {
+    directIdeaUuid?: string | null;
+    entityUuid?: string | null;
+}): string | null;
+/**
+ * Derive the deterministic OpenClaw `sessionKey` for a wake from its business key. The
+ * OpenClaw session store is keyed by `sessionKey` (the agent queue key), NOT by the
+ * Chorus business id — so to make `resume`/`deliver_turn` continue the SAME OpenClaw
+ * session we must derive the SAME key from the SAME business id every time. We namespace
+ * the business id under the host's main-agent key so a Chorus wake gets its own stable
+ * lane that re-resolves identically across runs (the in-process analog of
+ * `claude --resume <directIdeaUuid>`, where the disk transcript is the stable anchor).
+ */
+export declare function deriveSessionKey(businessKey: string, mainSessionKey: string): string;
+//# sourceMappingURL=daemon-client.d.ts.map

package/dist/daemon-client.d.ts.map

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