scitex_agent_container API Reference

Top-level package surface re-exported from scitex_agent_container. Use scitex-agent-container list-python-apis for the authoritative runtime enumeration.

SciTeX Agent Container – Declarative agent management.

Provides a YAML-based framework for defining, managing, and orchestrating AI coding agent instances across container runtimes.

Public surface — CLI-tree-shaped noun submodules:

import scitex_agent_container as sac

sac.agent.list()                  # `sac agent list`
sac.agent.start("head-nas")       # `sac agent start head-nas`
sac.db.query(table="instances")   # `sac db query --table=instances`
sac.host.list()                   # `sac host list`
sac.skills.get("02_quick-start")  # `sac skills get 02_quick-start`

Each noun submodule (agent, db, host, image, template, account, skills, mcp) re-exports its verbs under bare names that mirror the CLI subcommand tree. The same function objects power both the Python API and the MCP server (per scitex MCP §6 parity).

Lifecycle helpers that take a shared Registry instance live at scitex_agent_container._lifecycle.lifecycle for callers that need them. The submodule verbs go through the CLI for JSON-friendly input/output.

Config

YAML config loading and validation for agent definitions.

Public API:

AgentConfig, load_config, validate_config, resolve_config ContainerSpec, ClaudeSpec, HealthSpec, WatchdogSpec, RestartSpec, SkillsSpec, StartupCommand

RemoteSpec and the spec.remote field were deleted in WI-6 (handoff §6, 2026-05-20). Cross-host placement is via spec.host; the old SSH-dispatch path is retired.

class scitex_agent_container.config.AgentConfig(name, runtime='tui', provider='anthropic', image='', model='sonnet', workdir='', python_venv='', env=<factory>, env_files=<factory>, screen_name='', labels=<factory>, container=<factory>, claude=<factory>, health=<factory>, watchdog=<factory>, restart=<factory>, autonomous=<factory>, apptainer=<factory>, hooks=<factory>, listen=<factory>, extensions=<factory>, skills=<factory>, context_management=<factory>, startup_commands=<factory>, startup_prompts=<factory>, exclude_hooks=<factory>, exclude_skills=<factory>, mcp_servers=<factory>, multiplexer='tmux', hosts_spec=<factory>, scheduling=<factory>, config_path='', mounts=<factory>, user='', a2a=<factory>, comms=<factory>, lineage=<factory>, kind='Agent', proxy=None, to_home='./to_home')

Bases: object

Parsed agent configuration from a YAML definition file.

name: str

runtime: str = 'tui'

provider: Literal['anthropic', 'openai'] = 'anthropic'

image: str = ''

model: str = 'sonnet'

workdir: str = ''

python_venv: str = ''

env: dict[str, str]

env_files: list[str]

screen_name: str = ''

labels: dict[str, str]

container: ContainerSpec

claude: ClaudeSpec

health: HealthSpec

watchdog: WatchdogSpec

restart: RestartSpec

autonomous: AutonomousSpec

apptainer: ApptainerSpec

hooks: dict[str, list[str]]

listen: list[ListenPort]

extensions: Dict[str, Any]

skills: SkillsSpec

context_management: ContextManagementConfig

startup_commands: list[StartupCommand]

startup_prompts: list[str]

exclude_hooks: list[str]

exclude_skills: list[str]

mcp_servers: dict[str, dict]

multiplexer: str = 'tmux'

hosts_spec: HostsSpec

scheduling: SchedulingSpec

config_path: str = ''

mounts: list[dict]

user: str = ''

a2a: A2ASpec

comms: CommsSpec

lineage: LineageSpec

kind: str = 'Agent'

proxy: Any = None

to_home: str = './to_home'

property expanded_workdir: str

__init__(name, runtime='tui', provider='anthropic', image='', model='sonnet', workdir='', python_venv='', env=<factory>, env_files=<factory>, screen_name='', labels=<factory>, container=<factory>, claude=<factory>, health=<factory>, watchdog=<factory>, restart=<factory>, autonomous=<factory>, apptainer=<factory>, hooks=<factory>, listen=<factory>, extensions=<factory>, skills=<factory>, context_management=<factory>, startup_commands=<factory>, startup_prompts=<factory>, exclude_hooks=<factory>, exclude_skills=<factory>, mcp_servers=<factory>, multiplexer='tmux', hosts_spec=<factory>, scheduling=<factory>, config_path='', mounts=<factory>, user='', a2a=<factory>, comms=<factory>, lineage=<factory>, kind='Agent', proxy=None, to_home='./to_home')

class scitex_agent_container.config.ClaudeSpec(model='', channels=<factory>, flags=<factory>, raw_options=<factory>, session='fresh', continue_max_age_minutes=None, resume_id='', auto_accept=True, account='', credentials_file='', credentials_files=<factory>, provider=None)

Bases: object

model: str = ''

channels: list[str]

flags: list[str]

raw_options: dict

session: str = 'fresh'

continue_max_age_minutes: int | None = None

resume_id: str = ''

auto_accept: bool = True

account: str = ''

credentials_file: str = ''

credentials_files: list[str]

provider: ProviderSpec | None = None

__init__(model='', channels=<factory>, flags=<factory>, raw_options=<factory>, session='fresh', continue_max_age_minutes=None, resume_id='', auto_accept=True, account='', credentials_file='', credentials_files=<factory>, provider=None)

class scitex_agent_container.config.ContainerSpec(runtime='none', image='scitex-agent-container:latest', volumes=<factory>, network='host', mount_host_claude=False)

Bases: object

runtime: str = 'none'

image: str = 'scitex-agent-container:latest'

volumes: list[str]

network: str = 'host'

mount_host_claude: bool = False

__init__(runtime='none', image='scitex-agent-container:latest', volumes=<factory>, network='host', mount_host_claude=False)

class scitex_agent_container.config.ContextManagementConfig(trigger_at_percent=70.0, strategy='noop', warn_before_n_checks=0, check_interval_seconds=300, state_file='~/.scitex/agent-container/state/<agent>.json')

Bases: object

Context-lifecycle policy for an agent.

Defaults mirror strategy="noop" so absence of the context_management block preserves existing behavior (sensor disabled).

trigger_at_percent: float = 70.0

strategy: str = 'noop'

warn_before_n_checks: int = 0

check_interval_seconds: int = 300

state_file: str = '~/.scitex/agent-container/state/<agent>.json'

property enabled: bool

__init__(trigger_at_percent=70.0, strategy='noop', warn_before_n_checks=0, check_interval_seconds=300, state_file='~/.scitex/agent-container/state/<agent>.json')

class scitex_agent_container.config.HealthSpec(enabled=False, interval=30, timeout=5, method='multiplexer-alive')

Bases: object

enabled: bool = False

interval: int = 30

timeout: int = 5

method: str = 'multiplexer-alive'

__init__(enabled=False, interval=30, timeout=5, method='multiplexer-alive')

class scitex_agent_container.config.HookSpec(pre_start=<factory>, post_start=<factory>, pre_stop=<factory>, post_stop=<factory>, on_compact=<factory>, on_restart=<factory>, on_diff=<factory>)

Bases: object

All hook points supported by the container.

Each entry is a list of opaque commands — shell strings or http(s) URLs. The container executes them fire-and-forget; errors are logged but never raised to the caller. Absent keys default to empty lists (feature disabled).

pre_start: list[str]

post_start: list[str]

pre_stop: list[str]

post_stop: list[str]

on_compact: list[str]

on_restart: list[str]

on_diff: list[str]

counts()

Return type:

dict[str, int]

__init__(pre_start=<factory>, post_start=<factory>, pre_stop=<factory>, post_stop=<factory>, on_compact=<factory>, on_restart=<factory>, on_diff=<factory>)

class scitex_agent_container.config.HostsSpec(host='', hosts=<factory>)

Bases: object

Where an agent should run, in either singleton or multi-instance form.

Mutually exclusive — exactly one of host or hosts may be set:

• host (singular) — exactly one instance runs:

  • empty / absent: local singleton (runs wherever sac is invoked)

  • string: pinned to that host

  • list: priority order; first available host wins (fallback chain)

• hosts (plural) — multiple instances run, one per host:

  • “all”: one per fleet host (replaces the old per-host mode)

  • list of host names: one per listed host (subset)

Validator (in _validation.py) enforces mutual exclusion + types. Loader composes effective ids: hosts triggers the <name>-<HOST> suffix; host keeps the bare name.

host: str | list[str] = ''

hosts: str | list[str]

__init__(host='', hosts=<factory>)

class scitex_agent_container.config.ListenPort(port=0, proto='tcp', path='', name='', owner='')

Bases: object

Declaration of a port/socket an external tool binds on behalf of an agent.

The container NEVER binds these — it just validates the shape and echoes them in status --json so orchestrators can see what sidecars are expected to exist. owner is free-form (e.g. "orochi") to identify the plugin that actually listens.

port: int = 0

proto: str = 'tcp'

path: str = ''

name: str = ''

owner: str = ''

__init__(port=0, proto='tcp', path='', name='', owner='')

class scitex_agent_container.config.ProviderSpec(base_url='', auth_token_env='', allowed_tools=<factory>)

Bases: object

Vendor-agnostic backend override for the Claude SDK session.

When set under spec.claude.provider, the agent’s SDK session talks to an Anthropic-SDK-compatible backend OTHER than Anthropic (DeepSeek, a self-hosted gateway, etc.) using a never-expiring, login-free API key instead of Anthropic OAuth. Lets bulk fleet work run on a cheap backend without burning Max-plan quota.

The runtime injects three env vars into the container at start (see runtimes/_apptainer_provider.py):

• ANTHROPIC_BASE_URL ← base_url

• SAC_ANTHROPIC_API_KEY ← the host value of $<auth_token_env> (bridged to ANTHROPIC_API_KEY for the SDK by sac’s existing auth handoff). Fails loud at start if the env var is unset.

• CLAUDE_CONFIG_DIR ← a clean per-agent dir — the conflict-breaker so the OAuth .credentials.json bind cannot win (apptainer --env is last-wins).

The model id is the provider’s own (e.g. deepseek-chat); the claude-* regex in config._validation is relaxed whenever a provider is declared.

Mutually exclusive with ClaudeSpec.account (OAuth pin) — an API-key backend needs no OAuth, so declaring both is a config error the runtime rejects loudly.

base_url: str = ''

Anthropic-compatible base URL, e.g. https://api.deepseek.com/anthropic. Required when the provider block is present.

__init__(base_url='', auth_token_env='', allowed_tools=<factory>)

auth_token_env: str = ''

NAME of the host env var holding the API key (e.g. DEEPSEEK_API_KEY) — NOT the key value. The operator sources the secret file; sac reads the env var’s value at start and never logs it. Required when the provider block is present.

allowed_tools: list[str]

Whitelist of built-in Claude Code tools to REGISTER when this provider is active. Maps directly to ClaudeAgentOptions.tools (the SDK --tools <csv> knob, see claude_agent_sdk/_internal/transport/subprocess_cli.py:241-250), which controls the REGISTERED tool set rather than the use-allow list (--allowedTools / --disallowedTools only affect permission, not whether the tool’s JSON-schema ships in the outbound API request body — confirmed empirically by clew bm172 cohort v7 bind-test 2026-06-06).

Why this matters: an Anthropic-API shim (LiteLLM / vLLM / gateway) may not recognize newer Claude Code built-ins (ExitPlanMode, BashOutput, KillShell were added after LiteLLM 1.52.16). When the shim sees such a tool in the outbound tools[] it falls through its pydantic Union to the last subclass (AnthropicComputerTool), which requires display_width_px that the unknown tool’s payload doesn’t have → 422 on every API call → capsule errors all 60 turns. Whitelisting only the shim-recognized tools suppresses the unrecognized builtins at REGISTRATION, so they never enter the outbound body.

Empty list (the default) means “use the runner’s old-stable default whitelist when the provider is active, otherwise leave tools unset and let the CLI’s full default register” — the runner picks the safe shape automatically.

The string-form provider (e.g. provider: mimo) doesn’t carry this field today; the per-registry allowed_tools plumbing is a follow-up. Operators on the string form fall back to the runner’s old-stable default until the registry plumbing lands.

class scitex_agent_container.config.ProxySpec(upstream='', trust='untrusted', redact=<factory>, timeout_s=30.0)

Bases: object

Configuration for kind: AgentProxy agents.

upstream: str = ''

REQUIRED. Full URL to the upstream A2A AgentCard endpoint. Either an explicit .well-known path or a base URL (we’ll fetch <base>/.well-known/agent-card.json if a base is given).

trust: str = 'untrusted'

One of untrusted (default — operator must opt in to anything more permissive), local-mesh (peers on the same private network you control), trusted (cryptographically verified — reserved for future mTLS work). Surfaced on the AgentCard’s x-scitex-agent-container.trust field.

redact: list[str]

Substring tokens; any inbound text field containing one is refused with HTTP 400. Cheap defense-in-depth against accidentally forwarding secrets to an untrusted upstream — NOT a substitute for proper output filtering at the source.

__init__(upstream='', trust='untrusted', redact=<factory>, timeout_s=30.0)

timeout_s: float = 30.0

Per-turn upstream HTTP timeout. Forwarded turns that take longer than this surface as 504 to the caller.

class scitex_agent_container.config.RestartSpec(policy='never', max_retries=3, backoff_initial=30, backoff_max=300, backoff_multiplier=2, prune_on_stop=False)

Bases: object

policy: str = 'never'

max_retries: int = 3

backoff_initial: int = 30

backoff_max: int = 300

backoff_multiplier: int = 2

prune_on_stop: bool = False

__init__(policy='never', max_retries=3, backoff_initial=30, backoff_max=300, backoff_multiplier=2, prune_on_stop=False)

class scitex_agent_container.config.SchedulingSpec(mode='per-host', preferred_host='', fallback_hosts=<factory>)

Bases: object

Fleet-wide scheduling policy for an agent (shared-host layout).

mode controls effective-id composition and launch-skip behavior:

• per-host (default): agent is started on every host that runs sac agent start <name>; the effective id is <metadata.name>-<HOST> unless the name already ends with -<HOST>.

• singleton: exactly one instance fleet-wide. The effective id stays as the bare <metadata.name>. Only launched on preferred-host; on other hosts the launch is a no-op.

fallback-hosts is recorded for observability but not acted on automatically — manual failover today.

mode: str = 'per-host'

preferred_host: str = ''

fallback_hosts: list[str]

__init__(mode='per-host', preferred_host='', fallback_hosts=<factory>)

class scitex_agent_container.config.SkillsSpec(required=<factory>, available=<factory>, injection_mode='at-import', match_by=<factory>, match_style='exact')

Bases: object

required: list[str]

available: list[str]

injection_mode: str = 'at-import'

match_by: list[str]

match_style: str = 'exact'

__init__(required=<factory>, available=<factory>, injection_mode='at-import', match_by=<factory>, match_style='exact')

class scitex_agent_container.config.StartupCommand(delay=0, command='')

Bases: object

delay: int = 0

command: str = ''

__init__(delay=0, command='')

class scitex_agent_container.config.WatchdogSpec(enabled=False, interval=1.5, resp_y_n='1', resp_y_y_n='2', resp_waiting='/speak-and-call')

Bases: object

enabled: bool = False

interval: float = 1.5

resp_y_n: str = '1'

resp_y_y_n: str = '2'

resp_waiting: str = '/speak-and-call'

__init__(enabled=False, interval=1.5, resp_y_n='1', resp_y_y_n='2', resp_waiting='/speak-and-call')

scitex_agent_container.config.compose_effective_name(raw_name, hosts_spec, hostname)

Return the effective agent id given dir-derived name + host/hosts + host.

Return type:

str

Rules:

• If hosts: is set (multi-instance), append -<hostname> so each host’s instance has a unique id. Idempotent — names that already end with -<hostname> are not double-suffixed.

• Otherwise (host: set, or both empty = local singleton): keep the bare raw_name. Singleton id stays stable across hosts.

scitex_agent_container.config.load_config(path)

Load and validate a YAML config, returning an AgentConfig.

Only scitex-agent-container/v3 is accepted. Older apiVersions (v1, v2) raise loud validation errors — no backward compatibility.

Return type:

AgentConfig

scitex_agent_container.config.resolve_config(name_or_path)

Resolve agent name or path to a config file path.

Every agent lives in its own directory; the config file is always named spec.yaml (or spec.yml). The flat-form <base>/<name>.yaml and the legacy <base>/<name>/<name>.yaml are no longer accepted — sac is dir-as-SSoT.

Search order for short names (no slash, no .yaml/.yml suffix):

0. Project-local — first .scitex/agent-container/agents/ found walking upward from cwd. Highest priority so checked-in test agents and CI fixtures override globals.

1. ~/.scitex/agent-container/agents/<name>/spec.yaml (sac install root).

2. $SCITEX_AGENT_CONTAINER_YAML_DIRS (colon-separated extra dirs, each searched as <dir>/<name>/spec.yaml). Plugin port for downstream orchestrators to inject extra paths without sac knowing about them.

Scope ($SAC_AGENT_SCOPE): if the requested NAME resolves in BOTH a project-local registry AND the fleet and the scope is unset, this raises AmbiguousRegistryScope (a real collision) instead of silently preferring project-local. A name present in only one registry resolves with no error, even when both registry dirs exist. SAC_AGENT_SCOPE=user searches only the fleet; =project only project-local.

Pass an explicit path (with / or .yaml/.yml) to bypass the search entirely.

Return type:

str

scitex_agent_container.config.resolve_hostname(gethostname=<built-in function gethostname>)

Return the canonical host label for this machine.

Resolution order (first non-empty wins):

1. SCITEX_AGENT_CONTAINER_HOSTNAME env var (manual override).

2. SCITEX_AGENT_CONTAINER_HOSTNAME env var.

3. hostname_aliases[short hostname] from shared/config.yaml or ~/.scitex/agent-container/config.yaml.

4. socket.gethostname() short form (identity fallback).

Parameters:

gethostname (Callable[[], str]) – Callable returning the raw OS hostname. Defaults to socket.gethostname (production). Tests inject a callable returning a fixed string instead of patching socket.

Raises:

RuntimeError – If none of the sources produces a non-empty value. This should be practically impossible (gethostname() returns something on any configured box) but is handled loudly rather than returning the empty string.

Return type:

str

scitex_agent_container.config.substitute_hostnames(obj, hostname=None)

Recursively walk a dict/list/str and substitute hostname placeholders.

Non-string leaves (int, bool, None) are returned unchanged. The walk is pure-functional — the input is not mutated; a new structure is returned.

Parameters:

• obj (Any) – YAML-parsed structure (dict/list/scalar).

• hostname (str | None) – Override hostname (for tests). If None, calls resolve_hostname().

Return type:

Any

scitex_agent_container.config.validate_config(path)

Validate a config file and return list of errors (empty = valid).

Return type:

list[str]

Runtimes

Modular TUI prompt detection and response for Claude Code.

Each prompt handler defines: - name: identifier for logging - detect(content) -> bool: whether this prompt is visible - respond(send_keys) -> None: keystrokes to accept the prompt - priority: lower = checked first (default 10)

Add new handlers by appending to PROMPT_HANDLERS or calling register_prompt().

class scitex_agent_container.runtimes.prompts.PromptHandler(name, detect, keys=<factory>, priority=10)

Bases: object

A single TUI prompt detector and responder.

name: str

detect: Callable[[str], bool]

keys: list[str]

priority: int = 10

__init__(name, detect, keys=<factory>, priority=10)

scitex_agent_container.runtimes.prompts._detect_bypass_permissions(content)

Bypass Permissions mode prompt with radio selector.

Return type:

bool

Matches:

“1. No, exit” “2. Yes, I accept” “Bypass Permissions” “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_dev_channels(content)

Development channels loading confirmation.

Return type:

bool

Matches:

“1. I am using this for local development” “2. Exit” “development channels” or “dangerously-load-development-channels” “Enter to confirm”

scitex_agent_container.runtimes.prompts.has_esc_cancel_modal(content)

True iff an on-screen modal treats Esc as CANCEL / EXIT.

The fatal boot bug (card sac-boot-automation-devchannels-modal-continue-compose-buffer): the stale-compose clear sends Escape, but while the --dangerously-load- development-channels confirmation is up (”❯ 1. I am using this for local development … Enter to confirm · Esc to cancel”) an Escape CANCELS the launch → claude exits → the tmux session DIES mid-boot. Any drain step that would send Escape (the compose-buffer clear) MUST first verify no such cancelable modal is on screen.

Detection is deliberately BROAD — a keystroke that kills the session is far costlier than a spurious “don’t-Esc” skip:

• the explicit Esc to cancel footer any confirm-modal renders, OR

• the dev-channels modal specifically (its footer wording has varied across Claude Code builds; match the option text too so a reworded footer still guards).

Pure + string-only so the drain-ordering guard is unit-testable without a live TUI.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_thinking_effort(content)

Thinking effort level selector.

Return type:

bool

Matches:

“1. * Medium (recommended)” or similar “thinking” in various casings “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_skip_permissions_yn(content)

Legacy y/n text prompt for skip-permissions (older Claude Code).

Matches text-based y/n prompts without radio selector.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_mcp_json_edit(content)

Permission prompt when Claude tries to edit .mcp.json (runtime).

Matches “1. Yes” / “1. Proceed” / “1. Allow” + “.mcp.json” + “Enter to confirm”.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_press_enter_continue(content)

Generic ‘Press Enter to continue’ runtime pause (context-window warning, etc).

Uses a strict last-5-lines window to avoid scrollback false positives (per pane-state-patterns.md: classify against last 5 visible lines only). Excluded: active tool calls and numbered radio selectors.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_file_trust(content)

‘Do you trust the files in this folder?’ prompt (first-run or new cwd).

May appear when –dangerously-skip-permissions was not propagated to a subshell. Matches the LEGACY y/n text variant; the new radio-selector variant is handled by _detect_file_trust_radio().

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_file_trust_radio(content)

Radio-selector variant of the file-trust prompt.

Claude Code (>= ~2.1.x) asks “Is this a project you created or one you trust?” with numbered options instead of the legacy y/n text prompt. Appears on the first launch in any un-trusted workdir — including every throwaway tempdir the Haiku integration test uses.

Matches the exact option strings to avoid firing on the bypass-permissions dialog (which also says “Enter to confirm”).

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_external_imports(content)

External CLAUDE.md file imports prompt.

Appears when CLAUDE.md (or .claude/CLAUDE.md) contains @<absolute-path> imports pointing OUTSIDE the agent’s workdir. Triggered by the at-import skill-injection mode (sac PR #74) when skills live in ~/.claude/skills/ or the package source trees rather than the workspace itself.

Return type:

bool

Matches:

“Allow external CLAUDE.md file imports?” “1. Yes, allow external imports” “Enter to confirm”

scitex_agent_container.runtimes.prompts._detect_login_method(content)

First-run login-method picker on a fresh HOME.

Appears when Claude Code can’t find OAuth credentials at ~/.claude/.credentials.json. Even with ANTHROPIC_API_KEY set in env, the 2.1.x CLI still asks which auth mode to use before it checks the env var. Blocks startup until dismissed.

Matches the exact option strings to avoid false positives on any user message that happens to say “login method”.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_theme_selection(content)

First-run theme selection prompt.

Appears only on a fresh HOME (no ~/.claude/ saved theme). On dev machines it never shows, but in CI (a clean ubuntu VM) this is the first thing Claude Code asks. Blocks every downstream startup prompt until acknowledged.

Matches the radio variant: “Choose the text style…” + numbered options starting with “1. Auto (match terminal)”.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_compose_pending_unsent(content)

Detect unsent text sitting in the Claude Code compose buffer.

The classifier in agent_meta._classify_pane_state matches ❯[ \t\xa0]+\S (non-whitespace after the prompt marker on the same line), meaning the user has typed something but not yet pressed Enter. We mirror that pattern here so the prompts system can submit it via a plain Enter keystroke.

The gap MUST include U+00A0 NO-BREAK SPACE: Claude Code’s Ink TUI renders the prompt as ❯\xa0[Pasted text …] (an NBSP, not an ASCII space). The earlier ❯[ \t]+ pattern silently missed it, so a multi-line startup_prompt paste was never detected as pending and the boot-drain / _verify_submitted resend never fired — the agent sat idle with its instructions pasted-but-unsent (proj-scitex-dev 2026-06-23).

Excluded: lines that are just the decorative separator below an empty prompt — those contain only whitespace after ❯.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_resume_session(content)

Long-session resume picker shown by claude --continue / --resume.

When the session being resumed is large, Claude Code interposes a three-way picker before the REPL opens:

This session is <N>h <M>m old and <K>k tokens.
Resuming the full session will consume a substantial portion ...
❯ 1. Resume from summary (recommended)
  2. Resume full session as-is
  3. Don't ask me again

The sac TUI boot uses --continue precisely to resume the FULL prior context, so we always pick option 2 (“Resume full session as-is”). Left unhandled this modal BLOCKS boot: the startup_prompt paste lands inside the picker and the boot-drain hangs (lead-retirement, 2026-06-25). Must out-rank compose-pending-unsent — the modal’s ❯ 1. line also matches that detector — hence priority 1.

Return type:

bool

scitex_agent_container.runtimes.prompts._detect_done(content)

Check if claude is at the main input prompt (all TUI prompts done).

The status bar shows “bypass permissions” when ready.

Return type:

bool

scitex_agent_container.runtimes.prompts.register_prompt(handler)

Add a custom prompt handler to the registry.

Return type:

None

scitex_agent_container.runtimes.prompts._LIVE_WINDOW_LINES = 15

How many non-empty rows of a captured pane count as the LIVE region for modal detection. See _recent_tail() for the false-positive this guards against; sized with headroom over the tallest verified real modal capture (_LIVE_BYPASS_PANE in test_prompts.py, 9 non-empty rows).

scitex_agent_container.runtimes.prompts._recent_tail(content, lines=15)

Return the last lines non-empty rows of content.

Scopes modal detection to the LIVE region of a captured pane instead of the entire accumulated snapshot tmux capture-pane -p (no -S) returns the whole VISIBLE viewport, not just the freshest output. Once Claude Code’s Ink TUI has moved a first-run modal’s rendered text further up the screen — dismissed, but not yet scrolled past the viewport — an unscoped substring match can still fire on it long after the modal is gone, sending its registered digit+``Enter`` into what is now the plain, empty compose box: card sac-tui-stray-1-submitted-on-boot — a spurious "1" gets typed and submitted as a user message during boot (observed with the thinking-effort / file-trust-radio / theme-selection handlers, none of which scoped their match to the live screen).

_LIVE_WINDOW_LINES comfortably covers the tallest verified real modal capture with headroom, while still excluding an EARLIER, already-dismissed modal’s text once enough new output has rendered below it. Mirrors _detect_press_enter_continue()’s existing last-N-lines window (same fix shape, wider here because these handlers need a whole title+options+footer block, not one banner line) and _tui_compose._compose_pending_live()’s bottom-anchored scoping for the analogous Enter-drop bug (sac-tui-enter-drop-on-boot).

Return type:

str

scitex_agent_container.runtimes.prompts.detect_and_respond(content, accepted, send_keys_fn)

Check content against all handlers, respond to the first match.

Parameters:

• content (str) – Captured pane content.

• accepted (set[str]) – Set of already-accepted prompt names.

• send_keys_fn (Callable[..., None]) – Callable to send keystrokes (e.g., mux.send_keys).

Return type:

str | None

Returns:

Name of the matched prompt, or None if no match.

scitex_agent_container.runtimes.prompts.detect(content)

Return the NAME of the first matching prompt handler (by priority), or None when no known modal is on screen. Detect-only — sends nothing.

Pairs with respond_modal() so a drain loop can RESPOND, settle, then re-detect to VERIFY the modal actually cleared — instead of firing keystrokes once and assuming success. Claude’s Ink TUI drops keys sent mid-render, so a fire-and-forget send silently leaves the modal up; the detect/respond/verify cycle is the no-silent-fallback fix.

Matches against _recent_tail() (the LIVE region), not the raw content — see its docstring for the stray-boot-submit false positive this prevents.

Return type:

str | None

scitex_agent_container.runtimes.prompts.respond_modal(name, send_keys_fn)

Send the registered keystrokes for the handler named name.

Returns True iff a handler with that name exists (its keys were sent), False otherwise. The caller MUST verify the modal cleared (re-capture + detect()) and resend on the render race — a single send is not guaranteed to land.

Return type:

bool

scitex_agent_container.runtimes.prompts.is_ready(content)

Check if claude is at the main input prompt (all TUI prompts done).

Return type:

bool