@scotthuang/agent-knock-knock 0.13.16 → 0.13.18

package/dist/src/terminal-action-contracts.js

@@ -0,0 +1,695 @@
+export const TERMINAL_WATCH_ACTION_USE = "Observe this exact terminal without sending input. AKK uses an exact task " +
+    "anchor when available and otherwise falls back to best-effort terminal " +
+    "activity. Call agent_knock_knock_watch with this exact terminal_id; " +
+    "version, ownership, and artifact uncertainty are warnings rather than " +
+    "Watch vetoes.";
+export function listActionContracts() {
+    return {
+        version: 30,
+        instructions: actionContractInstructions(),
+        field_semantics: actionFieldSemantics(),
+        actions: terminalActionCatalog()
+    };
+}
+function actionContractInstructions() {
+    return [
+        "Treat terminals[] as the primary resource and use only mutation actions " +
+            "present in available_actions, except the snapshot-bound " +
+            "terminals[].handoff_decision.choices.take_over_current.action and an exact " +
+            "terminals[].blocking_turns[].recovery_action. Read-only Watch is the " +
+            "separate user-intent exception: one complete exact terminal_id may be " +
+            "watched even when available_actions.watch is absent. Either nested mutation " +
+            "action requires explicit user confirmation; after it succeeds, refresh list " +
+            "before any follow-current send.",
+        "A merely unverified complete Codex or Claude Code x.y.z version adds " +
+            "compatibility_warnings and action compatibility_warning diagnostics without " +
+            "vetoing an otherwise eligible action solely for lacking an exact " +
+            "regression-tested profile. Known incompatible protocols disable affected " +
+            "actions before input. Codex 0.157.0/0.157.1 paginated durable history and " +
+            "fullscreen command menus disable managed completion callbacks, native thread " +
+            "lifecycle, and automated native status dispatch; explicit terminal Send and " +
+            "warning-bearing terminal_activity Watch remain available subject to native " +
+            "UI safety checks. That Watch observes terminal activity without proving " +
+            "exact task completion. Execute only the advertised mutation actions; actual " +
+            "UI, artifact, identity, and postcondition evidence decides success. Never " +
+            "automatically retry a result that says terminal input may already have " +
+            "occurred.",
+        "A terminal_user_explicit send is the user's physical-terminal authority. It " +
+            "is gated only by one exact live physical terminal/process, a scanned, " +
+            "non-blocked approval state, no active native questionnaire, and no " +
+            "positively identified menu, editor, history search, or read-only viewer that " +
+            "owns input; parsed working activity and Codex rollout ambiguity do not veto " +
+            "it; Composer visibility, stability, exactness, or existing draft contents do " +
+            "not veto it; and AKK Turn, Session, deferred-transfer, transition, ledger, " +
+            "and Store health are not eligibility vetoes. Codex clears the current " +
+            "Composer once with C-u; Claude Code uses a sentinel-backed native C-s " +
+            "stash-clear transaction that is independent of the cursor position and does " +
+            "not interrupt an active turn, then proves the main Composer empty. Each then " +
+            "injects the new request, waits through the paste window, and dispatches " +
+            "Enter exactly once. After text injection, no Composer observation may veto " +
+            "Enter. AKK tries the managed fast path first; a source-less Codex pane " +
+            "freezes all current rollout roots and binds a provisional Session/Turn only " +
+            "after one anchored or newly opened rollout durably accepts the exact request " +
+            "hash. Zero matches stay pending; multiple matches or identity drift become " +
+            "uncertain without replay. If managed preparation fails before input, AKK " +
+            "performs the physical fallback as unmanaged work, best-effort attaches an " +
+            "exact Terminal Watch callback, then releases conflicting AKK management. " +
+            "Once exact request acceptance and terminal attribution are established, that " +
+            "Watch may expose a supported exact questionnaire as an owner-bound response " +
+            "offer through status and watch_id; terminal-activity observations and " +
+            "manual_required interactions remain notification-only. When runtime " +
+            "durability is available, an omitted target binds its message_id to the first " +
+            "selected physical terminal and an existing or possibly existing same-ID " +
+            "record rejects automatic replay. If no record exists and durability is " +
+            "unavailable, user priority wins: AKK proceeds with a warning, and callers " +
+            "must not automatically retry that degraded result. The fallback creates no " +
+            "managed callback Turn; Watch attachment failure is reported without changing " +
+            "a successful Send. Send output separates terminal_input_dispatched, " +
+            "agent_acceptance, management_mode, observation_mode, and " +
+            "callback/interaction capabilities. Once its sole mutation sequence begins, " +
+            "an uncertain result must not be retried automatically; watch-status remains " +
+            "the callback recovery path.",
+        "The session_exact scope uses session_id only when it is prefilled by the " +
+            "listed send action. A rollout-backed managed Codex pane instead uses the " +
+            "terminal_follow_current scope with its exact terminal_id because even one " +
+            "materialized rollout does not prove the current TUI foreground thread. AKK " +
+            "derives and revalidates current terminal authority internally. A turn id is " +
+            "never an ordinary send target.",
+        "A user-explicit raw terminal selector, or a uniquely delegated raw send with " +
+            "no selector, is only a discovery choice. If that terminal already has one " +
+            "rollout-backed managed Codex source, the managed fast path captures fresh " +
+            "candidate authority under the terminal and Store locks and still uses the " +
+            "same v3 follow-current transfer; it never degrades to sole-root strict " +
+            "continuation. If that managed path proves zero input and fails, the separate " +
+            "terminal_user_explicit path may deliver once as unmanaged work.",
+        "Read-only native-thread listing targets an exact terminal_id. Native-thread " +
+            "new/resume mutations use terminal_id and, for resume, one complete " +
+            "native_thread_id; AKK resolves and revalidates current lifecycle authority " +
+            "internally. They never create a Turn.",
+        "Native inspection is a separate terminal action: use only its closed " +
+            "inspection enum and current exact terminal_id. AKK resolves current " +
+            "lifecycle authority internally, and AKK status does not execute a native " +
+            "slash command.",
+        "Native model control is a separate explicit exact-physical-pane action. " +
+            "model_options requires one currently advertised terminal_id, an exact live " +
+            "pane/process, no approval, questionnaire/editor, read-only viewer, or active " +
+            "Turn, and either an idle empty Composer or one stable profiled Codex " +
+            "0.154.0/0.155.1 /model Composer residual. It obtains choices dynamically " +
+            "from the native catalog. Profiled Codex 0.154.0/0.155.1 requires either one " +
+            "exact current native Session or a verified-zero-rollout pane; Claude still " +
+            "requires one exact current native Session. identify_foreground is diagnostic " +
+            "rather than a prerequisite. For an exact Composer residual, model_options " +
+            "uses separate residual-bound authority to continue that same native slash " +
+            "command into read-only discovery. Whether entered from empty or a residual, " +
+            "model_options must dismiss to exact empty, consume any residual-entry " +
+            "authority, and return a fresh ordinary one-shot set_model offer. An " +
+            "already-open exact native picker is never advertised as model_options: List " +
+            "marks it non-idle and advertises repair_model_control only. " +
+            "repair_model_control is cleanup-only: it never presses Enter, never offers " +
+            "or continues into set_model, and requires refresh List then model_options " +
+            "after restoring empty. set_model consumes one exact model/reasoning-effort " +
+            "tuple from that same-controller catalog offer, revalidates every physical " +
+            "and UI boundary under lock, and reports uncertain without automatic retry " +
+            "when its postcondition cannot be proven.",
+        "Foreground identification is an explicit Codex-only diagnostic for an exact " +
+            "empty idle Composer whose native identity is unresolved. identify_foreground " +
+            "sends exactly one closed /status under the terminal lock, mutates no Store " +
+            "state, and returns a 30-second pane/process/cwd/screen-bound observation " +
+            "that grants no later authority. identify_and_send keeps that same terminal " +
+            "lock, revalidates the observation, and sends one task; it never falls back " +
+            "to unmanaged delivery. Final Session identity still comes only from the " +
+            "rollout that uniquely accepts the exact task. Ordinary list, status, and " +
+            "send never invoke this probe.",
+        "Terminal Watch is a read-only user-directed observation of one exact live " +
+            "terminal. AKK prefers an exact durable task anchor and otherwise degrades to " +
+            "best-effort terminal-activity observation; version, artifact, managed " +
+            "ownership, and stale action-advertisement uncertainty produce warnings " +
+            "rather than vetoing Watch. It sends no terminal input and creates no AKK " +
+            "Session or Turn. Pass the exact terminal_id and use watch_id for later " +
+            "status or unwatch operations.",
+        "A verified, idle human native-thread switch may expose a terminal-scoped " +
+            "send; that action atomically adopts the live context before creating its " +
+            "Turn. A conclusively ended Codex rollout may expose the same snapshot-bound " +
+            "operation only after AKK proves zero current rollout and an exact empty " +
+            "composer; it detaches the ended Session and creates an isolated virgin " +
+            "Session. A status-card-only zero-rollout source or any otherwise eligible " +
+            "quiescent rollout-backed source with a complete nonempty pinned open-rollout " +
+            "inventory may also expose this exact action. One materialized rollout does " +
+            "not prove the current Codex TUI foreground thread, and a /clear resume hint " +
+            "is diagnostic only. AKK freezes any released predecessor Turn history, " +
+            "submits the ordinary task once, and binds a separate provisional Session " +
+            "only after one post-anchor rollout uniquely accepts that exact request. The " +
+            "accepted UUID may equal or differ from the predecessor without merging their " +
+            "Session lineages, and narrow panes do not require /status. Until that " +
+            "promotion commits, strict session_id send, respond, approve, cancel, native " +
+            "lifecycle, and native_inspect remain unavailable, and the provisional " +
+            "binding has no callback authority. If dispatch, acceptance, or post-submit " +
+            "binding is uncertain, do not retry automatically. Explicit Close always " +
+            "honors the user's decision to release AKK management of the selected Turn; " +
+            "it sends no terminal input, never stops the coding agent or pane, and " +
+            "reports best-effort cleanup warnings without vetoing the Close. Refresh list " +
+            "afterward and use Watch when the coding agent is still working. Other " +
+            "input-producing binding actions remain fail-closed.",
+        "List resumable threads before resume; use only a complete native_thread_id and the action returned for that candidate.",
+        "Structured follow-current actions use only the exact terminal_id prefilled " +
+            "by that terminal row. Human slash commands may use an explicitly named " +
+            "discovery selector. AKK resolves and revalidates current action authority " +
+            "internally; never infer or guess a target.",
+        "Use respond only for an in-flight turn that is explicitly waiting for OpenClaw.",
+        "A native interaction response is a separate status-bound mutation. In the " +
+            "same controller conversation, call agent_knock_knock_status for the exact " +
+            "managed Turn or response-capable exact Watch, review its current pending " +
+            "interaction_state, and then call agent_knock_knock_respond_interaction with " +
+            "exactly one matching subject id (turn_id or watch_id), plus only that " +
+            "projection's interaction_id, question_id, and option_id values or bounded " +
+            "typed text. A Codex async_question defaults to advertised steer_current_turn " +
+            "and optionally accepts advertised queue_next_turn as delivery_mode; a " +
+            "blocking questionnaire forbids it. One call resolves only the current step; " +
+            "refresh status before every later question or final confirmation. " +
+            "Terminal-activity Watch observations and manual_required interactions are " +
+            "notification-only. Never invent semantic ids, expose private prompt " +
+            "authority, raw keys, or menu indexes, or retry a response whose terminal " +
+            "input may have occurred.",
+        "Retry submission is never automatic. Only when the current exact Turn " +
+            "exposes available_actions.retry_submission, ask for explicit user " +
+            "confirmation and call its prefilled agent_knock_knock_send {turn_id} form " +
+            "unchanged. It never accepts replacement text or caller-selected terminal, " +
+            "Session, timeout, or callback route data, and execution revalidates the " +
+            "durable submission and live terminal under lock before any input.",
+        "Manual approval binds the exact prompt the user reviewed. After explicit " +
+            "confirmation, call only the currently advertised approve action; AKK keeps " +
+            "the prompt authority private and recaptures the exact terminal, process, " +
+            "request, and prompt before sending a decision key. A prompt without complete " +
+            "exact evidence is not approvable.",
+        "Managed controls target turn_id. A raw terminal may be controlled only " +
+            "through its own list-prefilled conversation_id action. When a Codex managed " +
+            "prompt has no usable AKK Turn owner, list may expose one manual " +
+            "terminal-scoped approve action after exact observation. It does not mutate " +
+            "the Turn or Session binding, has no durable dispatch receipt, and is never " +
+            "eligible for automatic approval. If its result is interrupted, refresh " +
+            "status and inspect the live prompt instead of retrying blindly.",
+        "Start with the action's prefilled arguments, supply every missing_required " +
+            "field, and consult the top-level action's optional fields only when needed.",
+        "Authoritative full IDs are prefilled; short_ref is for display and human input.",
+        "Availability is a snapshot. terminal_user_explicit revalidates the exact " +
+            "live process and provider-owned terminal identity plus the scanned, " +
+            "non-blocked approval state; AKK recovery state and Codex Composer " +
+            "observation never veto it. Other actions revalidate their action-specific " +
+            "workspace, activity, management, and recovery authority before side effects."
+    ];
+}
+function actionFieldSemantics() {
+    return {
+        process_state: {
+            terminals: "physical_terminal_process_liveness",
+            authoritative_for_tool_calls: false
+        },
+        status: {
+            managed_turns: "managed_turn_lifecycle",
+            authoritative_for_tool_calls: false
+        },
+        activity_state: {
+            terminals: "legacy_conservative_effective_activity_projection",
+            authoritative_for_tool_calls: false
+        },
+        screen_state: {
+            terminals: "live_terminal_screen_activity_classification",
+            authoritative_for_tool_calls: false
+        },
+        screen_reason: {
+            terminals: "bounded_evidence_for_screen_state",
+            authoritative_for_tool_calls: false
+        },
+        native_identity_state: {
+            terminals: "foreground_native_identity_resolution_without_mutation_authority",
+            authoritative_for_tool_calls: false
+        },
+        durable_activity_state: {
+            terminals: "exact_native_artifact_task_activity_when_available",
+            authoritative_for_tool_calls: false
+        },
+        durable_activity_reason: {
+            terminals: "bounded_evidence_or_limitation_for_durable_activity_state",
+            authoritative_for_tool_calls: false
+        },
+        managed: {
+            current_turn: "the authoritative dispatch-ledger owner, never inferred from history",
+            recent_turn: "the latest visible non-owning turn in the current managed session",
+            session_id: "the continuing agent context; it is an ordinary-send target only when the " +
+                "listed send action explicitly prefills it, and rollout-backed Codex uses the " +
+                "listed follow-current terminal action instead",
+            binding_id: "the immutable terminal-binding generation currently authorized for this Session",
+            history: "older turns, present only with --all"
+        },
+        available_actions: {
+            meaning: "currently_safe_mutation_actions_and_watch_discovery",
+            authoritative_for_tool_calls: true,
+            read_only_watch_exception: "an explicit exact terminal_id remains callable when available_actions.watch is absent"
+        },
+        native_agent_identity_observation: {
+            meaning: "the latest bounded native identity probe; verified_absent is distinct from an unavailable resolver",
+            authoritative_for_tool_calls: false
+        },
+        management_conflict: {
+            verified_empty_native_session: "a previously bound Codex rollout is conclusively closed; only the exact " +
+                "snapshot-bound send in available_actions may detach it and create an " +
+                "isolated virgin Session"
+        },
+        handoff_state: {
+            meaning: "why a managed conflict-scoped follow-current send is available or blocked; " +
+                "it does not veto terminal_user_explicit physical Send",
+            verified_empty_native_session_adoptable: "the exact current terminal snapshot permits the listed conflict send; availability is revalidated before terminal input"
+        },
+        handoff_decision: {
+            meaning: "an explicit human choice required before superseding an active source Turn",
+            authoritative_action_path: "terminals[].handoff_decision.choices.take_over_current.action",
+            requires_explicit_user_confirmation: true,
+            after_success: "refresh list before using a follow-current send action"
+        },
+        blocking_turns: {
+            meaning: "terminal-incarnation-wide unresolved managed Turns that suppress managed " +
+                "send, lifecycle, and native-inspection actions but never " +
+                "terminal_user_explicit physical Send; each exact Turn remains explicitly " +
+                "closable even during a deferred transfer or human handoff",
+            authoritative_action_path: "terminals[].blocking_turns[].recovery_action",
+            requires_explicit_user_confirmation: true,
+            after_success: "refresh list before using any terminal action"
+        }
+    };
+}
+function terminalActionCatalog() {
+    return {
+        send: {
+            tool: "agent_knock_knock_send",
+            target_argument: "session_id",
+            initial_attach_target_argument: "terminal_id",
+            managed_scopes: {
+                session_exact: {
+                    target_arguments: ["session_id"],
+                    follows_current_terminal: false
+                },
+                terminal_follow_current: {
+                    target_arguments: ["terminal_id"],
+                    follows_current_terminal: true
+                }
+            },
+            initial_attach_scope: "A terminal_user_explicit structured call uses the terminal_id prefilled by " +
+                "an exact live terminal row's available send action, or omits the target only " +
+                "when exactly one send-ready pane exists. Human slash commands may preserve a " +
+                "discovery selector explicitly named by the user. This user-priority scope " +
+                "depends only on the exact live physical terminal/process, a scanned, " +
+                "non-blocked approval state, and no proven input-owning questionnaire, " +
+                "editor, menu, or read-only viewer. Composer visibility, exactness, and " +
+                "existing draft contents are advisory. Codex clears the current Composer once " +
+                "with C-u; Claude Code uses a sentinel-backed native C-s stash-clear " +
+                "transaction that is independent of the cursor position and does not " +
+                "interrupt an active turn, then proves the main Composer empty. Each injects " +
+                "the request, waits through the paste window, and dispatches Enter exactly " +
+                "once without a post-text Composer veto. The managed fast path may require " +
+                "exact empty before input. If that managed path cannot deliver before input, " +
+                "the physical operation runs once as unmanaged work with no managed callback " +
+                "Turn; AKK then best-effort attaches an exact Terminal Watch callback and " +
+                "releases stale management. Watch attachment failure never changes a " +
+                "successful Send.",
+            terminal_user_explicit_composer_policy: "replace_current_composer_and_submit",
+            // v28 compatibility alias. New consumers use the agent-neutral field.
+            codex_terminal_user_explicit_composer_policy: "replace_current_composer_and_submit",
+            required: ["request"],
+            optional: [
+                "session_id",
+                "terminal_id",
+                "type",
+                "idleTimeoutMinutes",
+                "agentTimeoutMinutes",
+                "agentHardTimeoutMinutes"
+            ],
+            unsupported: ["timeoutSeconds"],
+            status_card_only_deferred_scope: "A zero-Turn Codex status-card binding has no rollout; only its listed " +
+                "follow-current send creates an isolated provisional Session and binds it " +
+                "after exact request acceptance. Until promotion commits, strict managed " +
+                "controls, native lifecycle, native_inspect, and callback authority remain " +
+                "unavailable; an uncertain dispatch, acceptance, or post-submit binding must " +
+                "not be retried automatically.",
+            candidate_rollout_deferred_scope: "A quiescent rollout-backed Codex source uses a listed follow-current send " +
+                "whenever AKK can pin a complete nonempty candidate inventory. Inventory " +
+                "status resolved means only that one rollout is materialized; it does not " +
+                "prove the current TUI foreground thread. Released predecessor Turn history " +
+                "stays read-only while a separate provisional Session sends once and waits " +
+                "for one unique post-anchor request acceptance. A /clear resume hint is " +
+                "diagnostic only and is not routing authority. Same-UUID and different-UUID " +
+                "results keep separate Session lineages; zero, multiple, drifted, or " +
+                "uncertain acceptance is never retried blindly. Explicit Close is the " +
+                "user-owned escape hatch: it closes the AKK Turn first, then best-effort " +
+                "releases only linked AKK metadata without terminal input or coding-agent " +
+                "interruption.",
+            ordinary_use: "Create a new managed Turn through the exact action listed for the pane when " +
+                "the managed fast path succeeds. An explicit session_id never follows the " +
+                "pane and is unavailable for rollout-backed Codex Sessions; their listed " +
+                "follow-current action binds only the unique exact rollout that accepts the " +
+                "submitted request. The managed path can attach an unmanaged pane, adopt one " +
+                "verified human-selected native context, detach a verified-empty Codex " +
+                "source, or replace an eligible status-card/candidate-rollout source. A " +
+                "terminal_user_explicit action gives the user's selected exact live physical " +
+                "terminal/process priority over broken AKK internal state: Codex clears the " +
+                "current Composer once with C-u; Claude Code uses a sentinel-backed native " +
+                "C-s stash-clear transaction that is independent of the cursor position and " +
+                "does not interrupt an active turn, then proves the main Composer empty. Each " +
+                "injects the request, waits through the paste window, and dispatches Enter " +
+                "exactly once without any post-text Composer veto. The unmanaged path has no " +
+                "managed callback Turn; it best-effort attaches an exact Terminal Watch " +
+                "callback and releases conflicting management afterward. Watch attachment " +
+                "failure is a warning and never revokes delivery."
+        },
+        retry_submission: {
+            tool: "agent_knock_knock_send",
+            target_argument: "turn_id",
+            required: ["turn_id"],
+            accepts_only: ["turn_id"],
+            creates_turn: false,
+            caller_supplies_request_text: false,
+            may_retransmit_original_request_text: true,
+            retransmit_condition: "durable structured proof that Enter was never attempted plus a positively empty live composer",
+            requires_explicit_user_confirmation: true,
+            candidate_source: "the current exact managed Turn's available_actions.retry_submission",
+            scope: "Recover only the original durable submission whose text injection is proven " +
+                "but Enter dispatch remains uncertain. AKK either submits the proven exact " +
+                "existing draft once, or retransmits the immutable original request once only " +
+                "after structured no-Enter proof and a positively empty live composer. It " +
+                "revalidates all terminal, identity, route, composer, and one-shot authority " +
+                "under lock and otherwise fails closed."
+        },
+        watch: {
+            tool: "agent_knock_knock_watch",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            optional: ["hardTimeoutMinutes"],
+            creates_turn: false,
+            creates_session: false,
+            sends_terminal_input: false,
+            candidate_source: "terminals[].available_actions.watch",
+            scope: "Observe the user's exact selected live terminal without input. AKK prefers " +
+                "an exact durable task anchor; if version, artifact, task, managed-ownership, " +
+                "or action-advertisement evidence cannot support that anchor, Watch remains " +
+                "available through a warning-bearing terminal_activity fallback. That " +
+                "fallback reports best_effort confidence and stable-idle activity, not proof " +
+                "that one exact task completed. Only an absent or unobservable exact " +
+                "terminal, or failure to persist the Watch, is a hard error. Watch never " +
+                "adopts the task as AKK work or blocks later terminal use."
+        },
+        unwatch: {
+            tool: "agent_knock_knock_unwatch",
+            target_argument: "watch_id",
+            required: ["watch_id"],
+            creates_turn: false,
+            creates_session: false,
+            sends_terminal_input: false,
+            requires_user_intent: true
+        },
+        new_thread: {
+            tool: "agent_knock_knock_new_thread",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            creates_turn: false,
+            creates_session: true,
+            requires_user_intent: true
+        },
+        list_resumable_threads: {
+            tool: "agent_knock_knock_list_resumable_threads",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            side_effect_free: true
+        },
+        native_inspect: {
+            tool: "agent_knock_knock_native_inspect",
+            target_argument: "terminal_id",
+            required: ["terminal_id", "inspection"],
+            supported_inspections: ["status"],
+            creates_turn: false,
+            creates_session: false,
+            mutates_store: false,
+            sends_terminal_input: true,
+            candidate_source: "terminals[].available_actions.native_inspect"
+        },
+        model_options: {
+            tool: "agent_knock_knock_model_options",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            creates_turn: false,
+            creates_session: false,
+            mutates_store: false,
+            sends_terminal_input: true,
+            input_scope: "Fixed /model discovery, or one residual-bound continuation of that exact command, followed by exact Escape dismissal",
+            authority_scopes: [
+                "native_session",
+                "terminal_user_explicit_model_control",
+                "terminal_user_explicit_model_control_residual_entry"
+            ],
+            native_identity_requirement: {
+                codex: "exact_current_session_or_verified_zero_rollout_profile",
+                claude: "exact_current_session"
+            },
+            zero_rollout_codex_supported: true,
+            safety_boundary: "Exact live pane/process, no approval, questionnaire/editor, read-only " +
+                "viewer, or active Turn, plus either an idle empty Composer or one exact " +
+                "stable profiled Codex 0.154.0/0.155.1 /model Composer residual.",
+            candidate_source: "terminals[].available_actions.model_options"
+        },
+        permission_options: {
+            tool: "agent_knock_knock_permission_options",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            creates_turn: false,
+            creates_session: false,
+            mutates_store: false,
+            sends_terminal_input: true,
+            input_scope: "Closed Codex /status and /permissions discovery, followed by exact dismissal to an empty Composer.",
+            authority_scope: "terminal_user_explicit_permission_control",
+            safety_boundary: "Exact live pane/process, verified idle empty Composer, no active Turn, " +
+                "transition, approval, questionnaire/editor, or viewer.",
+            candidate_source: "terminals[].available_actions.permission_options"
+        },
+        set_permissions: {
+            tool: "agent_knock_knock_set_permissions",
+            target_argument: "terminal_id",
+            required: ["terminal_id", "mode"],
+            semantic_choice_source: "The preceding permission_options result in this same controller conversation.",
+            scope: "current_session",
+            accepts_raw_command_or_keys: false,
+            postcondition_required: true,
+            uncertain_retry_allowed: false,
+            candidate_source: "permission_options.available_actions.set_permissions"
+        },
+        repair_model_control: {
+            tool: "agent_knock_knock_repair_model_control",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            creates_turn: false,
+            creates_session: false,
+            mutates_store: false,
+            sends_terminal_input: true,
+            input_scope: "Reversible dismissal and clearing of one exact profiled Codex " +
+                "0.154.0/0.155.1 /model Composer residue or open native picker; never Enter, " +
+                "task submission, approval, or model selection.",
+            authority_scope: "terminal_user_explicit_model_control_repair",
+            accepts_raw_command_or_keys: false,
+            empty_composer_postcondition_required: true,
+            uncertain_retry_allowed: false,
+            after_success: "Refresh list, then run model_options before a deliberate set_model attempt.",
+            candidate_source: "terminals[].available_actions.repair_model_control"
+        },
+        set_model: {
+            tool: "agent_knock_knock_set_model",
+            target_argument: "terminal_id",
+            required: ["terminal_id", "model", "reasoning_effort"],
+            semantic_tuple_source: "The immediately preceding model_options result in the same controller conversation.",
+            authority_scopes: [
+                "native_session",
+                "terminal_user_explicit_model_control"
+            ],
+            native_identity_requirement: {
+                codex: "exact_current_session_or_verified_zero_rollout_profile",
+                claude: "exact_current_session"
+            },
+            identify_foreground_required: false,
+            accepts_raw_command_or_keys: false,
+            postcondition_required: true,
+            uncertain_retry_allowed: false,
+            candidate_source: "model_options.available_actions.set_model"
+        },
+        identify_foreground: {
+            tool: "agent_knock_knock_identify_foreground",
+            target_argument: "terminal_id",
+            required: ["terminal_id"],
+            creates_turn: false,
+            creates_session: false,
+            mutates_store: false,
+            sends_terminal_input: true,
+            terminal_submission: "exactly_one_closed_status_probe",
+            proof_ttl_ms: 30000,
+            proof_grants_authority: false,
+            requires_user_intent: true,
+            candidate_source: "terminals[].available_actions.identify_foreground"
+        },
+        identify_and_send: {
+            tool: "agent_knock_knock_identify_and_send",
+            target_argument: "terminal_id",
+            required: ["terminal_id", "request"],
+            creates_turn: true,
+            creates_session: true,
+            sends_terminal_input: true,
+            terminal_lock_scope: "status_probe_through_task_dispatch",
+            unmanaged_fallback: false,
+            final_identity_source: "unique_exact_request_acceptance",
+            requires_user_intent: true,
+            candidate_source: "terminals[].available_actions.identify_and_send"
+        },
+        resume_thread: {
+            tool: "agent_knock_knock_resume_thread",
+            target_argument: "terminal_id",
+            required: [
+                "terminal_id",
+                "native_thread_id"
+            ],
+            creates_turn: false,
+            requires_user_intent: true,
+            candidate_source: "list_resumable_threads"
+        },
+        reconcile_binding: {
+            tool: "agent_knock_knock_reconcile_binding",
+            target_argument: "terminal_id",
+            required: [
+                "terminal_id",
+                "conflicting_session_id"
+            ],
+            creates_turn: false,
+            sends_terminal_input: false,
+            requires_user_intent: true,
+            effect: "Detach one exactly listed conflicting Session binding without adopting the live replacement thread."
+        },
+        respond: {
+            tool: "agent_knock_knock_respond",
+            target_argument: "turn_id",
+            required: ["turn_id", "request"],
+            ordinary_use: "Answer an agent question inside the explicitly selected in-flight turn without creating another turn."
+        },
+        respond_interaction: {
+            tool: "agent_knock_knock_respond_interaction",
+            target_arguments: {
+                exactly_one_of: ["turn_id", "watch_id"]
+            },
+            managed_target_argument: "turn_id",
+            watch_target_argument: "watch_id",
+            interaction_argument: "interaction_id",
+            required: ["interaction_id", "answers"],
+            optional: ["delivery_mode"],
+            candidate_source: "terminal_status.interaction_state for a managed Turn or " +
+                "watch.interaction_state for a response-capable exact Watch, returned by " +
+                "agent_knock_knock_status in the same controller conversation",
+            watch_scope: "Only an exact current Watch interaction whose Status projection advertises " +
+                "capabilities.respond=true may use watch_id. Terminal-activity and " +
+                "manual_required Watch interactions remain notification-only.",
+            answer_contract: "Use only the current projection's opaque question_id and option_id values, " +
+                "or its bounded typed free_text answer. An async_question defaults to " +
+                "advertised steer_current_turn or accepts explicit advertised queue_next_turn " +
+                "as delivery_mode; questionnaire forbids delivery_mode. Raw terminal keys, " +
+                "menu indexes, rendered labels, prompt fingerprints, versions, and terminal " +
+                "commands are not accepted.",
+            one_step_per_call: true,
+            requires_fresh_status: true,
+            requires_same_controller_conversation: true,
+            manual_required_sends_input: false,
+            uncertain_retry_allowed: false
+        },
+        status: {
+            tool: "agent_knock_knock_status",
+            target_arguments: {
+                exactly_one_of: ["turn_id", "conversation_id", "watch_id"]
+            },
+            managed_target_argument: "turn_id",
+            watch_target_argument: "watch_id",
+            watch_scope: "Use only the authoritative watch_id prefilled by a current Terminal Watch row.",
+            compatibility_target_argument: "conversation_id",
+            compatibility_scope: "A deprecated legacy Turn alias, or only the exact selector prefilled by an " +
+                "unmanaged raw-terminal row's available status action; never construct, " +
+                "guess, or reuse it.",
+            required: [],
+            optional: ["idleTimeoutMinutes", "trace"]
+        },
+        approve: {
+            tool: "agent_knock_knock_approve",
+            target_arguments: {
+                exactly_one_of: ["turn_id", "terminal_id"]
+            },
+            managed_target_argument: "turn_id",
+            terminal_target_argument: "terminal_id",
+            required: [],
+            optional: ["decision"],
+            decisions: ["approve_once", "reject"],
+            decision_scope: "Use only a semantic decision advertised by the current approval action. " +
+                "Never pass raw keys, menu indexes, or labels. Omission remains approve_once " +
+                "for compatibility.",
+            terminal_scoped_scope: "Only the latest list-prefilled Codex terminal_id action may approve a " +
+                "managed current prompt without a usable Turn owner. It remains " +
+                "human-confirmed, uses private server-bound reviewed-prompt authority, " +
+                "revalidates exact terminal/process/Session/dispatch/prompt state before " +
+                "keys, never mutates managed state, has no durable dispatch receipt, cannot " +
+                "be auto-approved, and must not be blindly retried after an interrupted " +
+                "result.",
+            approval_authority: "private_server_bound_reviewed_prompt",
+            missing_prompt_region_evidence: "not_approvable",
+            requires_explicit_user_confirmation: true,
+            requires_fresh_status: true
+        },
+        cancel: {
+            tool: "agent_knock_knock_cancel",
+            target_argument: "turn_id",
+            compatibility_target_argument: "conversation_id",
+            compatibility_scope: "A deprecated legacy Turn alias, or only the exact selector prefilled by an " +
+                "unmanaged raw-terminal row's available cancellation action; never construct, " +
+                "guess, or reuse it.",
+            required: ["turn_id"],
+            optional: ["idleTimeoutMinutes"],
+            requires_user_intent: true
+        },
+        renew: {
+            tool: "agent_knock_knock_renew",
+            target_argument: "turn_id",
+            compatibility_target_argument: "conversation_id",
+            compatibility_scope: "Deprecated legacy Turn alias only; unmanaged raw-terminal rows never advertise renew.",
+            required: ["turn_id"],
+            optional: ["minutes"]
+        },
+        retry_callback: {
+            tool: "agent_knock_knock_retry_callback",
+            target_argument: "turn_id",
+            compatibility_target_argument: "conversation_id",
+            compatibility_scope: "Deprecated legacy Turn alias only; unmanaged raw-terminal rows never advertise callback retry.",
+            required: ["turn_id"]
+        },
+        close: {
+            tool: "agent_knock_knock_close",
+            target_argument: "turn_id",
+            compatibility_target_argument: "conversation_id",
+            compatibility_scope: "A deprecated legacy Turn alias, or only the exact selector prefilled by an " +
+                "unmanaged raw-terminal row's orphan-close action; never construct, guess, or " +
+                "reuse it.",
+            required: ["turn_id"],
+            optional: [
+                "reason",
+                "expected_message_id",
+                "expected_transition_id"
+            ],
+            requires_explicit_user_confirmation: true,
+            user_priority: true,
+            sends_terminal_input: false,
+            stops_coding_agent: false,
+            cleanup_policy: "Close the selected AKK Turn first. Linked transfer, Session, ledger, and " +
+                "callback cleanup is best-effort; missing, stale, malformed, or newer " +
+                "metadata is preserved and reported as a warning rather than blocking Close.",
+            handoff_scope: "After explicit confirmation, a handoff Close follows the same user-priority " +
+                "management-release path and does not depend on a private live-terminal " +
+                "fence."
+        }
+    };
+}
+//# sourceMappingURL=terminal-action-contracts.js.map