Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/adr/0348-persistent-python-repl-and-unharnessed-mode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# 0348. Persistent Stateful Python REPL (`python_repl`) and Opt-In `--unharnessed` Mode

Status: accepted 2026-11-16

## Context

One-shot `shell("python3 ...")` calls lose in-memory variables, parsed datasets, compiled helpers, and working directory state across turns, forcing models to re-read files and serialize intermediate results back to disk on every step. Meanwhile, `rlm` (ADR 0022) intentionally provides a constrained call-only script surface (`read_file`/`codedb`/`bash`/`subagent`) rather than full Python execution. At the same time, keeping the full native editing/search catalog by default preserves strict path/edit safety and minimum reliability on general software engineering tasks.

## Decision

1. **Persistent per-owner Python 3 worker (`src/python_repl.zig`, `src/python_repl_worker.py`):** Each owner (`root` or subagent worker ID) lazily spawns one persistent Python 3 child speaking newline-delimited JSON over dedicated non-inheritable (`CLOEXEC`) duplicated file descriptors (`proto_in`/`proto_out`). Before executing code, stdio fds `1`/`2` and `sys.stdout`/`sys.stderr` redirect into an unlinked per-call temporary capture file so subprocess and C-level fd writes capture without corrupting JSONL framing. The last expression statement evaluates via `ast.Expression`, binds `_`, and returns `repr()`, while POSIX `SIGALRM` + Zig `Io.Select` watchdogs bound hangs without dropping prior REPL globals on recoverable errors or `SystemExit`. Workspace switches automatically update `os.chdir` and `sys.path[0]`.
2. **Dual exposure — folded native `python_repl` + opt-in `--unharnessed` 1-tool mode:**
- **`python_repl` in normal sessions:** Appended via `python_repl.catalogExtras()` and registered in `native_fold.folded`, keeping turn-1 tool schemas and the 64-cell `tool_catalog.json` cube unchanged until loaded (`load_tool_schemas`) or called.
- **`--unharnessed` / `/unharnessed` (`src/unharnessed_mode.zig`):** Opt-in mode (`CLI > GRAFF_UNHARNESSED > .harness/settings.json`, default `false`) exposing ONLY the single `python` tool and a compact single-tool system prompt, bypassing `orchestrator_turn` handoff, with live toggle parity across CLI, REPL (`/unharnessed`), `--json` (`set_unharnessed`), and ACP (`configOptions` `id: "unharnessed"`).
3. **Uniform safety & lifecycle invariants:** Both `python_repl` and `python` are blocked by `--no-local-tools`, refused in `plan_mode` and read-only subagents, checked against `.harness/settings.json` hard policies (`tool.use`), serialized in mixed tool batches (`agent_tool_batch.isSequential`), and reset on `/clear`, `/new`, ACP `session/load`, or `reset: true`, with workers reaped on exit in `session_globals.release`.

## Consequences

- Normal `graff` sessions keep the existing turn-1 schema budget while unlocking persistent cross-turn Python state on demand via `python_repl`.
- Sessions launched with `--unharnessed` (or toggled via `/unharnessed on` / ACP) expose a clean 1-tool `python` loop with full auth, transport, approval, and trace parity.
- `--no-local-tools` continues to take precedence over unharnessed settings so host execution cannot be bypassed in embedder deployments.
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -372,6 +372,7 @@ record only when you need the evidence or the edge cases.
| [0345](0345-claude-dual-frontier-separate-quota-and-plan-ladders.md) | `anthropic` and `claude-agent` declare a 3-rung ladder with dual frontier (`opus-5-5` normal, `fable-5-2` at `xhigh`/`max`), `billing.quotaPoolFor` marks Fable as a separate plan pool across REPL (`plan*`), ACP (`separateQuota`), and quota recovery (`stepDownSeparateQuotaPool`), `chatgpt-new` mirrors Codex tiers, `xai` stays strictly `grok-4.7` or nothing, `liveLadderModel` adapts to rotated live catalogs, and cross-provider sub routing requires `billing.costFor == .plan`. |
| [0346](0346-acp-accounts-plan-windows-and-live-rate-limits.md) | `plan_usage_live` caches live HTTP/WebSocket/`claude-agent` rate limits and drives `isModelBlocked` Fable stepdown; `plan_accounts` and `plan_accounts_probe` collect redacted identity and usage windows across `/usage` and ACP `graff/accounts`, `_codegraff/usage.planWindows` streams active limits, and `initialize` advertises `_meta["codegraff/accounts"]` plus all 7 terminal `authMethods`. |
| [0347](0347-same-chat-plan-execute-baton-handoff.md) | Orchestrator Mode (`off` \| `auto` \| `on`, default `auto`) runs Phase 1 read-only planning on the root frontier seat (`exit_plan_mode`) and hands off in-place inside the same KV-cached conversation to a same-provider, same-wire executor 1 rung down (`enter_plan_mode` capped at 2 replans), integrated with `orchestration_policy` `.baton`, `.harness/settings.json`, REPL `/orchestrator`, and ACP `orchestrator` / `graff/models`. |
| [0348](0348-persistent-python-repl-and-unharnessed-mode.md) | Persistent per-owner Python 3 worker (`python_repl`, folded in `native_fold`) gives sessions cross-turn globals, `_` expression results, fd 1/2 capture, and timeout resilience without turn-1 schema overhead; opt-in `--unharnessed` / `/unharnessed` (`CLI > env > .harness/settings.json`, ACP/JSON parity) exposes only `python` with a single-tool prompt, while `--no-local-tools`, `plan_mode`, and hard policies block both. |

## When to write one

Expand Down
2 changes: 2 additions & 0 deletions evals/harness_behavior.jsonl
Original file line number Diff line number Diff line change
Expand Up @@ -181,3 +181,5 @@
{"id": "hard-policy-restricts-yolo-write", "why": "Operator hard policy is an independent restrictive gate even when ordinary approvals are bypassed.", "workspace_seed": {".harness/settings.json": "{\"policies\": [{\"action\": \"tool.use\", \"resource\": \"write_file\", \"effect\": \"deny\"}]}", "note.txt": "unchanged"}, "prompt": "Try writing to note.txt, then explain the result.", "script": [{"tool": "write_file", "arguments": {"path": "note.txt", "content": "changed"}}, {"text": "The write was blocked by hard policy."}], "assert": [{"file_equals": {"path": "note.txt", "content": "unchanged"}}, {"request_contains": {"index": 1, "text": "hard policy denied"}}, {"final_text_contains": "blocked by hard policy"}]}
{"id": "builtin-formatter-preserves-symlink-argv0", "why": "Built-in formatters resolved from PATH must keep the symlink leaf basename in argv[0] so multicall wrappers such as rustfmt -> rustup dispatch properly.", "env": {"PATH": "bin:/usr/bin:/bin", "GRAFF_NO_CODEDB_GUARD": "1"}, "workspace_seed": {".harness/settings.json": "{\"formatters\": true}", "pkg/Cargo.toml": "[package]\nname = \"pkg\"\nversion = \"0.1.0\"\n"}, "prompt": "Set up the multicall rustfmt shim and write pkg/src/lib.rs.", "script": [{"tool": "bash", "arguments": {"command": "mkdir -p bin pkg/src && printf '#!/bin/sh\\nif [ \"$(basename \"$0\")\" != \"rustfmt\" ]; then exit 2; fi\\nif [ \"$RUSTUP_AUTO_INSTALL\" != \"0\" ]; then exit 3; fi\\nfor last; do :; done\\ntr -s \" \" < \"$last\" > \"$last.tmp\" && mv \"$last.tmp\" \"$last\"\\n' > multicall && chmod +x multicall && ln -s ../multicall bin/rustfmt && echo shim-ready"}}, {"tool": "write_file", "arguments": {"path": "pkg/src/lib.rs", "content": "pub fn add() {}\n"}}, {"text": "Formatted through multicall symlink."}], "assert": [{"event": {"type": "tool_result", "name": "bash", "text": "shim-ready\n"}}, {"event": {"type": "tool_result", "name": "write_file", "is_error": false}}, {"request_contains": {"index": -1, "text": "formatter rustfmt: formatted"}}, {"file_equals": {"path": "pkg/src/lib.rs", "content": "pub fn add() {}\n"}}, {"final_text_contains": "Formatted through multicall symlink."}]}
{"id": "orchestrator-mode-json-control-and-single-seat-fallback", "scripted_only": true, "why": "set_orchestrator persists to .harness/settings.json and emits an orchestrator ack; single-seat or custom routes keep executor execution inline without exposing planning baton tools.", "controls_before_prompt": [{"type": "set_orchestrator", "mode": "on"}], "prompt": "Reply with hello.", "script": [{"text": "hello from mock"}], "assert": [{"event": {"type": "orchestrator", "ok": true, "mode": "on", "supported": false}}, {"request_count": 1}, {"request_lacks": {"index": 0, "text": "exit_plan_mode"}}, {"file_equals": {"path": ".harness/settings.json", "content": "{\"orchestrator\":\"on\"}\n"}}, {"final_text_contains": "hello from mock"}]}
{"id": "python-repl-persistent-session-state", "scripted_only": true, "why": "ADR 0348: python_repl unfolds on demand via load_tool_schemas and preserves variables and trailing _ across calls.", "prompt": "Load python_repl and compute total into answer.txt across two calls.", "script": [{"tool": "load_tool_schemas", "arguments": {"tools": ["python_repl"]}}, {"tool": "python_repl", "arguments": {"code": "nums = [10, 20, 30]\nsum(nums)"}}, {"tool": "python_repl", "arguments": {"code": "open('answer.txt', 'w').write(f'total={sum(nums)},prev={_}')\n'saved'"}}, {"text": "Saved persistent computation to answer.txt."}], "assert": [{"event": {"type": "tool_call", "name": "load_tool_schemas"}}, {"event": {"type": "tool_result", "name": "python_repl", "is_error": false}}, {"request_lacks": {"index": 0, "text": "\"name\": \"python_repl\""}}, {"request_contains": {"index": 1, "text": "\"name\": \"python_repl\""}}, {"request_contains": {"index": -1, "text": "'saved'"}}, {"file_equals": {"path": "answer.txt", "content": "total=60,prev=60"}}, {"final_text_contains": "answer.txt"}]}
{"id": "unharnessed-mode-single-tool-and-json-control", "scripted_only": true, "why": "ADR 0348: set_unharnessed persists to .harness/settings.json, switches to single-tool python catalog without file/shell tools, and preserves persistent REPL state.", "controls_before_prompt": [{"type": "set_unharnessed", "on": true}], "prompt": "Compute 7 * 9 across two persistent python calls and write out.txt.", "script": [{"tool": "python", "arguments": {"code": "val = 7 * 9\nval"}}, {"tool": "python", "arguments": {"code": "open('out.txt', 'w').write(f'{val}:{_}')\n'done'"}}, {"text": "Completed in single-tool python mode."}], "assert": [{"event": {"type": "unharnessed", "ok": true, "on": true}}, {"request_contains": {"index": 0, "text": "\"name\": \"python\""}}, {"request_lacks": {"index": 0, "text": "\"name\": \"read_file\""}}, {"request_lacks": {"index": 0, "text": "\"name\": \"edit_file\""}}, {"request_lacks": {"index": 0, "text": "\"name\": \"shell\""}}, {"file_equals": {"path": ".harness/settings.json", "content": "{\"unharnessed\":true}\n"}}, {"file_equals": {"path": "out.txt", "content": "63:63"}}, {"final_text_contains": "Completed in single-tool python mode."}]}
4 changes: 2 additions & 2 deletions examples/edge-worker/src/remote.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
export const HARNESS_VERSION = "0.13";

export type ModelName = "MiniMax-M2.5" | "MiniMax-M2.7" | "MiniMax-M3" | "accounts/fireworks/models/deepseek-v4-flash" | "accounts/fireworks/models/deepseek-v4-pro" | "accounts/fireworks/models/glm-5p2" | "accounts/fireworks/models/gpt-oss-120b" | "accounts/fireworks/models/kimi-k2p6" | "accounts/fireworks/models/kimi-k2p7-code" | "accounts/fireworks/models/minimax-m3" | "accounts/fireworks/models/qwen3p7-plus" | "alibaba/qwen3.8-27b" | "anthropic/claude-sonnet-4.6" | "claude-fable-5" | "claude-fable-5-1" | "claude-fable-5-2" | "claude-haiku-5-5" | "claude-opus-4-5" | "claude-opus-4-6" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-opus-4.8" | "claude-opus-5" | "claude-opus-5-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4.6" | "claude-sonnet-5" | "claude-sonnet-5-5" | "deepseek-chat" | "deepseek-reasoner" | "deepseek-v4-flash" | "deepseek-v4-pro" | "flint" | "fugu" | "fugu-ultra" | "fugu-ultra-20260615" | "gemini-3-flash-preview" | "gemini-3.1-flash-lite" | "gemini-3.1-pro-preview" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3.6-flash" | "gemini-3.7-flash" | "gemini-3.8-flash" | "gemini-4-argon" | "gemma-4-26b-a4b-it" | "gemma-4-31b" | "gemma-4-31b-it" | "glm-4.5" | "glm-4.7" | "glm-5" | "glm-5-turbo" | "glm-5.2" | "glm-5.3" | "glm-5.3-flash" | "glm-5v-turbo" | "gpt-5-codex" | "gpt-5.2" | "gpt-5.3-codex-spark" | "gpt-5.4" | "gpt-5.4-mini" | "gpt-5.4-pro" | "gpt-5.5" | "gpt-5.6" | "gpt-5.6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-6-astra" | "gpt-6-luna" | "gpt-6-sol" | "gpt-6.1-sol" | "gpt-oss-120b" | "grok-4.3" | "grok-4.6" | "grok-4.7" | "grok-build" | "k3" | "k3-256k" | "k3.1-pro" | "k3.1-pro-highspeed" | "kilo-auto/small" | "kimi-for-coding" | "kimi-for-coding-highspeed" | "kimi-k2.6" | "kimi-k2.7-code" | "kimi-k3" | "kimi-k3.1-pro" | "kimi-k3.1-pro-highspeed" | "kimi-latest" | "lmstudio" | "mimo-v2-flash" | "mimo-v2.5" | "mimo-v2.5-pro" | "mimo-v2.5-pro-ultraspeed" | "mimo-v2.6-flash" | "mimo-v2.6-pro" | "mimo-v2.6-pro-ultraspeed" | "minimax-m3" | "mistral-medium-latest" | "mlx-community/Qwen3.6-27B-OptiQ-4bit" | "muse-spark-1.2" | "muse-spark-1.2-contributor" | "omlx" | "openai/gpt-oss-120b" | (string & {});
export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "yield_turn" | "imagegen" | "lsp" | "rlm";
export type ToolName = "shell" | "read_file" | "edit_file" | "write_file" | "webfetch" | "skill" | "codedb" | "read_tool_result" | "render_html" | "todo_write" | "todo_read" | "eval" | "note_constraint" | "ask_user" | "attempt_completion" | "load_tool_schemas" | "mcp_search_tools" | "mcp_select_tool" | "clock_sleep" | "subagent" | "workflow" | "agent_output" | "agent_message" | "subagent_resume" | "learn_candidate" | "peer_message" | "workspace" | "yield_turn" | "imagegen" | "lsp" | "python_repl" | "rlm";
export type ProviderId = "anthropic" | "codegraff" | "deepseek" | "openai" | "google" | "minimax" | "xiaomi" | "kilo" | "groq" | "cerebras" | "mistral" | "kimi" | "moonshot" | "xai" | "zai" | "meta" | "vercel" | "openrouter" | "fugu" | "fireworks" | "mlx" | "lmstudio" | "omlx" | "chatgpt-new" | "codex" | "claude-agent";

/** Events streamed by the bridge (same `--json` contract as the stdio SDK).
Expand Down Expand Up @@ -529,7 +529,7 @@ export async function* runAgentRemote(opts: RunAgentRemoteOptions): AsyncGenerat
}

export const MODELS: ModelName[] = ["MiniMax-M2.5", "MiniMax-M2.7", "MiniMax-M3", "accounts/fireworks/models/deepseek-v4-flash", "accounts/fireworks/models/deepseek-v4-pro", "accounts/fireworks/models/glm-5p2", "accounts/fireworks/models/gpt-oss-120b", "accounts/fireworks/models/kimi-k2p6", "accounts/fireworks/models/kimi-k2p7-code", "accounts/fireworks/models/minimax-m3", "accounts/fireworks/models/qwen3p7-plus", "alibaba/qwen3.8-27b", "anthropic/claude-sonnet-4.6", "claude-fable-5", "claude-fable-5-1", "claude-fable-5-2", "claude-haiku-5-5", "claude-opus-4-5", "claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8", "claude-opus-4.8", "claude-opus-5", "claude-opus-5-5", "claude-sonnet-4-5", "claude-sonnet-4-6", "claude-sonnet-4.6", "claude-sonnet-5", "claude-sonnet-5-5", "deepseek-chat", "deepseek-reasoner", "deepseek-v4-flash", "deepseek-v4-pro", "flint", "fugu", "fugu-ultra", "fugu-ultra-20260615", "gemini-3-flash-preview", "gemini-3.1-flash-lite", "gemini-3.1-pro-preview", "gemini-3.5-flash", "gemini-3.5-flash-lite", "gemini-3.6-flash", "gemini-3.7-flash", "gemini-3.8-flash", "gemini-4-argon", "gemma-4-26b-a4b-it", "gemma-4-31b", "gemma-4-31b-it", "glm-4.5", "glm-4.7", "glm-5", "glm-5-turbo", "glm-5.2", "glm-5.3", "glm-5.3-flash", "glm-5v-turbo", "gpt-5-codex", "gpt-5.2", "gpt-5.3-codex-spark", "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-pro", "gpt-5.5", "gpt-5.6", "gpt-5.6-luna", "gpt-5.6-sol", "gpt-5.6-terra", "gpt-6-astra", "gpt-6-luna", "gpt-6-sol", "gpt-6.1-sol", "gpt-oss-120b", "grok-4.3", "grok-4.6", "grok-4.7", "grok-build", "k3", "k3-256k", "k3.1-pro", "k3.1-pro-highspeed", "kilo-auto/small", "kimi-for-coding", "kimi-for-coding-highspeed", "kimi-k2.6", "kimi-k2.7-code", "kimi-k3", "kimi-k3.1-pro", "kimi-k3.1-pro-highspeed", "kimi-latest", "lmstudio", "mimo-v2-flash", "mimo-v2.5", "mimo-v2.5-pro", "mimo-v2.5-pro-ultraspeed", "mimo-v2.6-flash", "mimo-v2.6-pro", "mimo-v2.6-pro-ultraspeed", "minimax-m3", "mistral-medium-latest", "mlx-community/Qwen3.6-27B-OptiQ-4bit", "muse-spark-1.2", "muse-spark-1.2-contributor", "omlx", "openai/gpt-oss-120b"];
export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "yield_turn", "imagegen", "lsp", "rlm"];
export const TOOLS: ToolName[] = ["shell", "read_file", "edit_file", "write_file", "webfetch", "skill", "codedb", "read_tool_result", "render_html", "todo_write", "todo_read", "eval", "note_constraint", "ask_user", "attempt_completion", "load_tool_schemas", "mcp_search_tools", "mcp_select_tool", "clock_sleep", "subagent", "workflow", "agent_output", "agent_message", "subagent_resume", "learn_candidate", "peer_message", "workspace", "yield_turn", "imagegen", "lsp", "python_repl", "rlm"];

// ── Serverless / In-Memory Agent Runtime (Edge & Worker safe) ─────────────

Expand Down
2 changes: 1 addition & 1 deletion scripts/test-acp-effort-config.py
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

def option(response):
options = response["result"]["configOptions"]
assert len(options) == 1, options
assert [o["id"] for o in options] == ["thought_level", "unharnessed"], options
selected = options[0]
assert selected["id"] == selected["category"] == "thought_level", selected
assert selected["type"] == "select", selected
Expand Down
4 changes: 2 additions & 2 deletions scripts/test-acp-http2.py
Original file line number Diff line number Diff line change
Expand Up @@ -173,12 +173,12 @@ def expected_text(number):
created, _ = call('session/new', {'cwd': str(case), 'mcpServers': []}, 2)
sid = created['result']['sessionId']
initial = created['result']['configOptions']
assert len(initial) == 1 and initial[0]['category'] == 'thought_level', initial
assert [o['id'] for o in initial] == ['thought_level', 'unharnessed'] and initial[0]['category'] == 'thought_level', initial
assert initial[0]['currentValue'] == 'medium', initial
selected, _ = call('session/set_config_option', {
'sessionId': sid, 'configId': 'thought_level', 'value': 'high'}, 8)
options = selected['result']['configOptions']
assert len(options) == 1 and options[0]['currentValue'] == 'high', selected
assert [o['id'] for o in options] == ['thought_level', 'unharnessed'] and options[0]['currentValue'] == 'high', selected
assert not [r for r in (json.loads(line) for line in log.read_text().splitlines())
if r['event'] == 'request'], 'Effort selection made a network request'
for number in range(1, 3 if success else 2):
Expand Down
2 changes: 1 addition & 1 deletion scripts/test-acp-session-load.py
Original file line number Diff line number Diff line change
Expand Up @@ -351,7 +351,7 @@ def run(binary):
assert selected["model"] == "alibaba/qwen3.8-27b", selected
created_config = created["configOptions"]
loaded_config = loaded["result"]["configOptions"]
assert len(created_config) == len(loaded_config) == 1, (created, loaded)
assert [o["id"] for o in created_config] == [o["id"] for o in loaded_config] == ["thought_level", "unharnessed"], (created, loaded)
assert created_config[0]["category"] == loaded_config[0]["category"] == "thought_level"
assert created_config[0]["currentValue"] == "high", created_config
assert loaded_config[0]["currentValue"] == "low", loaded_config
Expand Down
Loading
Loading