API FIELD MANUAL / 01
Agent control that stays machine-readable.
Generated Bash and PowerShell helpers plus authenticated JSON APIs let an agent create and steer real PTY workers, inspect evidence, and publish explicit state. MidTerm supplies transport and persistence—not another model.
By Johannes G. E. Schmidt · Updated July 14, 2026
60-SECOND PATH / 02
Bootstrap. Capture the exact ID. Address that session.
Run inside a MidTerm terminal. MidTerm generates and refreshes the local .midterm helpers for the session working directory.
Bash
. .midterm/mtcli.sh
worker_json=$(mt_bootstrap "review worker" "$PWD" codex status)
sid=$(printf '%s' "$worker_json" | jq -r '.session.id')
mt_prompt "$sid" \
"Review the auth change, run focused tests, then publish a verified checkpoint."
mt_tail "$sid" 80
mt_publish_status \
working \
"Reviewing auth change" \
"Run focused tests" \
"Publish verification" \
MidTerm \
"$sid" \
"$PWD"
mt_checkpoint \
verified \
"Focused tests passed" \
"18 backend tests" \
MidTerm \
"$sid" \
"$PWD"
mt_control_plane | jqPowerShell
. .\.midterm\mtcli.ps1
$worker = Mt-Bootstrap `
-Name 'review worker' `
-Cwd $PWD.Path `
-Profile codex `
-SlashCommands @('status')
$sid = ($worker | ConvertFrom-Json).session.id
Mt-Prompt -InputArgs @(
$sid
'Review the auth change, run focused tests, then publish a verified checkpoint.'
)
Mt-Tail -InputArgs @($sid, '80')
Mt-PublishStatus `
-State working `
-Summary 'Reviewing auth change' `
-CurrentTask 'Run focused tests' `
-NextAction 'Publish verification' `
-Project MidTerm `
-SessionId $sid `
-RepositoryPath $PWD.Path
Mt-Checkpoint `
-Kind verified `
-Summary 'Focused tests passed' `
-Details '18 backend tests' `
-Project MidTerm `
-SessionId $sid `
-RepositoryPath $PWD.Path
Mt-ControlPlane | ConvertFrom-Jsonmt_bootstrap NAME CWD PROFILE [SLASH_COMMAND ...] returns JSON. The exact handle for that live worker is session.id; do not guess a session from its display name. The Bash example uses jq only to extract that field.
RUNTIME BOUNDARY / 03
A supervised PTY is not Agent Controller.
The flags are deliberately separate because the execution models are different.
agentControlled: true | Supervision metadata on a normal terminal session. mt_bootstrap creates this kind of worker, injects guidance, and launches the selected CLI inside a real mthost PTY. |
|---|---|
appServerControlOnly: true | An explicit provider-backed Agent Controller session through mtagenthost: structured history, tool lifecycle, approvals, questions, diffs, and turn controls—without a PTY or terminal buffer. |
| Normal terminal | Works with any terminal program and exposes buffer, tail, paste, raw keys, Git, browser, history, and control-plane helpers. Its CLI output remains terminal output. |
| No auto-promotion | Starting Codex, Claude Code, Grok, OpenCode, or another CLI in Terminal never silently converts that session into Agent Controller. |
Query mt_agent_capabilities before choosing a control path. Each session reports agentControlled, appServerControlAttached, appServerControlOnly, surface, profileHint, and supported promptModes.
COMMAND MAP / 04
Use the narrowest explicit surface.
The same generated file can be dot-sourced or executed directly as .midterm/mtcli.sh mt_status or pwsh .midterm\mtcli.ps1 mt_status.
| Create and inspect | mt_sessions, mt_new_session [SHELL] [CWD], mt_bootstrap NAME CWD PROFILE [SLASH_COMMAND ...], mt_tail [SESSION_ID] [LINES], mt_buffer [SESSION_ID], mt_activity [SESSION_ID] [SECONDS] [BELL_LIMIT]. |
|---|---|
| Steer a PTY | mt_prompt [SESSION_ID] TEXT, mt_prompt_now [SESSION_ID] TEXT, mt_slash [SESSION_ID] COMMAND, mt_paste, mt_sendtext, mt_sendkeys, and explicit Enter, Ctrl-C, Escape, and arrow helpers. |
| Browser evidence | mt_preview, mt_open, mt_status, mt_outline, mt_query, mt_text, mt_exec, mt_click, mt_fill, mt_wait, mt_log, mt_proxylog, mt_screenshot. |
| Repository state | mt_repo list|status|add PATH [ROLE] [LABEL]|remove REPO_ROOT|refresh [REPO_ROOT] and mt_supervise [REPO_PATH ...]. |
| Input history | mt_input_history [SESSION_ID] [KIND] [LIMIT], mt_input_history_show, mt_input_history_replay, mt_input_history_delete, mt_input_history_clear. |
| Published state | mt_work_list|add|update|delete, mt_publish_status, mt_status_list|clear, mt_checkpoint, mt_checkpoints, mt_events. |
| Fan-out | mt_dispatch SESSION_ID[,SESSION_ID...] TEXT sends one explicit turn to named local sessions. mt_control_plane reads the resulting host snapshot. |
JSON CONTRACTS / 05
Stable roots, explicit records.
Use these response keys instead of parsing terminal prose.
mt_bootstrap | session, profile, launchCommand, slashCommands, guidanceInjected, midtermDir. The exact worker ID is session.id. |
|---|---|
mt_agent_capabilities | schemaVersion, features, workItemStates, sessionStates, sessions. Session records expose the runtime flags listed above. |
mt_control_plane | workItems, sessionStatuses, checkpoints. |
mt_events | latestSequence, events. Pass the last sequence back as AFTER_SEQUENCE for incremental reads. |
mt_dispatch | results; every result has sessionId, accepted, queued, and nullable error. |
| Lists | mt_work_list → totalCount, items; mt_status_list → statuses; mt_checkpoints → totalCount, checkpoints. |
mt_input_history | totalCount, entries. Entry kinds are prompt, textPaste, imagePaste, and fileUpload. |
mt_repo list | repos; each binding contains repoRoot, label, role, source, isPrimary, and status. |
Work-item states: open, active, waiting, blocked, done, dismissed. Session states: working, waiting, needsInput, blocked, done. Priorities: low, normal, high, urgent.
The control plane is an outlet, not an agent. MidTerm persists what callers publish; it does not invent tasks, summaries, next actions, or completion claims.
HTTP + AUTH / 06
The helpers are authenticated API clients.
Use them for normal work; call the routes directly when another tool needs the raw contract.
| Worker | POST /api/workers/bootstrap, GET /api/sessions/{id}/buffer/tail, POST /api/sessions/{id}/input/prompt. |
|---|---|
| Control plane | GET /api/control-plane, GET /api/control-plane/capabilities, GET /api/control-plane/events, POST /api/control-plane/dispatch. |
| Published records | /api/control-plane/work-items, /api/control-plane/session-status/{sessionId}, /api/control-plane/checkpoints. |
| History and Git | /api/input-history, /api/input-history/{id}/replay, /api/git/repos, /api/git/repos/refresh. |
The generated helper contains a machine-local browser-session credential with an approximately eight-day lifetime. Treat .midterm/mtcli.sh and .midterm/mtcli.ps1 as secrets. Set MT_API_KEY to use Authorization: Bearer instead.
For remote use, keep MidTerm HTTPS and password authentication enabled and restrict the network path. See the Tailscale remote-access security runbook.
LIMITS / 07
Deterministic where it matters. Honest where it cannot be.
These boundaries prevent automation from pretending to know more than it does.
| Attention | mt_attention ranks sessions from process profile, timing, activity heat, and bells. It is operational guidance, not semantic proof that an agent is done or blocked. |
|---|---|
| Prompt mode | mt_prompt uses the state-aware automatic path. Use mt_prompt_now only when an explicit interrupt-first turn is intended. |
| Dispatch | Dispatch is immediate and local. It does not wait for an idle PTY or maintain a PTY queue; queued is currently false. Hub variants read remote snapshots, events, and capabilities but do not write or dispatch across machines. |
| Browser | Browser commands need a connected MidTerm UI and a controllable preview. Most browser helper output is compact text; mt_capabilities --json is the discovery exception. |
| History | Input history records explicit MidTerm-handled prompts, terminal submissions, pastes, images, and files per session. It never reconstructs intent from PTY output, and raw mt_sendtext or mt_sendkeys calls are not history entries by themselves. |
| Reference coverage | The checked-in OpenAPI document does not yet enumerate every newer control-plane, history, Git, and browser route. Use capability discovery and the generated helpers as the current executable surface. |
FAQ / 08
Exact answers.
Can an AI agent control MidTerm?
Yes. Generated Bash and PowerShell helpers and authenticated HTTP APIs can create PTY workers, send prompts, read terminal tails, inspect repositories and browser previews, and publish structured work state.
Does MidTerm use its own AI to infer agent state?
No. The control plane stores explicit work items, session statuses, checkpoints, and events published by agents or tools. It does not infer semantic state from terminal output. The separate attention view and automatic prompt mode do use operational heuristics.
Does mt_bootstrap create an Agent Controller session?
No. mt_bootstrap creates a real PTY worker, marks it agentControlled, injects the generated helpers, and starts the selected CLI profile. An appServerControlOnly session is an explicit provider-backed Agent Controller surface with structured history and no PTY.
Can one control plane dispatch to other machines?
Not today. Local dispatch can fan one turn out to explicit session IDs on the same MidTerm instance. Hub endpoints can read remote snapshots, events, and capabilities, but remote writes and cross-machine dispatch are not exposed.
Does it work with any CLI?
The PTY and generic session helpers work with any terminal program. Bootstrap provides built-in launch profiles for selected AI CLIs; other CLIs can be started normally or through the raw bootstrap API with an explicit launch command.
