ait-agent-worker: Messaging and Reply Runtime

Role in ait-native#

ait-agent is the release-family component and ait-agent-worker is its Python-free native executable. The worker is an optional, Repository-scoped messaging transport and reply execution surface for Telegram, LINE, Discord, and Slack.

The worker is not required for ordinary ait CLI use and it is not a separate desktop or mobile coding client. A primary coding client remains responsible for the interactive authoring experience. ait-agent-worker accepts a message from one explicitly configured transport, binds it to one Repository context, obtains a bounded reply, and returns that reply through the same transport.

The worker does not automatically create a sprint card, start a Task, create a Snapshot, or Land a Change. Those workflow mutations occur only when the reply provider or another authorized client explicitly runs the corresponding ait commands.

Appropriate uses#

• Operate one named messaging bot against one AIT Repository without a Python worker runtime.
• Receive Telegram, LINE, Discord, or Slack requests through the transport mode implemented for that service and return Repository-contextual replies.
• Place a native, headless worker behind a trusted service supervisor or HTTP adapter.
• Inspect the exact transport, event-loop, platform, and fallback capabilities compiled into an installed executable before admitting it to service.
• Use the worker's native Codex reply provider, or supply one explicit custom local reply program for a controlled integration.

Use ait-server rather than ait-agent-worker for remote Repository authority, offsite preservation, recovery, Patchset CI, and runner job coordination. The worker may resolve a local or remote Repository target, but it is not the server's administration API.

Message-to-reply execution path#

1. The process resolves the Repository root, .ait/config.json, and the worker manifest. AIT_AGENT_CONFIG_PATH may select a different manifest path.
2. The manifest is normalized and the exact <kind>/<name> worker is selected. Invalid fields, a missing worker, or a kind/name mismatch fail before the transport starts.
3. Credentials and runtime settings are resolved. The effective workflow mode determines whether the Repository target is local or uses its configured default remote.
4. The requested native event-loop backend and zero-based shard are checked against the runtime admission plan. A backend or shard mismatch fails closed.
5. The transport authenticates or verifies its service-specific ingress, parses the exact request, applies its conversation and duplicate state, and submits a bounded reply job.
6. The configured local reply program runs. When no complete custom provider is supplied, the native worker installs its own reply-provider subcommand and invokes Codex with the selected model, reasoning effort, sandbox, and timeout.
7. The transport sends or returns the reply. Failures use a structured native diagnostic and do not fall back to a Python worker.

The worker's sync state and Codex thread binding keep transport conversation identity separate from AIT workflow authority. A resumed conversation can reuse its compatible Codex thread, while Task, Change, Snapshot, and Land state remain owned by AIT.

Complete executable command surface#

Exact RC.6 forms:

ait-agent-worker capabilities [--json]

ait-agent-worker run \
  --transport <telegram|discord|slack|line> \
  --worker <name> \
  --event-loop-backend <backend-reported-by-capabilities> \
  --shard <zero-based-index> \
  [--console-mode <service|webhook>]

ait-agent-worker slack-command [--worker <name>] < exact-slack-body
ait-agent-worker discord-interaction [--worker <name>] < exact-discord-body
ait-agent-worker reply-provider < provider-request.json

service is the default run console mode. Use webhook only for one Telegram webhook payload supplied on stdin. The Slack and Discord one-shot commands are adapter boundaries, not unauthenticated network listeners: the caller must preserve the exact raw body and supply the matching signature and timestamp metadata through the trusted request boundary.

Before launch, record both forms of capability evidence:

ait-agent-worker --version
ait-agent-worker capabilities
ait-agent-worker capabilities --json

Do not infer a backend or transport from the operating-system name alone. Use the installed binary's capability result, then pass the backend and shard selected by launch planning to run.

Transport behavior#

All listener defaults are loopback addresses. Put an HTTP listener behind a trusted reverse proxy only after request verification, TLS, body-size, timeout, and forwarding behavior have been tested with the exact selected transport.

Native Codex reply provider#

Transport workers need a reply provider; they do not contain a second coding model. An explicit complete local_reply.program plus local_reply.args configuration wins. Otherwise the native executable configures itself as the provider by running its reply-provider subcommand.

The native provider accepts the versioned ait.agent.gateway_reply_provider_request.v1 JSON contract. The request binds one Repository root, conversation key, surface, actor, input payload, optional prior provider thread, and reply settings. It starts or resumes a Codex thread for that compatible Repository and conversation, captures the final reply and bounded turn telemetry, and returns the versioned response contract.

The provider enforces bounded request and process-output sizes, a thread lock, the configured timeout, and one of read-only, workspace-write, or danger-full-access sandbox values. Sandbox selection is the execution boundary. It must match what the worker is allowed to do in that Repository; transport credentials do not grant additional filesystem or AIT authority.

Admission, concurrency, and shutdown#

run never chooses an arbitrary shard. It normalizes the full worker manifest, plans the configured worker set against the selected native event-loop backend, and verifies that the requested worker belongs to the supplied shard. Telegram can additionally bound expected concurrent workers and workers per shard.

Transport reply work uses bounded native job admission. When capacity is full, the worker reports failure instead of creating unbounded background work. A service stops accepting new jobs before draining admitted work; process-control behavior is the native backend reported by capabilities.

Failure and security contract#

Operational failures are written to stderr as ait.agent.worker.error.v1 JSON. The diagnostic contains a stable code, message, numeric exit code, bounded details, and python_worker_execution_allowed: false.

Diagnostics report credential presence, not values. Slack and Discord verify the exact raw body. One-shot outcomes redact secrets and delivery locators. Python fallback is disabled for RC.6 transport, signature, reply, and state work.

Deliberate limits#

• ait-agent-worker is not a general-purpose desktop, mobile, or web app.
• It is not the durable remote authority and does not replace ait-server.
• Receiving a message does not itself create or complete AIT workflow objects.
• A transport worker is scoped to one resolved Repository and one named worker selection per process invocation.
• The public commands do not bypass transport signatures, manifest validation, runtime admission, Codex sandboxing, or AIT workflow policy.

Configuration map#

• Appendix: Agent-worker Configuration expands .ait/agent-workers.json, credential precedence, every transport field, local reply settings, runtime paths, and verification guidance.
• Appendix: Environment Variables identifies the supported worker bootstrap and credential environment inputs.
• ait-server: Remote Authority and Recovery explains the separate remote authority, preservation, and recovery boundary.