@workerdeck/core 0.18.0 → 0.20.0

package/build/index.d.mts

@@ -242,6 +242,26 @@ interface Runner {
   /** Resolve a pending permission request. Returns false if the id is unknown (e.g. timed out). */
   resolvePermission(requestId: string, decision: PermissionDecision): boolean;
   interrupt(): Promise<void>;
+  /**
+   * Reset the conversation in place: the session keeps its id, its watermarks
+   * and its place in the list, and the engine starts over with an empty
+   * context. Announced with a `conversation_reset` event, whose replay rules
+   * (see `transcriptContent` in `@workerdeck/protocol`) are what stop an
+   * attaching client from resurrecting the cleared rows.
+   *
+   * Optional, like every member added after `Runner` became public API: an
+   * out-of-tree runner that declines it declines the `clear_context` command
+   * with it, which is exactly what `EngineCapabilities.clearContext: false`
+   * tells clients to expect.
+   *
+   * **Queues behind in-flight work rather than racing it** — resolving when the
+   * clear has actually happened, not when it was accepted. A clear that landed
+   * in the middle of the turn it was clearing would be neither, and the engines
+   * differ in how they wait (claude hands `/clear` to a CLI that queues its own
+   * streamed input; codex and the provider put it on their turn chain), so the
+   * one thing callers may rely on is the resolution, not the mechanism.
+   */
+  clearContext?(): Promise<void>;
   setPermissionMode(mode: PermissionMode): Promise<void>;
   /** Switch the model for subsequent responses; undefined = back to the default. */
   setModel(model?: string): Promise<void>;
@@ -357,6 +377,25 @@ declare class SessionRunner implements Runner {
   /** Resolve a pending permission request. Returns false if the id is unknown (e.g. timed out). */
   resolvePermission(requestId: string, decision: PermissionDecision): boolean;
   interrupt(): Promise<void>;
+  /**
+   * Reset the conversation by sending the `/clear` the CLI already honors.
+   *
+   * Deliberately not a second mechanism: this engine's reset arrives *from the
+   * SDK*, and `normalizeSdkMessage` turns the CLI's report of it into the
+   * `conversation_reset` event (adopting the new conversation id and re-polling
+   * context usage on the way through). Reimplementing the clear here would give
+   * one engine two ways to reach the same state, and only one of them would get
+   * the id adoption right. So the command and the composer's `/clear` are one
+   * behaviour, and this method is the thin end of it.
+   *
+   * The one place it differs from the other two engines: this resolves when the
+   * `/clear` has been **handed to the CLI**, not when the reset has happened —
+   * the CLI queues its own streamed input, so waiting is its job, and there is
+   * no chain here to ride. The observable contract is the same (a clear sent
+   * mid-turn queues rather than cutting the turn short); only the moment the
+   * promise settles is weaker, and no caller depends on it.
+   */
+  clearContext(): Promise<void>;
   setPermissionMode(mode: PermissionMode): Promise<void>;
   /** Switch the model for subsequent responses; undefined = back to the default. */
   setModel(model?: string): Promise<void>;
@@ -399,8 +438,12 @@ declare class SessionRunner implements Runner {
  * 1. `afterSeq` — the caller already holds everything at or below it.
  * 2. `resetSeq` — transcript *content* strictly below the latest
  *    `conversation_reset` is skipped, so a re-attach cannot resurrect a cleared
- *    conversation while state events still replay. Claude's alone; the other
- *    engines pass 0.
+ *    conversation while state events still replay. **Every engine that can emit
+ *    a reset must track it and pass it** — this was Claude's alone only for as
+ *    long as Claude's was the only engine that could produce the event, and the
+ *    failure when a runner forgets is quiet: the end state is right for a
+ *    current reducer, so nothing looks broken while every attach re-sends the
+ *    whole cleared conversation for the process's lifetime.
  * 3. `coalesceReplay` — last-write-wins state readings superseded later in the
  *    same replay (`staleReplaySeqs`), plus everything `replayRetains` says the
  *    reducer reads and discards. Opt-in, and only sound for a consumer whose
@@ -627,6 +670,20 @@ declare class AiSdkRunner implements Runner {
    * its tokens are never lost from the turn's accounting.
    */
   generateDigest(prompt: string): Promise<string>;
+  /**
+   * Reset the conversation: drop the message array the next turn would have
+   * been built from. There is no engine round trip — this runner *is* where the
+   * transcript lives, so clearing it is the whole operation.
+   *
+   * Two things ride along, both already written elsewhere and both load-bearing
+   * here. `#emit`'s `conversation_reset` arm retires `#contextUsage` (the
+   * reading described a conversation that no longer exists), and the same arm
+   * in `restore` keeps a parked session that comes back after a clear from
+   * resurrecting it. Pending tool calls are NOT swept: a parked call is work a
+   * backend still owes an answer for, and a clear is not an interrupt — the
+   * refusal below is what keeps the two apart.
+   */
+  clearContext(): Promise<void>;
   interrupt(): Promise<void>;
   setPermissionMode(mode: PermissionMode): Promise<void>;
   setModel(model?: string): Promise<void>;
@@ -1645,7 +1702,15 @@ declare const codexAdapter: EngineAdapter;
  *     const c=JSON.parse(d.slice(s,i));
  *     for(const m of c.models) console.log(m.slug, m.display_name,
  *       m.visibility, m.supported_reasoning_levels.map(l=>l.effort).join(","))'\
- *     "$(node -p 'require.resolve("@openai/codex-darwin-arm64/package.json").replace("package.json","vendor/aarch64-apple-darwin/bin/codex")')"
+ *     "$(node -p 'const{createRequire}=require("module");
+ *       const w=require.resolve("@openai/codex/package.json");
+ *       createRequire(w).resolve("@openai/codex-darwin-arm64/package.json")
+ *         .replace("package.json","vendor/aarch64-apple-darwin/bin/codex")')"
+ *
+ * The two-hop resolve is NOT optional: under pnpm's strict layout the platform
+ * package is a dependency of `@openai/codex`, so it resolves only from that
+ * wrapper's location, never from the repo root. Resolving it directly throws
+ * MODULE_NOT_FOUND — the same two hops `resolveBundledCodexExecutable` makes.
  *
  * Mapping decisions:
  * - the internal `codex-auto-review` row is dropped (the codex analogue of
@@ -1709,6 +1774,36 @@ declare class CodexRunner implements Runner {
    * timed out, or already settled by codex itself). */
   resolvePermission(requestId: string, decision: PermissionDecision): boolean;
   interrupt(): Promise<void>;
+  /**
+   * Reset the conversation: a **fresh thread on the same session**.
+   *
+   * Codex has no clear/reset RPC — `thread/compact/start` summarises and
+   * continues, `thread/fork` makes a second thread, and neither is "same
+   * session, empty context". So the analog is to stop resuming the old thread
+   * and start a new one, which is the path a dead child already takes minus the
+   * resume. The old thread is NOT deleted: it stays in CODEX_HOME and stays
+   * resumable from `GET /sdk-sessions`.
+   *
+   * Two things it does on the way through, both mirroring the Claude engine's
+   * SDK-driven reset (`engines/claude/runner.ts`):
+   *
+   * 1. **The new thread id is adopted before `conversation_reset` is emitted**,
+   *    whenever a child is already up — the eager `thread/start` costs no
+   *    tokens and no model call, and it is what keeps the dormant record from
+   *    ever naming the conversation that was just cleared. With no child there
+   *    is nothing to start against and the id is simply dropped; the parking
+   *    service treats a resumable session with no engine session id as one with
+   *    nothing to come back to, and forgets the stale record.
+   * 2. **The context reading is retired**, in `#emit`'s `conversation_reset`
+   *    arm. Codex cannot re-poll it the way Claude does — the only source is
+   *    `thread/tokenUsage/updated`, which arrives *during* a turn — so there is
+   *    no reading at all until the next turn runs, and the protocol's rule
+   *    applies: render nothing rather than a stale ring or a 0%.
+   *
+   * The turn counter stays monotonic across this, on purpose (it is an unread
+   * cursor, not an item count), and so does `activityCount` — `#emit` owns both.
+   */
+  clearContext(): Promise<void>;
   setPermissionMode(mode: PermissionMode): Promise<void>;
   setModel(model?: string): Promise<void>;
   fail(message: string): void;