workspace

harness install workspace

Operate project files and processes with the Harness's own Python control programs. The target project has its own files, dependencies and processes; importing a module in the controller does not import the target project. No coding agent is delegated to.

Install with harness install workspace, or from this checkout with harness install ./packages/workspace --link. Start a native task with harness run "Fix the failing parser and verify the change" --folder ./project. The project must already exist. There is no browser, display or screenshot dependency.

The model uses read_file, write_file, run_command, start_process, process_status, read_output and cancel_process from Python. An execution belongs to the existing tick and ends with a receipt. Foreground commands suspend that execution while the worker owns the target process; no second planner or job service is involved.

Each command starts in the requested project directory with a fresh shell/environment. Files persist; cd and export do not persist between commands. Use the project's actual interpreter (for example .venv/bin/python), never assume the controller's Python or installed dependencies are the target's. The target receives basic OS environment variables and explicit overrides, not the controller's PYTHONPATH or model API credentials. The backend is trusted local execution, with the OS user's authority. The directory bounds the file API, not arbitrary commands. Use a dedicated OS user or container around the worker if an OS security boundary is required.

File reads return a complete-file hash. Replacements must supply that hash; an observed conflict leaves the file intact. Writes replace files atomically. This is optimistic conflict detection, not a transaction with arbitrary external writers.

Commands have a wall deadline; start_process explicitly creates a task-owned server. run_command belongs to its execution and is cancelled when that execution stops. Results distinguish running, exited, cancelled, timeout and session_closed, and retain the exit code. Nonzero exits are normal results for the agent to inspect. Complete combined stdout and stderr and final receipts live in the run's artifacts; model previews are bounded and read_output can retrieve any byte range. Budget exhaustion does not erase these outputs or turn an unknown task outcome into success.

The session owns background processes and cleans them up on release. On POSIX the worker kills the process group; programs deliberately detaching into another session are outside this guarantee. Windows cancellation uses taskkill's tree operation while the parent is alive and is reported as best effort; it cannot guarantee cleanup of already detached descendants. No backend claims cancellation merely because a request was sent. Files already changed are not rolled back on cancellation.

Operation values return to the caller, while execution events stream to the run trace. The next model decision receives program output, event counts and unresolved events. Raw evidence lives under artifacts/evidence: an append-only index references immutable payloads by hash. Repeated reads share stored content. The worker reserves at most 256 MiB for evidence and process output, with 16 MiB per process and 16 concurrent processes. Exhaustion is explicit; a possibly executed action is never automatically retried. Program output has a separate 1 MiB character limit ; the model is told up to 30,000 characters of it, and of more the file it was saved to.

The package owns project selection, directory inheritance, toolchain provisioning and process release through its host provider. Set [workspace] workers = 4 in user settings to limit concurrent project workers. Install this package before using --folder; the core does not select or install a particular environment backend implicitly.

0.3.1

• The project-folder prompt says the project's instruction files open the first message, instead of asking the model to find them.

0.3.0

• What the model is given has a limit everywhere, and says so where it leaves something out. - A conversation is compacted instead of cut: when the context a call read reaches runtime.compact_at_tokens (default 150000), the model writes a summary, which replaces the conversation before its recent messages (the last 10,000 to 40,000 tokens, at least five messages). After runtime.clear_results_after_minutes (default 60) without a reply, when the provider's cache is cold, the results of all programs but the last five are cleared. Requests to Anthropic's and Qwen's models on OpenRouter mark the system prompt and the last message for the provider's cache. runtime.max_history_turns is gone (a configuration that sets it is refused): set compact_at_tokens instead. The trace records compaction; context_shortened is gone. - What a unit printed or returned is told whole up to 30,000 characters (it was cut to 8,000 and 2,000); more is saved to a file a program can read, and the model is told the file and the first 2,000 characters. output_of reads up to 30,000 characters. - Every turn tells how many nodes act in the tree of reflexes and which changed since the model was last told (at most 10), not the whole tree. reflexes() gives the nodes at the top and reflexes("name") those under a node, at most 50 at a time; a node's under is now the names of the nodes under it. - The system prompt stays the same from call to call: what an active run has learned is told with a program's result, whole when it changed. The library's skills are listed within 8,000 characters (past that by name only) and its notes within 200 lines or 25,000 characters.
• A conversation goes on until you end it. The agent's answer, a reply in plain text, ends its turn, not the conversation: the next message goes to the same conversation, which keeps its messages, the variables of its programs, its rules, its facts and the environment. What the agent left running goes on after the answer, and the end of a unit or an event starts its next turn without a message. Model calls and time are limits of a turn and begin anew with the next one; a turn that reaches one, fails or is cancelled (/cancel) ends with that reason and the conversation waits; cost is counted for the whole conversation. Every turn ends with a turn_result record. /clear is another name of /new. Sessions are kept on disk as they go (conversation.json beside the trace), and one that ended is continued in its own session id with a new kernel: harness --continue, harness --resume ID, harness run --continue | --session ID "task", harness sessions resume ID, /resume, Host.resume_session(); what lived in the old process (variables, rules, running programs) is gone, and the agent is told so. A sub-agent whose turn ended can be sent another message (send_agent) and goes on with its history. A conversation whose workspace is needed by another is parked, and its next message continues it. A run nobody talks to keeps its conversation as well: harness program CONFIG --continue EPISODE --message "..." gives the episode in that directory one more turn, in its own session, against the worker that runs. What breaks: the prompt no longer teaches <finish>; <finish> and finish() are still accepted and mean the same as a text answer. In a run without a user (a benchmark), a reply in plain text now ends the run as its answer instead of being sent back as a format error. A frontend that waited for FINISHED after an answer waits for the turn_result record instead (the state after it is IDLE, whose reason is how the turn ended); harness run "task" and the MCP server's run_task still end the session they started after its turn. A sub-agent's report has no question and no asks status: what it asks is its answer. ACP session/cancel ends the turn and keeps the conversation. A task the agent package gives (harness agent) ends with its turn, so a question it asks comes back as the task's answer. In summary.json, a conversation closed between turns keeps the status of its last turn; closed is a turn that was cut short. The evaluator's outcome is read when the conversation ends, as before, since a worker evaluates once. A kernel that dies ends the conversation; it is continued with --resume. Esc in the terminal chat still pauses.
• A run is now one model and the units it starts. Every program the model writes runs as a unit beside the others, with its own output and result: the model's turn comes back at once (with the result when the program was over within runtime.turn_grace_seconds, 2 s by default, else while it still runs), and the model may start another program, cancel one, or reply <wait> until a unit ends, a message or an event reaches it, or its time is over (runtime.longest_wait_seconds). A rule is a condition, a priority and a program: rule(begins, program, ends=..., priority=...) starts the program as a unit when its condition comes to hold; facts is a store of named values that programs and rule conditions share. A unit of higher priority takes the environment from a lower one, whose call is started again afterwards. A sub-agent that ends wakes the model that started it. What breaks: the look-ahead during a program (<assume>), watch(every=seconds), the reflex rule (reflex, remove_reflex, the named priorities) and the USER_MESSAGE event are gone; runtime.think_while_acting, model.think_while_acting and --think are still accepted and have no effect. A worker's profile says how it is driven with max_hz and step_seconds instead of clock (an old clock is still read); an environment that needs a command every period while nothing runs now needs a rule on time. A pause stops every unit and holds until the conversation is continued. The traces lose ahead, side_program, side_program_end and program_stopped and gain unit_end, wait, wait_end, rule, fact and preempted.
• A file the agent creates in a project folder gets the same permissions as one you create (usually rw-r--r--), not rw-------; a file it replaces keeps its own.

0.2.1

• Declares the environment its host gives (workspaces = ["project"]), so a new installation finds and installs this package when a task names a folder or the project environment. Requires Harness 0.81.1.

0.2.0

• Project folder is one of the environments every new conversation chooses from, and can be taken into another conversation with use_environment("project", why, folder=PATH). A project conversation takes a browser or the desktop the same way when a step must see something. Requires Harness 0.80.0.

0.1.0

• Own project binding, child inheritance, worker startup and settings through the package host provider; no computer dependency or core project fallback.
• Native project files and processes, controlled by model-written Python through the existing bounded execution lifecycle. Explicit project binding, target toolchains, conflict-checked file replacement, deadlines, cancellation and complete paginated process output.
• Trusted local execution. POSIX process-group cleanup; Windows tree cleanup is best effort. No external coding agent, browser or additional job service.