# 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.show()                   # `sac host show`
    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.

scitex_agent_container._PackageNotFoundError

  alias of `PackageNotFoundError`

scitex_agent_container._version(distribution_name)

  Get the version string for the named package.

  Parameters:

    distribution_name – The name of the distribution package to query.

  Returns:

    The version string for the package as defined in the package’s “Version” metadata key.

## Config

YAML config loading and validation for agent definitions.

Public API:

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

class scitex_agent_container.config.AgentConfig(name, runtime='apptainer', 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>, telegram=<factory>, remote=<factory>, skills=<factory>, context_management=<factory>, startup_commands=<factory>, startup_prompts=<factory>, startup=<factory>, mcp_servers=<factory>, multiplexer='tmux', hosts_spec=<factory>, scheduling=<factory>, config_path='', mounts=<factory>, user='', a2a=<factory>, kind='Agent', proxy=None, dot_claude='')

  Bases: `object`

  Parsed agent configuration from a YAML definition file.

  __init__(name, runtime='apptainer', 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>, telegram=<factory>, remote=<factory>, skills=<factory>, context_management=<factory>, startup_commands=<factory>, startup_prompts=<factory>, startup=<factory>, mcp_servers=<factory>, multiplexer='tmux', hosts_spec=<factory>, scheduling=<factory>, config_path='', mounts=<factory>, user='', a2a=<factory>, kind='Agent', proxy=None, dot_claude='')
  config_path: `str` = ''
  dot_claude: `str` = ''
  property expanded_workdir: str
  image: `str` = ''
  kind: `str` = 'Agent'
  model: `str` = 'sonnet'
  multiplexer: `str` = 'tmux'
  proxy: `Any` = None
  python_venv: `str` = ''
  runtime: `str` = 'apptainer'
  screen_name: `str` = ''
  user: `str` = ''
  workdir: `str` = ''
  name: `str`
  env: `dict`[`str`, `str`]
  env_files: `list`[`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`]
  telegram: `TelegramSpec`
  remote: `RemoteSpec`
  skills: `SkillsSpec`
  context_management: `ContextManagementConfig`
  startup_commands: `list`[`StartupCommand`]
  startup_prompts: `list`[`str`]
  startup: `StartupSpec`
  mcp_servers: `dict`[`str`, `dict`]
  hosts_spec: `HostsSpec`
  scheduling: `SchedulingSpec`
  mounts: `list`[`dict`]
  a2a: `A2ASpec`

class scitex_agent_container.config.ClaudeSpec(model='', channels=<factory>, flags=<factory>, raw_options=<factory>, session='continue', continue_max_age_minutes=None, resume_id='', auto_accept=True)

  Bases: `object`

  __init__(model='', channels=<factory>, flags=<factory>, raw_options=<factory>, session='continue', continue_max_age_minutes=None, resume_id='', auto_accept=True)
  auto_accept: `bool` = True
  continue_max_age_minutes: `int` | `None` = None
  model: `str` = ''
  resume_id: `str` = ''
  session: `str` = 'continue'
  channels: `list`[`str`]
  flags: `list`[`str`]
  raw_options: `dict`

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

  Bases: `object`

  __init__(runtime='none', image='scitex-agent-container:latest', volumes=<factory>, network='host', mount_host_claude=False)
  image: `str` = 'scitex-agent-container:latest'
  mount_host_claude: `bool` = False
  network: `str` = 'host'
  runtime: `str` = 'none'
  volumes: `list`[`str`]

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).

  __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')
  check_interval_seconds: `int` = 300
  property enabled: bool
  state_file: `str` = '~/.scitex/agent-container/state/<agent>.json'
  strategy: `str` = 'noop'
  trigger_at_percent: `float` = 70.0
  warn_before_n_checks: `int` = 0

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

  Bases: `object`

  __init__(enabled=False, interval=30, timeout=5, method='multiplexer-alive')
  enabled: `bool` = False
  interval: `int` = 30
  method: `str` = 'multiplexer-alive'
  timeout: `int` = 5

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).

  __init__(pre_start=<factory>, post_start=<factory>, pre_stop=<factory>, post_stop=<factory>, on_compact=<factory>, on_restart=<factory>, on_diff=<factory>)
  counts()
    Return type:

      `dict`[`str`, `int`]

  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`]

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.

  __init__(host='', hosts=<factory>)
  host: `str` | `list`[`str`] = ''
  hosts: `str` | `list`[`str`]

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.

  __init__(port=0, proto='tcp', path='', name='', owner='')
  name: `str` = ''
  owner: `str` = ''
  path: `str` = ''
  port: `int` = 0
  proto: `str` = 'tcp'

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

  Bases: `object`

  Configuration for kind: AgentProxy agents.

  __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.

  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.

  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).

  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.

class scitex_agent_container.config.ReadyPattern(regex='')

  Bases: `object`

  A single regex the pane content must match for the agent to be ready.

  __init__(regex='')
  regex: `str` = ''

class scitex_agent_container.config.RemoteSpec(hops=<factory>, host='', user='', key='', port=22, timeout=60, login_shell=True, no_preflight=False)

  Bases: `object`

  __init__(hops=<factory>, host='', user='', key='', port=22, timeout=60, login_shell=True, no_preflight=False)
  host: `str` = ''
  property is_remote: bool

    Return True if this agent should be deployed via SSH.

  key: `str` = ''
  login_shell: `bool` = True
  no_preflight: `bool` = False
  port: `int` = 22
  timeout: `int` = 60
  user: `str` = ''
  hops: `list`

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

  Bases: `object`

  __init__(policy='never', max_retries=3, backoff_initial=30, backoff_max=300, backoff_multiplier=2)
  backoff_initial: `int` = 30
  backoff_max: `int` = 300
  backoff_multiplier: `int` = 2
  max_retries: `int` = 3
  policy: `str` = 'never'

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.

  __init__(mode='per-host', preferred_host='', fallback_hosts=<factory>)
  mode: `str` = 'per-host'
  preferred_host: `str` = ''
  fallback_hosts: `list`[`str`]

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

  Bases: `object`

  __init__(required=<factory>, available=<factory>, injection_mode='at-import', match_by=<factory>, match_style='exact')
  injection_mode: `str` = 'at-import'
  match_style: `str` = 'exact'
  required: `list`[`str`]
  available: `list`[`str`]
  match_by: `list`[`str`]

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

  Bases: `object`

  __init__(delay=0, command='')
  command: `str` = ''
  delay: `int` = 0

class scitex_agent_container.config.StartupSpec(ready_patterns=<factory>, ready_idle_ticks=3, ready_poll_interval_seconds=0.5, ready_timeout_seconds=60.0, on_timeout='capture_and_proceed', commands=<factory>)

  Bases: `object`

  Opt-in ready-state gate for startup commands (todo#291).

  When `ready_patterns` is empty, legacy fire-and-hope behavior is preserved. Otherwise `agent_start` polls the tmux pane content and only dispatches `commands` once all patterns match against the tail of the capture AND the pane has been byte-identical for `ready_idle_ticks` consecutive polls.

  __init__(ready_patterns=<factory>, ready_idle_ticks=3, ready_poll_interval_seconds=0.5, ready_timeout_seconds=60.0, on_timeout='capture_and_proceed', commands=<factory>)
  on_timeout: `str` = 'capture_and_proceed'
  ready_idle_ticks: `int` = 3
  ready_poll_interval_seconds: `float` = 0.5
  ready_timeout_seconds: `float` = 60.0
  ready_patterns: `list`[`ReadyPattern`]
  commands: `list`[`StartupCommand`]

class scitex_agent_container.config.TelegramSpec(bot_token_env='SCITEX_AGENT_CONTAINER_TELEGRAM_BOT_TOKEN', allowed_users=<factory>, auto_connect=True, greeting='')

  Bases: `object`

  __init__(bot_token_env='SCITEX_AGENT_CONTAINER_TELEGRAM_BOT_TOKEN', allowed_users=<factory>, auto_connect=True, greeting='')
  auto_connect: `bool` = True
  bot_token_env: `str` = 'SCITEX_AGENT_CONTAINER_TELEGRAM_BOT_TOKEN'
  greeting: `str` = ''
  allowed_users: `list`[`str`]

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`

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

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.

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

  Return type:

    `str`

scitex_agent_container.config.resolve_hostname()

  Return the canonical host label for this machine.

  Return type:

    `str`

  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).

  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.

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._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]+\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.

  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_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.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.is_ready(content)

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

  Return type:

    `bool`