@workerdeck/core 0.19.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>;
@@ -1717,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;

package/build/index.mjs

@@ -607,8 +607,12 @@ function staleReplaySeqs(events, afterSeq) {
 * 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
@@ -1309,6 +1313,28 @@ var SessionRunner = class {
 	async interrupt() {
 		await this.#query?.interrupt();
 	}
+	/**
+	* 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.
+	*/
+	async clearContext() {
+		if (this.#status === "closed" || this.#status === "failed") throw new Error("session is closed");
+		this.sendMessage("/clear");
+	}
 	async setPermissionMode(mode) {
 		await this.#query?.setPermissionMode(mode);
 		this.#permissionMode = mode;
@@ -1836,6 +1862,15 @@ var AiSdkRunner = class {
 	*/
 	#contextUsage;
 	#activityCount = 0;
+	/**
+	* Seq of the latest `conversation_reset` event, 0 when none. The log itself is
+	* never truncated — it still carries the state-bearing events (`capabilities`,
+	* `system_init`, …) a fresh attacher depends on and which are not re-emitted —
+	* but `subscribe()` skips transcript *content* strictly below this mark, so a
+	* replay does not resurrect a cleared conversation. A later reset supersedes
+	* an earlier one by overwriting it.
+	*/
+	#resetSeq = 0;
 	#status = "starting";
 	#permissionMode;
 	#messages = [];
@@ -1887,8 +1922,10 @@ var AiSdkRunner = class {
 		this.#activityCount = 0;
 		for (const event of this.#events) {
 			this.#activityCount += transcriptActivity(event);
-			if (event.type === "conversation_reset") this.#contextUsage = void 0;
-			else this.#contextUsage = contextReading(event) ?? this.#contextUsage;
+			if (event.type === "conversation_reset") {
+				this.#resetSeq = event.seq;
+				this.#contextUsage = void 0;
+			} else this.#contextUsage = contextReading(event) ?? this.#contextUsage;
 		}
 		this.#messages = [...state.messages];
 		for (const call of state.pendingToolCalls) this.#pendingToolCalls.set(call.toolCallId, call);
@@ -2158,6 +2195,30 @@ var AiSdkRunner = class {
 		}
 		return result.text;
 	}
+	/**
+	* 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.
+	*/
+	async clearContext() {
+		if (this.#status === "closed" || this.#status === "failed") throw new Error("session is closed");
+		const run = this.#turnChain.then(() => {
+			if (this.#closed) throw new Error("session is closed");
+			if (this.#pendingToolCalls.size > 0) throw new Error("cannot clear context while tool calls are outstanding");
+			this.#messages = [];
+			this.#emit({ type: "conversation_reset" });
+		});
+		this.#turnChain = run.then(() => void 0, () => void 0);
+		await run;
+	}
 	async interrupt() {
 		if (this.#abort) this.#abort.abort();
 		else if (this.#pendingToolCalls.size > 0) {
@@ -2238,7 +2299,7 @@ var AiSdkRunner = class {
 		return this.#events.find((event) => event.seq === seq);
 	}
 	subscribe(listener, afterSeq = 0, options) {
-		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options);
+		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options, this.#resetSeq);
 	}
 	#scheduleTurn() {
 		this.#turnChain = this.#turnChain.then(() => this.#runTurn());
@@ -2628,7 +2689,10 @@ var AiSdkRunner = class {
 		this.#lastActivityAt = event.ts;
 		this.#activityCount += transcriptActivity(body);
 		this.#contextUsage = contextReading(body) ?? this.#contextUsage;
-		if (body.type === "conversation_reset") this.#contextUsage = void 0;
+		if (body.type === "conversation_reset") {
+			this.#resetSeq = event.seq;
+			this.#contextUsage = void 0;
+		}
 		this.#events.push(event);
 		this.#subscribers.emit(event);
 	}
@@ -4100,6 +4164,25 @@ var CodexAgentTracker = class {
 	sweep() {
 		for (const record of this.#byThread.values()) if (record.status === "running") this.#settle(record, "failed");
 	}
+	/**
+	* The conversation these agents belonged to is gone (a `conversation_reset`).
+	*
+	* Deliberately NOT {@link CodexAgentTracker.sweep}: that settles the running
+	* ones as failed and keeps the rows, which is right when the *process* dies —
+	* the transcript still holds the anchor `tool_use` each row points at, and a
+	* row that vanished would leave that card unexplained. A clear is the other
+	* way round. The anchors go with the transcript, so a surviving row would
+	* publish a `toolUseId` that resolves to nothing — and clients key a
+	* pressable, enterable agent line off exactly that id.
+	*/
+	forget() {
+		this.#byThread.clear();
+	}
+	/** The thread ids currently tracked — what a clear remembers so a still-running
+	* agent's later traffic can be dropped rather than re-anchored. */
+	threadIds() {
+		return Array.from(this.#byThread.keys());
+	}
 	/** The rollup as `SessionInfo.subagents` serves it — spawn order, fresh
 	* objects, and `undefined` when there is nothing to say (absent and empty
 	* mean the same thing to a client, and bytes on a polled list are paid for). */
@@ -4943,6 +5026,15 @@ var CodexRunner = class {
 	*/
 	#contextUsage;
 	#activityCount = 0;
+	/**
+	* Seq of the latest `conversation_reset` event, 0 when none. The log itself is
+	* never truncated — it still carries the state-bearing events (`capabilities`,
+	* `system_init`, …) a fresh attacher depends on and which are not re-emitted —
+	* but `subscribe()` skips transcript *content* strictly below this mark, so a
+	* replay does not resurrect a cleared conversation. A later reset supersedes
+	* an earlier one by overwriting it.
+	*/
+	#resetSeq = 0;
 	#status = "starting";
 	#sdkSessionId;
 	#model;
@@ -5005,6 +5097,15 @@ var CodexRunner = class {
 	* it, and only the child process dying (or the session closing) ends them
 	* all — see the module doc in `subagents.ts`. */
 	#agents = new CodexAgentTracker();
+	/** Threads that belonged to a conversation this session has cleared — the
+	* agents that were still running when it happened. Their notifications keep
+	* arriving on the same connection (a clear does not interrupt them and does
+	* not drop the child), and without this {@link CodexRunner.#agentFor} would
+	* mint them a fresh anchor and stream the cleared conversation's agent work
+	* into the new one. Never pruned: it is a handful of uuids for the session's
+	* life, and a late report from a long-dead agent is exactly what it exists to
+	* catch. */
+	#clearedThreads = /* @__PURE__ */ new Set();
 	constructor(config, id = randomUUID()) {
 		const mode = config.permissionMode ?? "default";
 		if (!ENGINE_CAPABILITIES.codex.permissionModes.includes(mode)) throw new Error(`permission mode '${mode}' is not supported by the codex engine`);
@@ -5183,6 +5284,15 @@ var CodexRunner = class {
 	}
 	sendMessage(text, attachments) {
 		if (this.#closed) throw new Error("session is closed");
+		if (text.trim() === "/clear" && !attachments?.length) {
+			this.clearContext().catch((error) => {
+				this.#emit({
+					type: "session_error",
+					message: `could not clear the conversation: ${error instanceof Error ? error.message : String(error)}`
+				});
+			});
+			return;
+		}
 		const input = this.#buildInput(text, attachments ?? []);
 		const echo = () => this.#emit({
 			type: "user_message",
@@ -5254,6 +5364,66 @@ var CodexRunner = class {
 		await this.#interruptTurn();
 		await this.#turnChain;
 	}
+	/**
+	* 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.
+	*/
+	async clearContext() {
+		if (this.#closed) throw new Error("session is closed");
+		const run = this.#turnChain.then(() => this.#clearNow());
+		this.#turnChain = run.then(() => void 0, () => void 0);
+		await run;
+	}
+	/** The clear itself, only ever called as a turn-chain link. */
+	async #clearNow() {
+		if (this.#closed) throw new Error("session is closed");
+		const previousThread = this.#sdkSessionId;
+		this.#sdkSessionId = void 0;
+		this.#threadLoaded = false;
+		if (this.#connection) try {
+			await this.#ensureThread();
+		} catch (error) {
+			this.#sdkSessionId = previousThread;
+			this.#threadLoaded = false;
+			throw error;
+		}
+		for (const agent of this.#agents.threadIds()) this.#clearedThreads.add(agent);
+		this.#agents.forget();
+		for (const [id, pending] of this.#approvals) this.#settleApproval(id, pending, {
+			behavior: "deny",
+			message: "the conversation was cleared"
+		}, "policy");
+		this.#resumedHistory = void 0;
+		this.#emit({
+			type: "conversation_reset",
+			sdkSessionId: this.#sdkSessionId
+		});
+	}
 	/** Address the in-flight turn only (no approval sweep) — also the follow-up
 	* for a deny+interrupt whose wire decision couldn't carry the interrupt. */
 	async #interruptTurn() {
@@ -5331,7 +5501,7 @@ var CodexRunner = class {
 		return this.#events.find((event) => event.seq === seq);
 	}
 	subscribe(listener, afterSeq = 0, options) {
-		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options);
+		return this.#subscribers.subscribe(this.#events, listener, afterSeq, options, this.#resetSeq);
 	}
 	#scheduleTurn() {
 		this.#turnChain = this.#turnChain.then(() => this.#runTurn());
@@ -5747,6 +5917,7 @@ var CodexRunner = class {
 		if (threadId === void 0 || threadId === this.#sdkSessionId) return void 0;
 		const known = this.#agents.get(threadId);
 		if (known) return known;
+		if (this.#clearedThreads.has(threadId)) return void 0;
 		const nonce = this.#activeTurn?.nonce ?? "codex";
 		const record = this.#agents.open(threadId, `${nonce}:agent:${threadId}`, void 0, Date.now());
 		record.anchored = true;
@@ -6385,7 +6556,10 @@ var CodexRunner = class {
 		this.#lastActivityAt = event.ts;
 		this.#activityCount += transcriptActivity(body);
 		this.#contextUsage = contextReading(body) ?? this.#contextUsage;
-		if (body.type === "conversation_reset") this.#contextUsage = void 0;
+		if (body.type === "conversation_reset") {
+			this.#resetSeq = event.seq;
+			this.#contextUsage = void 0;
+		}
 		this.#events.push(event);
 		this.#subscribers.emit(event);
 	}