@scotthuang/agent-knock-knock 0.12.11 → 0.12.13

package/dist/src/terminal-binding-authority.js

@@ -0,0 +1,245 @@
+import { isExactNativeThreadId } from "./managed-session.js";
+import { nonBlankString as stringValue, recordValue } from "./value-guards.js";
+export function isCompleteNativeRollout(value) {
+    const rollout = recordValue(value);
+    return Boolean(rollout &&
+        stringValue(rollout.fd) &&
+        stringValue(rollout.device) &&
+        stringValue(rollout.inode) &&
+        stringValue(rollout.path));
+}
+export function terminalNativeIdentityFence(identity) {
+    const sessionId = stringValue(identity?.sessionId);
+    const processUuid = stringValue(identity?.processUuid);
+    const processBirth = stringValue(identity?.processBirth);
+    return sessionId && processUuid && processBirth &&
+        isCompleteNativeRollout(identity?.rollout)
+        ? {
+            sessionId,
+            processUuid,
+            processBirth,
+            rollout: identity.rollout
+        }
+        : undefined;
+}
+export function terminalNativeIdentityMatchesFence(identity, expected) {
+    const identitySessionId = stringValue(identity?.sessionId);
+    const identityProcessUuid = stringValue(identity?.processUuid);
+    const identityProcessBirth = stringValue(identity?.processBirth);
+    const expectedSessionId = stringValue(expected?.sessionId);
+    const expectedProcessUuid = stringValue(expected?.processUuid);
+    const expectedProcessBirth = stringValue(expected?.processBirth);
+    return Boolean(identity && expected &&
+        identitySessionId && identitySessionId === expectedSessionId &&
+        identityProcessUuid && identityProcessUuid === expectedProcessUuid &&
+        identityProcessBirth && identityProcessBirth === expectedProcessBirth &&
+        isCompleteNativeRollout(identity.rollout) &&
+        isCompleteNativeRollout(expected.rollout) &&
+        identity.rollout.fd === expected.rollout.fd &&
+        identity.rollout.device === expected.rollout.device &&
+        identity.rollout.inode === expected.rollout.inode &&
+        identity.rollout.path === expected.rollout.path);
+}
+/** Build the list-side observation without importing CLI orchestration. */
+export function terminalObservationFromListEntry(terminal, agent) {
+    const liveThreadId = stringValue(terminal.native_agent_session_id);
+    const liveRollout = isCompleteNativeRollout(terminal.native_agent_rollout)
+        ? terminal.native_agent_rollout
+        : undefined;
+    let nativeIdentity;
+    if (liveThreadId) {
+        nativeIdentity = {
+            status: "resolved",
+            identity: {
+                sessionId: liveThreadId,
+                processUuid: stringValue(terminal.native_agent_process_uuid),
+                processBirth: stringValue(terminal.native_agent_process_birth),
+                rollout: liveRollout,
+                evidence: stringValue(terminal.native_agent_identity_evidence) ??
+                    "terminal_scan"
+            }
+        };
+    }
+    else {
+        const identityObservation = recordValue(terminal.native_agent_identity_observation);
+        nativeIdentity = identityObservation?.status === "verified_absent"
+            ? {
+                status: "verified_absent",
+                evidence: stringValue(identityObservation.evidence)
+            }
+            : identityObservation?.status === "unavailable"
+                ? {
+                    status: "unavailable",
+                    reason: stringValue(identityObservation.reason)
+                }
+                : { status: "not_observed" };
+    }
+    return {
+        agent,
+        pid: Number(terminal.pid),
+        nativeIdentity,
+        processIncarnation: {
+            processUuid: stringValue(terminal.native_agent_process_uuid),
+            processBirth: stringValue(terminal.native_agent_process_birth)
+        },
+        statusCardNativeThreadId: stringValue(terminal.native_agent_status_card_session_id),
+        codexOpenRootInventory: recordValue(terminal._codex_open_root_rollout_inventory)
+    };
+}
+/** Build the mutation-side observation from evidence freshly read under lock. */
+export function terminalObservationFromResolvedIdentity({ agent, pid, identity, processIncarnation }) {
+    return {
+        agent,
+        pid,
+        nativeIdentity: identity
+            ? { status: "resolved", identity }
+            : { status: "not_observed" },
+        processIncarnation
+    };
+}
+export function classifyTerminalBindingConflict(facts) {
+    const { session, processRelationship } = facts;
+    const binding = session.binding;
+    if (!binding || processRelationship === "different") {
+        return "stale_process_incarnation";
+    }
+    const boundThreadId = exactThreadId(binding.native_thread_id);
+    const liveThreadId = exactThreadId(facts.liveNativeThreadId);
+    const statusCardThreadId = exactThreadId(facts.statusCardNativeThreadId);
+    if (boundThreadId && statusCardThreadId &&
+        boundThreadId !== statusCardThreadId) {
+        return processRelationship === "same" && (liveThreadId === statusCardThreadId || liveThreadId === boundThreadId) ? "live_external_thread_change" : "unverifiable";
+    }
+    if (session.lineage.created_by === "attach" &&
+        !session.last_transition_id &&
+        !binding.native_thread_id &&
+        !binding.native_process.rollout &&
+        facts.managedTurnCount === 0) {
+        return "provisional_orphan";
+    }
+    return processRelationship === "same" &&
+        boundThreadId && liveThreadId && boundThreadId !== liveThreadId
+        ? "live_external_thread_change"
+        : "unverifiable";
+}
+function exactThreadId(value) {
+    return isExactNativeThreadId(value) ? value.toLowerCase() : undefined;
+}
+/**
+ * Pure exact-binding policy shared by read-only projection and mutation
+ * preparation. Store, process and filesystem evidence is gathered by the
+ * caller and supplied explicitly so this function cannot widen authorization
+ * or change I/O ordering.
+ */
+export function decideTerminalBindingMatch(session, observation, evidence) {
+    const binding = session.binding;
+    if (session.status !== "bound") {
+        return { state: "unrelated", reason: "session_not_bound" };
+    }
+    if (!binding) {
+        return { state: "unrelated", reason: "missing_binding" };
+    }
+    if (session.agent !== observation.agent) {
+        return { state: "unrelated", reason: "agent_mismatch" };
+    }
+    if (binding.native_process.pid !== observation.pid) {
+        return { state: "unrelated", reason: "pid_mismatch" };
+    }
+    if (!evidence.terminalAliasMatches) {
+        return { state: "unrelated", reason: "terminal_alias_mismatch" };
+    }
+    if (!evidence.workspaceMatches) {
+        return { state: "unrelated", reason: "workspace_mismatch" };
+    }
+    const nativeIdentity = observation.nativeIdentity.status === "resolved"
+        ? observation.nativeIdentity.identity
+        : undefined;
+    if (isExactNativeThreadId(binding.native_thread_id) &&
+        isExactNativeThreadId(observation.statusCardNativeThreadId) &&
+        binding.native_thread_id.toLowerCase() !==
+            observation.statusCardNativeThreadId.toLowerCase()) {
+        return { state: "not_exact", reason: "status_card_thread_mismatch" };
+    }
+    if (!nativeIdentity) {
+        if (codexOpenRootRolloutMatchesBinding(session, observation)) {
+            return { state: "exact", basis: "codex_open_root_rollout" };
+        }
+        if (codexStatusCardProcessMatchesBinding(session, observation)) {
+            return { state: "exact", basis: "codex_status_card_process" };
+        }
+        return { state: "not_exact", reason: "native_identity_absent" };
+    }
+    if (nativeIdentityMatchesBinding(session, nativeIdentity)) {
+        return { state: "exact", basis: "native_identity" };
+    }
+    if (evidence.codexLingeringBeforeMatches === true &&
+        session.agent === "codex" &&
+        Boolean(binding.native_thread_id) &&
+        !binding.native_process.rollout &&
+        isCodexStatusCardEvidence(binding.native_process.evidence)) {
+        return { state: "exact", basis: "codex_lingering_before" };
+    }
+    return { state: "not_exact", reason: "native_identity_mismatch" };
+}
+function nativeIdentityMatchesBinding(session, identity) {
+    const binding = session.binding;
+    return Boolean(binding &&
+        binding.native_thread_id === identity.sessionId &&
+        (!binding.native_process.process_uuid ||
+            binding.native_process.process_uuid === identity.processUuid) &&
+        (!binding.native_process.process_birth ||
+            binding.native_process.process_birth === identity.processBirth) &&
+        (!binding.native_process.rollout ||
+            exactRolloutMatches(binding.native_process.rollout, identity.rollout)));
+}
+function codexOpenRootRolloutMatchesBinding(session, observation) {
+    const binding = session.binding;
+    const inventory = observation.codexOpenRootInventory;
+    const boundRollout = binding?.native_process.rollout;
+    if (session.agent !== "codex" ||
+        !binding?.native_thread_id ||
+        !isCompleteNativeRollout(boundRollout) ||
+        !inventory) {
+        return false;
+    }
+    const candidate = inventory.roots.find((root) => root.sessionId.toLowerCase() === binding.native_thread_id?.toLowerCase());
+    return Boolean(candidate &&
+        exactRolloutMatches(candidate.rollout, boundRollout) &&
+        inventory.pid === binding.native_process.pid &&
+        inventory.processUuid === binding.native_process.process_uuid &&
+        inventory.processBirth === binding.native_process.process_birth);
+}
+function codexStatusCardProcessMatchesBinding(session, observation) {
+    const binding = session.binding;
+    return Boolean(session.agent === "codex" &&
+        binding?.native_thread_id &&
+        isCodexStatusCardEvidence(binding.native_process.evidence) &&
+        binding.native_process.process_uuid &&
+        binding.native_process.process_birth &&
+        binding.native_process.process_uuid ===
+            observation.processIncarnation.processUuid &&
+        binding.native_process.process_birth ===
+            observation.processIncarnation.processBirth);
+}
+export function exactRolloutMatches(left, right) {
+    return Boolean(isCompleteNativeRollout(left) &&
+        isCompleteNativeRollout(right) &&
+        left.fd === right.fd &&
+        left.device === right.device &&
+        left.inode === right.inode &&
+        left.path === right.path);
+}
+export function candidateSourceRootAuthorityMatches(roots, sourceThreadId, sourceRollout, authority) {
+    const sourceId = exactThreadId(sourceThreadId);
+    if (!sourceId || !isCompleteNativeRollout(sourceRollout))
+        return false;
+    const sameSource = (root) => root.sessionId.toLowerCase() === sourceId;
+    return authority === "explicitly_abandoned_predecessor"
+        ? !roots.some(sameSource) &&
+            !roots.some((root) => exactRolloutMatches(root.rollout, sourceRollout))
+        : roots.some((root) => sameSource(root) && exactRolloutMatches(root.rollout, sourceRollout));
+}
+export function isCodexStatusCardEvidence(evidence) {
+    return evidence.split("+").includes("codex_status_card");
+}
+//# sourceMappingURL=terminal-binding-authority.js.map

package/dist/src/terminal-binding-authority.js.map

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

package/dist/src/terminal-binding-reconciliation-service.d.ts

@@ -0,0 +1,75 @@
+import type { ConversationStatus } from "./protocol.js";
+import { type ManagedSessionState } from "./managed-session.js";
+import { type CanonicalMutationLockPorts, type CanonicalMutationResources, type CanonicalMutationScopes } from "./mutation-transaction.js";
+import { type ManagedBindingConflictKind } from "./native-thread-transition-policy.js";
+import type { ExecutorKind } from "./executors.js";
+import type { TerminalControlRef } from "./terminal-control-ref.js";
+import type { TerminalNativeIdentity } from "./terminal-binding-authority.js";
+export interface BindingReconciliationTerminalFacts {
+    readonly conversationId: string;
+    readonly agent: ExecutorKind;
+    readonly pid: number;
+    readonly terminalControl: TerminalControlRef;
+}
+export interface BindingReconciliationStatusFacts {
+    readonly reachable: boolean;
+    readonly activity_state: string;
+    readonly activity_reason: string;
+    readonly approval_state: Readonly<{
+        blocked: boolean;
+    }>;
+}
+type Identity = TerminalNativeIdentity | undefined;
+type ScopeArgs = [CanonicalMutationScopes, CanonicalMutationResources];
+type Scoped<Args extends unknown[], Result> = (...args: [...ScopeArgs, ...Args]) => Result;
+type TurnBlocker = Readonly<{
+    turnId: string;
+    status: ConversationStatus;
+}>;
+export type BindingReconciliationRequest<Terminal extends BindingReconciliationTerminalFacts = BindingReconciliationTerminalFacts> = Readonly<{
+    initialTerminal: Terminal;
+    conflictingSessionId: string;
+    expectedSessionRevision: number;
+    expectedBindingToken: string;
+    expectedTerminalToken: string;
+}>;
+export type BindingReconciliationResult<Terminal extends BindingReconciliationTerminalFacts = BindingReconciliationTerminalFacts> = Readonly<{
+    terminal: Terminal;
+    detached: ManagedSessionState;
+    conflictKind: ManagedBindingConflictKind;
+}>;
+type BindingTransactionPort<Terminal extends BindingReconciliationTerminalFacts> = Readonly<{
+    locks: CanonicalMutationLockPorts;
+    recover: Scoped<[Terminal], Promise<void>>;
+    loadSession: Scoped<[string], ManagedSessionState>;
+    saveSession: Scoped<[
+        ManagedSessionState,
+        {
+            expectedRevision: number;
+        }
+    ], ManagedSessionState>;
+}>;
+type BindingTerminalPort<Terminal extends BindingReconciliationTerminalFacts, Status extends BindingReconciliationStatusFacts> = Readonly<{
+    resolve: () => Promise<Terminal>;
+    sameIncarnation: (left: unknown, right: unknown) => boolean;
+    identity: (terminal: Terminal) => Promise<Identity>;
+    prepareStatus: () => (terminal: Terminal) => Promise<Status>;
+    assertReady: (terminal: Terminal, status: Status) => void;
+}>;
+type BindingAuthorityPort<Terminal extends BindingReconciliationTerminalFacts> = Readonly<{
+    dispatchIsFree: (control: Terminal["terminalControl"]) => boolean;
+    sessionClaimsTerminal: (session: ManagedSessionState, terminal: Terminal) => boolean;
+    terminalTokenMatches: (terminal: Terminal, identity: Identity, token: string) => boolean;
+    hasUnresolvedTransition: (session: ManagedSessionState) => boolean;
+    blockingTurn: (sessionId: string) => TurnBlocker | undefined;
+    conflictKind: (session: ManagedSessionState, terminal: Terminal, identity: Identity) => ManagedBindingConflictKind | undefined;
+}>;
+export type BindingReconciliationPorts<Terminal extends BindingReconciliationTerminalFacts = BindingReconciliationTerminalFacts, Status extends BindingReconciliationStatusFacts = BindingReconciliationStatusFacts> = Readonly<{
+    transaction: BindingTransactionPort<Terminal>;
+    terminal: BindingTerminalPort<Terminal, Status>;
+    authority: BindingAuthorityPort<Terminal>;
+    now: () => string;
+    present: (result: BindingReconciliationResult<Terminal>) => void;
+}>;
+export declare function reconcileTerminalBinding<Terminal extends BindingReconciliationTerminalFacts, Status extends BindingReconciliationStatusFacts>(request: BindingReconciliationRequest<Terminal>, ports: BindingReconciliationPorts<Terminal, Status>): Promise<void>;
+export {};

package/dist/src/terminal-binding-reconciliation-service.js

@@ -0,0 +1,73 @@
+import { legacyManagedSessionBindingToken, managedSessionBindingToken } from "./managed-session.js";
+import { withCanonicalMutationLocks } from "./mutation-transaction.js";
+import { decideBindingReconciliation } from "./native-thread-transition-policy.js";
+const REJECTION_MESSAGES = {
+    stale_process_incarnation: "the stale process incarnation no longer requires explicit reconciliation; refresh AKK list",
+    already_exact: "the managed Session now exactly matches the live terminal; no reconciliation is needed",
+    unverifiable: "the managed binding conflict is unverifiable and cannot be detached automatically"
+};
+function requireCondition(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+function sameTerminal(port, candidate, expected) {
+    return candidate.pid === expected.pid &&
+        candidate.conversationId === expected.conversationId &&
+        port.sameIncarnation(candidate.terminalControl, expected.terminalControl);
+}
+function sessionTokenMatches(session, expected) {
+    return [
+        managedSessionBindingToken(session),
+        legacyManagedSessionBindingToken(session)
+    ].includes(expected);
+}
+export async function reconcileTerminalBinding(request, ports) {
+    const { authority, terminal, transaction } = ports;
+    return withCanonicalMutationLocks(transaction.locks, async (scopes, resources) => {
+        const current = await terminal.resolve();
+        requireCondition(sameTerminal(terminal, current, request.initialTerminal), "terminal identity changed while waiting to reconcile its binding; refresh AKK list");
+        await transaction.recover(scopes, resources, current);
+        requireCondition(authority.dispatchIsFree(current.terminalControl), "the terminal acquired an unresolved dispatch after the binding conflict was listed; refresh AKK list");
+        const session = transaction.loadSession(scopes, resources, request.conflictingSessionId);
+        requireCondition(session.revision === request.expectedSessionRevision &&
+            sessionTokenMatches(session, request.expectedBindingToken), "managed Session binding changed after it was listed; refresh AKK list");
+        requireCondition(authority.sessionClaimsTerminal(session, current), "the listed managed Session no longer claims this exact terminal");
+        const identity = await terminal.identity(current);
+        requireCondition(authority.terminalTokenMatches(current, identity, request.expectedTerminalToken), "live terminal identity changed after the conflict was listed; refresh AKK list");
+        const readStatus = terminal.prepareStatus();
+        requireCondition(!authority.hasUnresolvedTransition(session), `managed Session ${session.session_id} has an unresolved native-thread transition`);
+        const blocker = authority.blockingTurn(session.session_id);
+        if (blocker) {
+            throw new Error(`managed Session ${session.session_id} still has unresolved Turn ` +
+                `${blocker.turnId} (${blocker.status})`);
+        }
+        const finalTerminal = await terminal.resolve();
+        requireCondition(sameTerminal(terminal, finalTerminal, current), "terminal identity changed during binding reconciliation; refresh AKK list");
+        const finalStatus = await readStatus(finalTerminal);
+        terminal.assertReady(finalTerminal, finalStatus);
+        const finalIdentity = await terminal.identity(finalTerminal);
+        requireCondition(authority.terminalTokenMatches(finalTerminal, finalIdentity, request.expectedTerminalToken), "live terminal identity changed during binding reconciliation; refresh AKK list");
+        const finalSession = transaction.loadSession(scopes, resources, request.conflictingSessionId);
+        requireCondition(finalSession.revision === request.expectedSessionRevision &&
+            sessionTokenMatches(finalSession, request.expectedBindingToken), "managed Session binding changed during reconciliation; refresh AKK list");
+        const conflictKind = authority.conflictKind(finalSession, finalTerminal, finalIdentity);
+        const decision = decideBindingReconciliation(conflictKind);
+        if (decision.action === "reject") {
+            throw new Error(REJECTION_MESSAGES[decision.reason]);
+        }
+        const reconciledAt = ports.now();
+        const detached = transaction.saveSession(scopes, resources, {
+            ...finalSession,
+            status: "detached",
+            detached_at: reconciledAt,
+            updated_at: reconciledAt
+        }, { expectedRevision: request.expectedSessionRevision });
+        ports.present({
+            terminal: current,
+            detached,
+            conflictKind: conflictKind
+        });
+    });
+}
+//# sourceMappingURL=terminal-binding-reconciliation-service.js.map

package/dist/src/terminal-binding-reconciliation-service.js.map

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