@scotthuang/agent-knock-knock 0.12.11 → 0.12.12

package/dist/src/value-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-guards.js","sourceRoot":"","sources":["../../src/value-guards.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACzD,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7C,CAAC"}

package/dist/src/verified-dead-agent-policy.d.ts

@@ -0,0 +1,192 @@
+import type { ExecutorKind } from "./executors.js";
+import type { TerminalControlEvidence, TerminalControlRef } from "./terminal-control-ref.js";
+export type VerifiedDeadTerminalAgentProcessProof = {
+    kind: "exact_pid_absent_from_complete_process_inventory";
+    agent: ExecutorKind;
+    pid: number;
+    process_uuid: string;
+    process_birth?: string;
+    conversation_id: string;
+    session_id: string;
+    turn_id: string;
+    terminal_control: TerminalControlRef;
+    terminal_endpoint: TerminalControlEvidence;
+    binding_id: string;
+    binding_generation: number;
+    message_id: string;
+    observed_at: string;
+};
+export type BoundTerminalAgentProcessObservation = {
+    status: "alive";
+    pid: number;
+} | {
+    status: "verified_dead";
+    proof: VerifiedDeadTerminalAgentProcessProof;
+} | {
+    status: "unverifiable";
+    reason: string;
+};
+export type VerifiedDeadAgentAuthorityDecision = {
+    status: "absent";
+} | {
+    status: "valid";
+    proof: VerifiedDeadTerminalAgentProcessProof;
+    evidenceId: string;
+    recordedAt: string;
+} | {
+    status: "invalid";
+    reason: string;
+};
+export type VerifiedDeadAgentAuthorityContext = {
+    terminalControl: TerminalControlRef;
+    conversation: {
+        agent: ExecutorKind;
+        conversationId: string;
+        sessionId: string;
+        turnId: string;
+        bindingId?: string;
+        bindingGeneration: number;
+    };
+    session?: {
+        status: string;
+        agent: ExecutorKind;
+        workspaceMatchesConversation: boolean;
+        binding?: {
+            terminalControl: TerminalControlRef;
+            pid: number;
+            processUuid?: string;
+            processBirth?: string;
+            bindingId: string;
+            generation: number;
+        };
+    };
+    takeover?: {
+        pid: number;
+        processUuid?: string;
+        processBirth?: string;
+        bindingId?: string;
+        bindingGeneration: number;
+        messageId?: string;
+    };
+    submission?: {
+        status?: string;
+        sessionId?: string;
+        turnId?: string;
+        messageId?: string;
+        bindingId?: string;
+        bindingGeneration: number;
+    };
+};
+export type VerifiedDeadAgentProcessDecision = {
+    status: "absent";
+} | {
+    status: "invalid";
+    reason: string;
+} | {
+    status: "alive";
+    pid: number;
+} | {
+    status: "unverifiable";
+    reason: string;
+} | {
+    status: "verified_dead";
+    proof: VerifiedDeadTerminalAgentProcessProof;
+    source: "persisted" | "observation";
+};
+export type VerifiedDeadAgentProcessInput = {
+    persistedAuthority: VerifiedDeadAgentAuthorityDecision;
+    observation?: BoundTerminalAgentProcessObservation;
+};
+type PersistedVerifiedDeadAgentProcessDecision = Extract<VerifiedDeadAgentProcessDecision, {
+    status: "absent" | "invalid" | "verified_dead";
+}>;
+type ObservedVerifiedDeadAgentProcessDecision = Exclude<VerifiedDeadAgentProcessDecision, {
+    status: "absent";
+}>;
+type FreshVerifiedDeadAgentProcessDecision = Exclude<ObservedVerifiedDeadAgentProcessDecision, {
+    status: "invalid";
+}>;
+export type AcceptedTurnDeadAgentStallInput = {
+    conversationStatus: string;
+    terminalBridge: boolean;
+    messageId?: string;
+    submissionStatus?: string;
+    submissionMessageId?: string;
+    deferredTransferId?: string;
+    deferredTransferStatus?: string;
+};
+export type AcceptedTurnDeadAgentStallDecision = {
+    status: "applicable";
+} | {
+    status: "not_applicable";
+} | {
+    status: "requires_deferred_transfer";
+    transferId: string;
+};
+export type VerifiedDeadAgentCompletionObservation<T> = {
+    status: "present";
+    completion: T;
+} | {
+    status: "absent";
+} | {
+    status: "unverifiable";
+    reason: string;
+};
+export type VerifiedDeadAgentCompletionDecision<T> = {
+    action: "complete";
+    completion: T;
+} | {
+    action: "stall";
+    completionObservation: "absent" | "unverifiable";
+    resultReason: "bound_agent_process_verified_dead" | "bound_agent_process_verified_dead_completion_unverifiable";
+};
+type EventRecord = Readonly<Record<string, unknown>>;
+type VerifiedDeadAgentEventSelection = {
+    status: "absent";
+} | {
+    status: "candidate";
+    proof: VerifiedDeadTerminalAgentProcessProof;
+    evidenceId: string;
+    recordedAt: string;
+} | {
+    status: "invalid";
+    reason: string;
+};
+export declare function isVerifiedDeadAgentProcessDisposition(disposition: unknown): boolean;
+export declare function verifiedDeadTerminalAgentProcessEvidenceId(proof: VerifiedDeadTerminalAgentProcessProof): string;
+export declare function validateStoredVerifiedDeadAgentAuthority({ disposition, context }: {
+    disposition: unknown;
+    context: VerifiedDeadAgentAuthorityContext;
+}): VerifiedDeadAgentAuthorityDecision;
+export declare function selectVerifiedDeadAgentEvent({ events, conversationId }: {
+    events: readonly EventRecord[];
+    conversationId: string;
+}): VerifiedDeadAgentEventSelection;
+export declare function validateVerifiedDeadAgentEventAuthority({ candidate, context }: {
+    candidate: Extract<VerifiedDeadAgentEventSelection, {
+        status: "candidate";
+    }>;
+    context: VerifiedDeadAgentAuthorityContext;
+}): VerifiedDeadAgentAuthorityDecision;
+export declare function reconcileVerifiedDeadAgentAuthority({ stored, event }: {
+    stored: VerifiedDeadAgentAuthorityDecision;
+    event: VerifiedDeadAgentAuthorityDecision;
+}): VerifiedDeadAgentAuthorityDecision;
+export declare function decideVerifiedDeadAgentProcess(input: {
+    persistedAuthority: VerifiedDeadAgentAuthorityDecision;
+    observation?: undefined;
+}): PersistedVerifiedDeadAgentProcessDecision;
+export declare function decideVerifiedDeadAgentProcess(input: {
+    persistedAuthority: {
+        status: "absent";
+    };
+    observation: BoundTerminalAgentProcessObservation;
+}): FreshVerifiedDeadAgentProcessDecision;
+export declare function decideVerifiedDeadAgentProcess(input: {
+    persistedAuthority: VerifiedDeadAgentAuthorityDecision;
+    observation: BoundTerminalAgentProcessObservation;
+}): ObservedVerifiedDeadAgentProcessDecision;
+export declare function decideVerifiedDeadAgentProcess(input: VerifiedDeadAgentProcessInput): VerifiedDeadAgentProcessDecision;
+export declare function decideAcceptedTurnDeadAgentStall(input: AcceptedTurnDeadAgentStallInput): AcceptedTurnDeadAgentStallDecision;
+export declare function decideVerifiedDeadAgentCompletion<T>(observation: VerifiedDeadAgentCompletionObservation<T>): VerifiedDeadAgentCompletionDecision<T>;
+export {};

package/dist/src/verified-dead-agent-policy.js

@@ -0,0 +1,262 @@
+import { createHash } from "node:crypto";
+import { sameTerminalControlIncarnation, terminalControlEvidenceMatches, terminalEndpointFromControlRef, terminalEndpointIdentityKey } from "./terminal-control-ref.js";
+import { canonicalJson } from "./canonical-json.js";
+import { isRecord, nonBlankString as stringValue } from "./value-guards.js";
+export function isVerifiedDeadAgentProcessDisposition(disposition) {
+    return isRecord(disposition) && disposition.status === "verified_dead";
+}
+export function verifiedDeadTerminalAgentProcessEvidenceId(proof) {
+    return createHash("sha256")
+        .update(canonicalJson({
+        kind: proof.kind,
+        agent: proof.agent,
+        pid: proof.pid,
+        process_uuid: proof.process_uuid,
+        process_birth: proof.process_birth ?? null,
+        conversation_id: proof.conversation_id,
+        session_id: proof.session_id,
+        turn_id: proof.turn_id,
+        terminal_endpoint: proof.terminal_endpoint,
+        binding_id: proof.binding_id,
+        binding_generation: proof.binding_generation,
+        message_id: proof.message_id
+    }))
+        .digest("hex");
+}
+export function validateStoredVerifiedDeadAgentAuthority({ disposition, context }) {
+    if (!isVerifiedDeadAgentProcessDisposition(disposition)) {
+        return { status: "absent" };
+    }
+    const proof = isRecord(disposition) && isRecord(disposition.proof)
+        ? disposition.proof
+        : undefined;
+    const evidenceId = isRecord(disposition)
+        ? stringValue(disposition.evidence_id)
+        : undefined;
+    const recordedAt = isRecord(disposition)
+        ? stringValue(disposition.recorded_at)
+        : undefined;
+    return validateVerifiedDeadAgentEvidence({
+        proof,
+        evidenceId,
+        recordedAt,
+        context
+    });
+}
+export function selectVerifiedDeadAgentEvent({ events, conversationId }) {
+    const candidates = events.filter((event) => event.event === "terminal_agent_process_verified_dead" &&
+        event.conversation_id === conversationId);
+    if (candidates.length === 0) {
+        return { status: "absent" };
+    }
+    if (candidates.length !== 1) {
+        return {
+            status: "invalid",
+            reason: "the process-death event history is ambiguous"
+        };
+    }
+    const event = candidates[0];
+    const proof = isRecord(event.proof)
+        ? event.proof
+        : undefined;
+    const evidenceId = stringValue(event.evidence_id);
+    const recordedAt = stringValue(event.ts);
+    if (!proof ||
+        !evidenceId ||
+        !recordedAt ||
+        proof.observed_at !== recordedAt ||
+        verifiedDeadTerminalAgentProcessEvidenceId(proof) !== evidenceId) {
+        return {
+            status: "invalid",
+            reason: "the process-death event proof is malformed"
+        };
+    }
+    return {
+        status: "candidate",
+        proof,
+        evidenceId,
+        recordedAt
+    };
+}
+export function validateVerifiedDeadAgentEventAuthority({ candidate, context }) {
+    return validateVerifiedDeadAgentEvidence({
+        proof: candidate.proof,
+        evidenceId: candidate.evidenceId,
+        recordedAt: candidate.recordedAt,
+        context
+    });
+}
+export function reconcileVerifiedDeadAgentAuthority({ stored, event }) {
+    if (stored.status === "invalid") {
+        return stored;
+    }
+    if (stored.status === "absent") {
+        return event;
+    }
+    if (event.status !== "valid" ||
+        event.evidenceId !== stored.evidenceId ||
+        canonicalJson(event.proof) !== canonicalJson(stored.proof)) {
+        return {
+            status: "invalid",
+            reason: "the persisted process-death disposition has no exact append-only event"
+        };
+    }
+    return stored;
+}
+export function decideVerifiedDeadAgentProcess({ persistedAuthority, observation }) {
+    if (persistedAuthority.status === "invalid") {
+        return persistedAuthority;
+    }
+    if (persistedAuthority.status === "valid") {
+        return {
+            status: "verified_dead",
+            proof: persistedAuthority.proof,
+            source: "persisted"
+        };
+    }
+    if (!observation) {
+        return { status: "absent" };
+    }
+    if (observation.status === "verified_dead") {
+        return {
+            status: "verified_dead",
+            proof: observation.proof,
+            source: "observation"
+        };
+    }
+    return observation;
+}
+export function decideAcceptedTurnDeadAgentStall(input) {
+    if (input.conversationStatus !== "waiting_for_agent" ||
+        input.terminalBridge !== true ||
+        !input.messageId ||
+        input.submissionStatus !== "agent_accepted" ||
+        input.submissionMessageId !== input.messageId) {
+        return { status: "not_applicable" };
+    }
+    if (!input.deferredTransferId) {
+        return { status: "applicable" };
+    }
+    if (input.deferredTransferStatus === undefined) {
+        return {
+            status: "requires_deferred_transfer",
+            transferId: input.deferredTransferId
+        };
+    }
+    return input.deferredTransferStatus === "resolved"
+        ? { status: "applicable" }
+        : { status: "not_applicable" };
+}
+export function decideVerifiedDeadAgentCompletion(observation) {
+    if (observation.status === "present") {
+        return { action: "complete", completion: observation.completion };
+    }
+    return observation.status === "unverifiable"
+        ? {
+            action: "stall",
+            completionObservation: "unverifiable",
+            resultReason: "bound_agent_process_verified_dead_completion_unverifiable"
+        }
+        : {
+            action: "stall",
+            completionObservation: "absent",
+            resultReason: "bound_agent_process_verified_dead"
+        };
+}
+function validateVerifiedDeadAgentEvidence({ proof, evidenceId, recordedAt, context }) {
+    const candidate = isRecord(proof)
+        ? proof
+        : undefined;
+    const session = context.session;
+    const binding = session?.binding;
+    const takeover = context.takeover;
+    const submission = context.submission;
+    if (!candidate ||
+        candidate.kind !==
+            "exact_pid_absent_from_complete_process_inventory" ||
+        !session ||
+        session.status !== "bound" ||
+        !binding ||
+        candidate.agent !== session.agent ||
+        session.agent !== context.conversation.agent ||
+        !session.workspaceMatchesConversation ||
+        candidate.pid !== takeover?.pid ||
+        candidate.pid !== binding.pid ||
+        candidate.process_uuid !== takeover?.processUuid ||
+        candidate.process_uuid !== binding.processUuid ||
+        (candidate.process_birth ?? undefined) !==
+            (takeover?.processBirth ?? undefined) ||
+        (candidate.process_birth ?? undefined) !==
+            (binding.processBirth ?? undefined) ||
+        candidate.conversation_id !== context.conversation.conversationId ||
+        candidate.session_id !== context.conversation.sessionId ||
+        candidate.turn_id !== context.conversation.turnId ||
+        candidate.binding_id !== context.conversation.bindingId ||
+        candidate.binding_id !== binding.bindingId ||
+        candidate.binding_generation !==
+            context.conversation.bindingGeneration ||
+        candidate.binding_generation !== binding.generation ||
+        !terminalControlsShareIncarnation(binding.terminalControl, context.terminalControl) ||
+        candidate.binding_id !== takeover?.bindingId ||
+        candidate.binding_generation !== takeover?.bindingGeneration ||
+        candidate.message_id !== takeover?.messageId ||
+        candidate.message_id !== submission?.messageId ||
+        submission?.status !== "agent_accepted" ||
+        submission.sessionId !== candidate.session_id ||
+        submission.turnId !== candidate.turn_id ||
+        submission.bindingId !== candidate.binding_id ||
+        submission.bindingGeneration !== candidate.binding_generation ||
+        !isRecord(candidate.terminal_control) ||
+        !terminalControlsShareIncarnation(candidate.terminal_control, context.terminalControl) ||
+        !terminalControlEvidenceMatches(candidate.terminal_endpoint, context.terminalControl, { requireProcessAnchor: true }) ||
+        Number(candidate.terminal_endpoint.process_anchor_pid) !==
+            terminalEndpointFromControlRef(context.terminalControl).processAnchorPid ||
+        validTimestampMs(candidate.observed_at) === undefined ||
+        !recordedAt ||
+        validTimestampMs(recordedAt) === undefined ||
+        recordedAt !== candidate.observed_at ||
+        !evidenceId ||
+        evidenceId !== verifiedDeadTerminalAgentProcessEvidenceId(candidate)) {
+        return {
+            status: "invalid",
+            reason: "the persisted process-death proof no longer matches the exact Turn, Session, terminal, or submission binding"
+        };
+    }
+    return {
+        status: "valid",
+        proof: candidate,
+        evidenceId,
+        recordedAt
+    };
+}
+function terminalControlsShareIncarnation(left, right) {
+    if (!terminalControlIncarnationSelectorKey(left) ||
+        !terminalControlIncarnationSelectorKey(right)) {
+        return false;
+    }
+    return sameTerminalControlIncarnation(left, right);
+}
+function terminalControlIncarnationSelectorKey(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    try {
+        const endpoint = terminalEndpointFromControlRef(value);
+        const processAnchorPid = Number(endpoint.processAnchorPid);
+        if (!Number.isSafeInteger(processAnchorPid) || processAnchorPid <= 1) {
+            return undefined;
+        }
+        return JSON.stringify({
+            identity: terminalEndpointIdentityKey(endpoint),
+            process_anchor_pid: processAnchorPid
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+function validTimestampMs(value) {
+    const parsed = Date.parse(String(value ?? ""));
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+//# sourceMappingURL=verified-dead-agent-policy.js.map

package/dist/src/verified-dead-agent-policy.js.map

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

package/docs/quickstart-tmux.md

@@ -89,7 +89,7 @@ Starting a new native context, clearing it, or resuming an older native thread i
 
 Omitting the resume selection lists exact verified candidates. You may use the complete UUID, the deterministic number or collision-safe `@short-id` from that same displayed snapshot, or its opaque snapshot handle. Numbers and short IDs are valid only for the latest list shown in the same OpenClaw session; handles, too, expire after five minutes and any relevant terminal, process, workspace, binding, or candidate change. `previous` / `刚才那个` works only when the list advertises a single verified source from the current Session's latest committed lifecycle transition; AKK never treats “previous” as “newest”. These display selectors are resolved back to the complete UUID and exact saved tokens before the native Resume path runs. A successful switch creates or activates an AKK Session but creates no Turn, so send the next request separately. There is no background binding poll: after an old coding-agent process exits, the next lifecycle listing can expose its sole historical Session as resumable, and resume safely detaches that stale binding before terminal input. Unsupported, busy, ambiguous, stale, expired, active-elsewhere, or unverifiable transitions stop without falling back to raw `/clear`, `/new`, `/resume`, `/status`, Codex `/fork`, `/side`, or `/btw`, or Claude `/branch` text.
 
-AKK Turn status and the coding agent's native status are separate. `/akk status` and `agent_knock_knock_status` inspect AKK-managed state and a bounded current screen; they never type `/status`. For native status, start from `/akk list` and use only an advertised `native_inspect` action through `agent_knock_knock_native_inspect`, preserving its exact `terminal_id`, `inspection="status"`, and `expected_binding_token`. Supported profiles are Codex 0.146.0/0.146.1/0.147.0 and Claude Code 2.1.218/2.1.226. Claude's modal Status panel is parsed and dismissed before the action proves the original idle composer. The action creates no Session, Turn, receipt, monitor, or callback. `/usage`, `/cost`, `/stats`, `/usage-credits`, `/model`, `/compact`, and arbitrary slash commands remain unavailable. Bare Codex `/usage` is not read-only automation: it opens a menu whose later Enter can select an account-side usage-limit reset.
+AKK Turn status and the coding agent's native status are separate. `/akk status` and `agent_knock_knock_status` inspect AKK-managed state and a bounded current screen; they never type `/status`. For native status, start from `/akk list` and use only an advertised `native_inspect` action through `agent_knock_knock_native_inspect`, preserving its exact `terminal_id`, `inspection="status"`, and `expected_binding_token`. Supported profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0 and Claude Code 2.1.218/2.1.226/2.1.237. Claude's modal Status panel is parsed and dismissed before the action proves the original idle composer. The action creates no Session, Turn, receipt, monitor, or callback. `/usage`, `/cost`, `/stats`, `/usage-credits`, `/model`, `/compact`, and arbitrary slash commands remain unavailable. Bare Codex `/usage` is not read-only automation: it opens a menu whose later Enter can select an account-side usage-limit reset.
 
 ## Optional: Enable natural-language routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scotthuang/agent-knock-knock",
-  "version": "0.12.11",
+  "version": "0.12.12",
   "description": "Control local Codex and Claude Code from OpenClaw through shared tmux or Herdr terminals, with seamless human-agent handoff.",
   "license": "MIT",
   "type": "module",
@@ -73,6 +73,8 @@
     "build": "npm run clean && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate:architecture": "node scripts/validate-architecture.js",
+    "validate:refactor-evidence": "node scripts/validate-refactor-evidence.js",
     "test": "npm run test:full",
     "test:fast": "npm run build && node scripts/run-test-tier.js fast",
     "test:integration": "npm run build && node scripts/run-test-tier.js integration",

package/templates/openclaw-skills/agent-knock-knock/SKILL.md

@@ -81,7 +81,7 @@ Do not treat ordinary send as native clear, new-session, fork, branch, side thre
 For native status inspection:
 
 1. Use only a current `available_actions.native_inspect` entry. Its structured arguments are authoritative and complete; never construct or reuse them.
-2. Supported exact profiles are Codex 0.146.0/0.146.1/0.147.0 and Claude Code 2.1.218/2.1.226 `inspection="status"`. Claude success includes parsing and safely dismissing the newly opened Status panel. The tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, `/model`, `/compact`, and unsupported versions remain unavailable. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
+2. Supported exact profiles are Codex 0.146.0/0.146.1/0.147.0/0.148.0 and Claude Code 2.1.218/2.1.226/2.1.237 `inspection="status"`. Claude success includes parsing and safely dismissing the newly opened Status panel. The tool does not accept `/status` text or any arbitrary command string. `/usage`, `/cost`, `/stats`, `/usage-credits`, `/model`, `/compact`, and unsupported versions remain unavailable. Never automate bare Codex `/usage`: it opens an interactive menu whose later Enter can select an account-side usage-limit reset.
 3. Treat this as terminal input even though the native command is read-only. AKK requires an idle empty composer, fresh binding token, exact PID/process/pane/cwd/version identity, and no conflicting Turn, transition, dispatch, approval, or owner.
 4. Codex `/status` requires an exact viewport of at least 80 columns so the full Session UUID can be proven. That pre-UUID gate applies to native inspection, lifecycle, and strict Session operations that must know the UUID before terminal input. An otherwise eligible terminal-scoped ordinary task may send once and bind from exact native acceptance afterward, so it does not run `/status` or fail merely because the pane is narrow.
 5. The result is valid only when AKK proves one fresh bounded native status result and the pane returns to idle. On an uncertain or unproven submission, do not retry, send Enter, clear the composer, or bypass AKK with raw terminal input.