noacp

name	noacp
description	File-based session protocol for agents without ACP support. Wraps any CLI agent (agy, etc.) in persistent multi-turn conversations using shared session files. Use when acpx is unavailable, the target agent lacks ACP, or when user mentions noacp, agy session, file-based agent, or non-ACP agent communication. Supports agy model selection via aliases (agy-flash, agy-pro, agy-claude, etc.).

File-based session protocol. Replaces ACPX for agents that lack ACP adapters.

Concept

The orchestrator (you) owns a session file. The agent is stateless. The file IS the session. Each turn appends XML-tagged blocks. Full history re-sent each call so the agent sees context.

Quick start

# Create session (returns file path)
bash skills/noacp/scripts/session.sh new agy
# /tmp/noacp/a1b2.md

# Send first prompt
bash skills/noacp/scripts/session.sh prompt /tmp/noacp/a1b2.md "Analyze auth middleware"

# Continue (same file = same session)
bash skills/noacp/scripts/session.sh prompt /tmp/noacp/a1b2.md "Fix the timing vuln you found"

# Read history
bash skills/noacp/scripts/session.sh history /tmp/noacp/a1b2.md

Session file format

Sessions live in /tmp/noacp/ by default. Override with NOACP_DIR. Files use .xml extension.

<session agent="agy" id="auth-fix" created="2026-06-09T12:00:00Z">
<orchestrator turn="1" ts="2026-06-09T12:00:01Z">Analyze auth middleware</orchestrator>
<agent turn="1" ts="2026-06-09T12:00:15Z">Found timing vuln in...</agent>
<orchestrator turn="2" ts="2026-06-09T12:01:00Z">Fix it, minimal change</orchestrator>
<agent turn="2" ts="2026-06-09T12:01:30Z">Here is the patch: ...</agent>
</session>

Tags: <orchestrator> (you), <agent> (them). The agent attribute on <session> identifies which CLI agent is in use.

Commands

Command	Usage	What it does
new	session.sh new <agent> [id]	Create session file, print path. Random id if omitted.
prompt	session.sh prompt <file> [opts] ["text"]	Append orchestrator block, call agent, append agent block, print response.
prompt	... --timeout N	Override agent timeout for this call (seconds).
prompt	... --file prompt.txt	Read prompt text from file (avoids shell arg size limits).
history	session.sh history <file>	Print all turn pairs in readable format.
list	session.sh list	List all sessions in NOACP_DIR.
close	session.sh close <file>	Mark session closed, keep file on disk.
delete	session.sh delete <file>	Delete session file.
validate	session.sh validate <file>	Check session file integrity.

Agent registry

Defined in scripts/agents.json. Add new agents with command + input_mode:

{
  "agy": {
    "command": "agy",
    "print_flag": "-p",
    "input_mode": "flag",
    "timeout_default": 120
  }
}

input_mode values: flag (prompt via CLI flag), stdin (prompt via stdin), file (prompt via file path arg).

Choosing an agy model

agy supports model selection via --model "<name>". The exact strings live in agy models output; the registry pre-binds the common tiers to dedicated aliases. When the user asks for agy by flavor, pick the alias whose name matches; this file gives you the map.

Phrase -> alias

User says	Agent alias	Effective --model
agy (no flavor)	agy	agy's own default (no --model injected)
agy flash / agy 3.6 flash	agy-flash	Gemini 3.6 Flash (Medium)
agy flash high / quality-priority flash	agy-flash-high	Gemini 3.6 Flash (High)
agy flash low / cheap flash	agy-flash-low	Gemini 3.6 Flash (Low)
agy pro / agy 3.1 pro	agy-pro	Gemini 3.1 Pro (High)
agy pro low / cheap pro	agy-pro-low	Gemini 3.1 Pro (Low)
agy claude / agy sonnet	agy-claude	Claude Sonnet 4.6 (Thinking)
agy opus / strongest claude	agy-opus	Claude Opus 4.6 (Thinking)

If the user names the version and tier explicitly (agy 3.1 pro low, agy 3.6 flash high), use the matching suffix entry. Bare agy flash and bare agy pro map to the Medium / High defaults respectively (best price/perf). agy claude maps to Sonnet, the cheaper Claude tier that still uses the Claude quota.

Quota and cost

• Claude models (agy-claude, agy-opus) draw from the Claude quota in your Antigravity plan -- a separate bucket from Gemini. Use them only when reasoning style matters (Claude's edit behavior, instruction following). Opus is the most expensive of all options.
• Gemini 3.1 Pro is slower and pricier than 3.6 Flash but stronger on multi-step reasoning.
• Gemini 3.6 Flash (Low) is the cheapest. Use it for trivial / throwaway prompts.
• Default agy lets the CLI pick. Prefer an explicit alias if the user named one.

Discovery

Model names change between agy releases. Verify with agy models before relying on any name in this table. Add a new alias to agents.json with the verbatim string from that command, plus a matching timeout_default (Claude/Pro need higher defaults -- see existing entries).

Worked example

User: "spin up an agy pro session and review this auth PR".

bash skills/noacp/scripts/session.sh new agy-pro
# /tmp/noacp/<id>.xml

PROMPT=$(mktemp --suffix=.md)
cat > "$PROMPT" <<'EOF'
Review the auth PR against this repo. Flag timing vulns, missing CSRF,
and unsafe redirects. Output a punchlist only -- no code patches.
EOF
bash skills/noacp/scripts/session.sh prompt /tmp/noacp/<id>.xml --file "$PROMPT"
rm -f "$PROMPT"

Picking agy-pro ensures --model "Gemini 3.1 Pro (High)" is injected by session.sh automatically -- you do not need to add the flag yourself.

Prefer file input for multi-line prompts

Default to --file for any prompt longer than a single line, not only when the payload is large. File input removes shell escaping issues (quotes, backticks, $, newlines) and makes the prompt easy to inspect, edit, and replay.

PROMPT=$(mktemp --suffix=.md)
cat > "$PROMPT" <<'EOF'
Multi-line instructions go here.
Special characters like $, `, ", ', \ pass through unchanged.
EOF
bash skills/noacp/scripts/session.sh prompt /tmp/noacp/abc123.xml --file "$PROMPT"
rm -f "$PROMPT"

Single-line prompts can still go inline: bash skills/noacp/scripts/session.sh prompt /tmp/noacp/abc123.xml "summarize this file".

Limitations

• No streaming. Agent responds once per call.
• Token cost grows linearly (full history re-sent each turn).
• No tool-use callbacks during agent turn.
• No cancel mid-turn. Use OS signals (timeout wrapper).
• No parallel turns on same session. Sequential only.

Large payloads and arg size limits

Agents using flag input_mode pass the entire session file as a CLI argument. Linux ARG_MAX is typically 2MB. Session history grows each turn. The script rejects payloads over 1MB with a clear error.

For large prompts (docs, code reviews, multi-file context):

1. Use --file prompt.txt to read prompt from file
2. Use stdin or file input_mode in agents.json instead of flag
3. Start a new session when history grows too large

# Large prompt via file
bash skills/noacp/scripts/session.sh prompt /tmp/noacp/abc123.xml --file /tmp/large-review.txt

# Override timeout for slow agents
bash skills/noacp/scripts/session.sh prompt /tmp/noacp/abc123.xml --timeout 300 "Analyze this"

Advanced

See REFERENCE.md for agent config schema, session validation rules, multi-agent routing, and inline usage fallback.