@scotthuang/agent-knock-knock 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,8 +1,23 @@
 # Changelog
 
-## Unreleased
+## 0.2.1 - 2026-06-22
 
-No unreleased changes.
+### Changed
+
+- Deprecated the standalone restart recovery path from the OpenClaw-facing tool, slash command, skill, and docs. Conversations that need recovery now present `recover`, `close`, or starting a new independent delegation.
+- Changed `send` to automatically fall back to AKK replay recovery when the previous ACPX session is unavailable. Explicit recovery decisions remain available only through `--recovery-policy explicit`.
+
+## 0.2.0 - 2026-06-22
+
+### Added
+
+- Added experimental native Codex session discovery and takeover flows, including safe resume, OpenClaw-summarized fork, and confirmed terminate-then-resume adoption for active Codex CLI sessions.
+- Added an explicit `allowCwdOnly` terminate-then-resume fallback for Codex TUI processes that do not expose a session id in argv; it still requires a user-confirmed pid and cwd re-scan before termination.
+- Added tests for Codex native session takeover planning, confirmed termination safeguards, fork summary confirmation, and native `codex exec resume` follow-up delivery.
+
+### Changed
+
+- Updated Codex takeover sends to use native `codex exec resume` for adopted Codex sessions, avoiding ACPX session binding issues when resuming existing terminal Codex sessions.
 
 ## 0.1.2 - 2026-06-21
 

package/README.md

@@ -140,7 +140,6 @@ akk list
 akk send <conversation-id>: continue with the smaller implementation
 akk cancel <conversation-id>
 akk recover <conversation-id>
-akk restart <conversation-id>
 akk close <conversation-id>
 ```
 
@@ -156,7 +155,6 @@ The plugin also registers the `/akk` slash command for channel surfaces that sup
 /akk send <conversation-id> <message>
 /akk cancel <conversation-id>
 /akk recover <conversation-id>
-/akk restart <conversation-id>
 /akk close <conversation-id> [reason]
 ```
 
@@ -172,7 +170,6 @@ If your OpenClaw config uses a restrictive tool allowlist, allow the tool:
       "agent_knock_knock_send",
       "agent_knock_knock_cancel",
       "agent_knock_knock_recover",
-      "agent_knock_knock_restart",
       "agent_knock_knock_close"
     ]
   }
@@ -189,13 +186,15 @@ New delegations create a fresh ACPX session by default, using a name like `akk-c
 
 Background launches also start a small AKK monitor process. The monitor exits when the conversation receives a callback or otherwise leaves the agent-waiting state. If the executor process disappears before a callback, or if no callback arrives before `agentTimeoutMinutes`, the conversation is marked `stalled` and AKK attempts to notify the original OpenClaw session through the callback Gateway route. The default agent timeout is 60 minutes.
 
-Some coding agents may not reliably resume a named ACPX session after their backing process disappears. Executors can opt into an explicit recovery decision flow. In that mode, a failed follow-up send marks the AKK conversation `needs_recovery` instead of automatically replaying history or starting a new session. The user can then choose:
+Some coding agents may not reliably resume a named ACPX session after their backing process disappears. By default, `AKK send <conversation-id>: <message>` automatically falls back to AKK replay recovery: it starts a fresh ACPX session, gives the agent a bounded summary of AKK's saved protocol history, and includes the pending message. The result includes `auto_recovered: true` when this happens.
+
+If a caller uses the explicit recovery policy, or if automatic recovery cannot complete, the AKK conversation can enter `needs_recovery`. The user can then choose:
 
 - `AKK recover <conversation-id>`: start a new coding-agent session with AKK's saved protocol history summary plus the pending message.
-- `AKK restart <conversation-id>`: start a new coding-agent session with only the pending message.
 - `AKK close <conversation-id>`: close the AKK task without recovery.
+- Start a new independent AKK delegation if the old task should not be recovered.
 
-Codex and Claude Code currently use native named-session recovery through ACPX. Cursor uses the explicit decision flow because its native session resume can be unreliable after the backing process disappears.
+Recover is AKK replay recovery, not guaranteed native coding-agent session resume. Codex, Claude Code, and Cursor all use the same default `send` auto-recovery behavior when the existing ACPX session is unavailable.
 
 Task status can include a safe executor trace with `--trace` or the OpenClaw status tool's `trace: true` parameter. Trace summaries show client lifecycle events, tool call names and statuses, permission-request markers, monitor events, and short sanitized output previews. Agent thinking content is never returned; it is counted and marked as redacted.
 
@@ -256,16 +255,44 @@ node dist/src/cli.js cancel \
   --conversation <conversation-id>
 ```
 
-Recover or restart a task that is waiting for an explicit recovery decision:
+Recover a task that is waiting for an explicit recovery decision:
 
 ```bash
 node dist/src/cli.js recover \
   --conversation <conversation-id>
+```
 
-node dist/src/cli.js restart \
-  --conversation <conversation-id>
+Inspect and take over native Codex sessions that were started outside AKK:
+
+Experimental: native Codex takeover depends on best-effort local Codex session metadata, process scanning, and Codex CLI resume behavior. It may be unstable across Codex versions or unusual terminal states, so review the returned plan before confirming any takeover.
+
+```bash
+node dist/src/cli.js agent discover \
+  --agent codex \
+  --scope active
+
+node dist/src/cli.js agent takeover \
+  --agent codex \
+  --session-id <native-codex-session-id> \
+  --strategy terminate_then_resume
+```
+
+`terminate_then_resume` is intentionally two-step. The first command returns the exact pid, cwd, and session that would be stopped. After confirming that plan, execute the takeover:
+
+```bash
+node dist/src/cli.js agent takeover \
+  --agent codex \
+  --session-id <native-codex-session-id> \
+  --strategy terminate_then_resume \
+  --create-conversation \
+  --confirm-terminate \
+  --expected-pid <confirmed-pid>
 ```
 
+AKK re-scans before terminating and only proceeds when the confirmed pid is still an exact match for the requested Codex session. After the process exits, AKK creates a managed conversation and future sends use native `codex exec resume`.
+
+Some Codex TUI processes do not expose the native session id in argv. In that case the default takeover remains blocked as ambiguous. For a deliberate local test or an operator-confirmed handoff, add `--allow-cwd-only` with `--expected-pid`; AKK will still re-scan and require that pid to be active in the target session cwd before terminating it.
+
 Close a task locally:
 
 ```bash

package/dist/src/agent-session-provider.d.ts

@@ -0,0 +1,25 @@
+import type { ActiveCodexProcess, CodexSessionModelInfo, CodexSessionSummary, ForkContextPackage, RolloutExcerptOptions } from "./codex-session-provider.js";
+export type CodingAgentSessionProviderAgent = "codex";
+export type HistoricalSessionCapability = "full" | "metadata_only" | "unavailable";
+export type ForkContextCapability = "full" | "partial" | "unavailable";
+export type ActiveSessionCapability = "process_scan" | "unavailable";
+export type TakeoverCapability = "plan_only" | "unavailable";
+export interface AgentSessionCapabilities {
+    historicalSessions: HistoricalSessionCapability;
+    forkContext: ForkContextCapability;
+    activeSessions: ActiveSessionCapability;
+    takeover: TakeoverCapability;
+    reasons: string[];
+}
+export interface ForkContextOptions extends RolloutExcerptOptions {
+    sessionId: string;
+}
+export interface CodingAgentSessionProvider {
+    agent: CodingAgentSessionProviderAgent;
+    getCapabilities(): Promise<AgentSessionCapabilities>;
+    listHistoricalSessions(): Promise<CodexSessionSummary[]>;
+    listActiveSessions(): Promise<ActiveCodexProcess[]>;
+    getSession(sessionId: string): Promise<CodexSessionSummary | undefined>;
+    getSessionModel(sessionId: string): Promise<CodexSessionModelInfo | undefined>;
+    getForkContext(options: ForkContextOptions): Promise<ForkContextPackage | undefined>;
+}

package/dist/src/agent-session-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-session-provider.js.map

package/dist/src/agent-session-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-provider.js","sourceRoot":"","sources":["../../src/agent-session-provider.ts"],"names":[],"mappings":""}