@xingular/harness 1.3.1-unstable.8 → 1.4.0-unstable

package/CHANGELOG.md

@@ -2,6 +2,123 @@
 
 ## Unreleased
 
+- **A large, content-block reporting prompt (ADR-0073).**
+  - The `reporting` section in `src/prompt/reporting.ts` is about 15.8k characters: outcome first,
+    required what-changed / how-to-test / what-to-do-next blocks for a change, optional beyond,
+    departures, unverified and open-question blocks, five worked examples and an anti-pattern table.
+  - Headings are the model's choice; the three fixed headings from ADR-0068 are gone.
+  - `REPORTING_BUDGET` rises to 18,000, and the section is never cut.
+  - The peer study is `docs/study/STUDY-0006-reporting-prompts.md`.
+- **Skill installation guidance and package skill layouts.**
+  - The release-owned `plugin-authoring` skill now says where a skill is installed (a project's
+    `.pi/skills` and `.agents/skills`, the user's `~/.agents/skills`, the shared state folder), to
+    copy a whole skill folder, and that `.claude/skills` is never read. It also says which installs
+    only a person commits, and that `plugin_propose` is not an install route.
+  - `plugins.install` refuses a GitHub or GitLab `tree`/`blob` page address with the repository
+    address and the skill routes, instead of a raw git error.
+  - A package's foreign plugin manifest (`plugin.json`, `.claude-plugin/plugin.json`,
+    `.codex-plugin/plugin.json`) may declare `skills`; those folders load as package skills, under
+    the package's switch and filter.
+
+- **Codex's prompts and `/goal`; the completion check moves behind `/goal` (ADR-0072).**
+  - **Ordinary replies.** No model-judged check runs on them. The todo gate stays and says the list
+    is progress, not the limit of the work; `TODO_GUIDANCE` now says the request is the scope.
+  - **Prompt.** A person's own session reads Codex's autonomy and persistence, when-to-ask,
+    steering and compaction, and writing-style rules as separate sections, and a longer reporting
+    section: unfinished work says so on the first line, with the reason and the next step.
+    `ask_user` is never used to ask permission, and no answer means continue.
+  - **Failures from outside the session.** A test or error that does not come from the session's
+    work is reported with its command and output, not fixed, unless the person asks. It stays off
+    the todo list, and it is a reason to stop that the autonomy rules name.
+  - **`/goal <objective>`.** A long run the person starts. Codex's `get_goal` and `update_goal`,
+    continuation, round-cap and edit prompts, `blocked` after the same blocker on three turns, and
+    brakes for idle, failing and erroring rounds. `/goal edit|pause|resume|clear`, a footer label,
+    Esc pauses. Caps: 30 rounds or 8 hours (`--rounds`, `--hours`).
+  - **A completion claim is checked** once by the same model at low effort with a fresh context.
+    `sessions.run` takes `goal`; `run.json` records `goalMode`.
+  - **Fixed.** The check sends a session id, so opencode-go no longer answers 400 `MissingSessionID`.
+  - Adapted from OpenAI Codex (Apache-2.0); see `NOTICE.md`.
+- **A completion check replaces `finish` (ADR-0071; the every-reply check is superseded by ADR-0072).**
+  - **The check.** When a reply that did work ends with its todo list closed or absent, the run's
+    own model, at low effort and with a fresh context, judges the person's request against what the
+    reply did: `done`, `continue` (the reply is sent back with the reason and next step), or
+    `needs_person`. The request is the goal; there is no `/goal` command.
+  - **Shared cap.** It shares the stop gate's cap of three nudges per reply and its no-progress rule.
+  - **Usage and failure.** Its request counts in the run's usage, and any failure leaves the reply
+    as it was.
+  - **`finish` is removed.** A live GPT 6 Luna run used `needs_decision` after 23 seconds to ask
+    something the handoff already answered. Only the check can now decide that the person is needed.
+  - **Prompt.** The `role` paragraph names which decisions are the agent's own, says a document the
+    request points to is the request, and says a question the request or files already answer is not
+    a question for the person. Its budget rises from 1,500 to 2,200 characters, so it fits uncut with
+    the subagent paragraph.
+  - **Kill switches.** `XINGULAR_STOP_GATE=off` and `XINGULAR_COMPLETION_CHECK=off` at launch switch a
+    layer off, for experiments.
+- **The model is told it has `edit` and `write`.** Pi's `createEditTool` and `createWriteTool` drop
+  the definition's prompt line and guidelines, and Pi lists only tools with a prompt line, so every
+  terminal and headless run's system prompt named only `read` and `bash`. Models edited files
+  through shell scripts instead: one 2-hour terminal run made 156 script edits (14 failed) and no
+  `edit` call. `createWorkspaceFileTools` now restores the prompt line and guidelines, as Pi's own
+  `createBashTool` does, for both the terminal and the runner. The stable prefix changes once.
+- **A plan no longer leaks its tools into normal mode.** A terminal plan request narrows the active
+  tools, and Pi records the restored normal set only with the next request. A rebuild before then
+  (a new runtime, resume, switch, fork or tree navigation) replayed the plan set, so normal work ran
+  without `edit`, `write`, browser and connected-app tools. One recorded session implemented a whole
+  plan that way. The terminal now marks each plan request in the session and restores the normal
+  set after any rebuild.
+- **Terminal replies continue across work slices (ADR-0070).** A terminal reply that reaches its
+  320-call or 60-minute budget after doing work now continues in place as the next slice, with a
+  checkpoint and a notice, up to 8 slices, instead of waiting for "continue" and re-sending the
+  whole context uncached. Fruitless, blocked, failed, aborted and plan slices still stop.
+  `XINGULAR_WORK_SLICE` also accepts key=value pairs such as `maxToolCalls=15,maxSlices=3`.
+- **One copy of each credential: no more `invalid_grant` from terminals.** A terminal's Pi kept the
+  account's tokens in `auth.json` under its own lock while the host, its subagents and usage probes
+  refreshed the same token in the Keychain under another, and `terminalEnd` copied the file back
+  over whatever the Keychain held. OpenAI rotates refresh tokens, so whichever side refreshed second
+  failed with `invalid_grant` and the account needed a new sign-in. A terminal now reads and refreshes
+  through the host store (`accounts.credentials.*`, INV-ACC-5), holding its lock for the refresh. An
+  `auth.json` left by an older terminal is folded in, newest token first.
+- **A stalled terminal reply is recorded as `stalled`.** Pi's abort reports back through
+  `terminal.interrupt` like a person's Esc, which closed the run as `user_abort` before the reply
+  settled as `stalled`; one silent 15-minute hang was recorded as the person's abort. The interrupt
+  now carries the stall. An interrupt also ends a settling reply's wait for its subagents.
+
+- **A reply can no longer quietly stop with work open (ADR-0069).**
+  - **Stop gate.** In attended top-level runs, terminal included, a reply that ends while its todo
+    list has open items is sent back to the model, naming the items, up to three times per reply,
+    and never after a nudge that produced no work.
+  - **`finish`.** Added here as the one explicit way to stop with work open; removed again by ADR-0071
+    above.
+  - **Honest stop codes.** Such a reply settles `interrupted` with the new stop codes `needs_person`
+    or `unfinished`, never `completed`, with a checkpoint the harness writes from the todo list,
+    files and checks.
+  - **`checkpoint_write` is removed.** A run used it as a sign-off and stopped with work open. At a
+    work-slice budget the harness now writes the checkpoint itself.
+  - **One budget per reply.** The work-slice budget now covers the whole reply: Pi's own
+    continuations (nudges, delivered subagent results, plan repair) no longer reset it.
+  - **Prompt wording.** The texts that read as permission to stop were rewritten: the todo guidance's
+    "final update before your final reply", and `## What would make this complete` "when the run
+    could be more complete".
+  - **Subagents.** `spawn_subagent` now returns the child's tools, and the read-only profiles say up
+    front when a brief needs a tool they lack.
+  - **Hosts.** Accept the two new stop codes and offer Continue for them.
+  - **Restart required.** A live terminal session keeps the code it started with, so restart it to
+    get the gate.
+- Do the job the request implies, and report it apart from the request. A standard session's role
+  paragraph now sets the scope of the work — the obvious adjacent step, what the work itself exposes,
+  the check it needs, inside the working folder and away from what a person must decide (a deploy, a
+  secret, remote data, money), without asking first inside those bounds — and the reporting guidance
+  requires two headings when they apply: `## Beyond what you asked` and
+  `## What would make this complete` (ADR-0068). The reporting budget rises from 2,000 to 2,400
+  characters so both fit uncut. All of it is stable-prefix text, so the cached prefix changes once
+  per session.
+- Say in the prompt when a reply may end. The standard session's role paragraph, the opening of the
+  reporting guidance and the todo guidance now say that an open todo item, a passing check or a
+  partial result is not a reason to end the turn, and name the reasons that are: the request is done,
+  the work-slice guard hands the reply back, a person's decision is needed, or the person interrupts.
+  ADR-0069 below now enforces it in the runner. A sweep of 822 runs in seven days found 207 that ended with work left
+  (137 within 30 tool calls, median 17, and 191 with no checkpoint), which is what the wording is
+  for. All three texts are in the stable prefix, so this changes the cached prefix once.
 - Reword the final-reply guidance so the outcome leads and structure follows what the answer needs. The
   reporting guidance is part of every request's stable prefix, so this changes the cached prefix.
 - Keep the provider cache working after a compaction (ADR-0067). The compaction checkpoint now arms only
@@ -10,11 +127,11 @@
   request plus new items, so Codex WebSocket continuation and prefix caching apply. Before, every later
   turn of a compacted session resent its whole context: one measured session fell from 94–99% to
   18–24% cache hits after its first compaction.
-- Flag a low prompt-cache hit rate in the terminal's composer status bar. `R<percentage>%` now covers the
-  last 10 model responses instead of the whole session (`recentCacheUsage`, `CACHE_HIT_WINDOW`), and
-  gets a yellow `⚠` below 70 percent and a red one below 40 percent. Each drop to a worse level posts
-  one transcript notice. A window of one response, or one with no cache reads or writes, is not judged
-  (`cacheHitLevel`, `CACHE_HIT_WARNING_PERCENT`, `CACHE_HIT_CRITICAL_PERCENT`).
+- Flag a low prompt-cache hit rate in the terminal's composer status bar. `R<percentage>%` covers the last
+  10 model responses instead of the whole session (`recentCacheUsage`, `CACHE_HIT_WINDOW`), and the rate
+  gets a yellow `⚠` below 70 percent and a red one below 40 percent. The warning stays in the status bar;
+  no cache-hit notice is added to the transcript. A window of one response, or one with no cache reads or
+  writes, is not judged (`cacheHitLevel`, `CACHE_HIT_WARNING_PERCENT`, `CACHE_HIT_CRITICAL_PERCENT`).
 
 - Refine a variant from the terminal and keep checkpoints of it (PROP-0052, ADR-0065, ADR-0066).
   `/refine [what to look at]` replays the latest request typed in this chat from a snapshot of the

package/NOTICE.md

@@ -58,3 +58,29 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
+
+## OpenAI Codex
+
+The standard session prompt (`src/prompt/standard.ts`: autonomy and persistence, when to ask the
+person, steering and compaction, writing style), the final-reply rules in `REPORTING_GUIDANCE`
+(`src/prompt/compile.ts`), the `/goal` prompts and tool descriptions (`src/sessions/goalPrompts.ts`,
+`src/sessions/goal.ts`), the goal brakes and status text, and the `/goal` command
+(`src/terminal/tui/goalCommand.ts`) adapt text and design from OpenAI Codex, mainly:
+
+- `codex-rs/models-manager/models.json` (`instructions_template` of `gpt-6.1-sol` and `gpt-6-luna`);
+- `codex-rs/ext/goal/templates/goals/{continuation,budget_limit,objective_updated}.md`;
+- `codex-rs/ext/goal/src/{spec,tool,accounting,runtime,api}.rs`;
+- `codex-rs/tui/src/{goal_display,slash_dispatch,goal_menu}.rs`;
+- `codex-rs/collaboration-mode-templates/templates/default.md` (the `ask_user` rule).
+
+Upstream: https://github.com/openai/codex (OpenAI Codex, Copyright 2025 OpenAI)
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use these files except
+in compliance with the License. You may obtain a copy of the License at
+https://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in
+writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Changes from upstream: ported from
+Rust to TypeScript for Pi; text about Codex's own channels and tools (commentary channel,
+`apply_patch`, `functions.exec`, apps, plugins, visualizations) left out; the goal's token budget
+became rounds and hours; `update_plan` became `todo_write`; completing a goal is a claim that the
+harness checks; the model cannot create a goal.

package/builtin/skills/plugin-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plugin-authoring
-description: Use when designing, building, testing, or packaging a Harness or Pi plugin, extension, skill, or terminal interaction.
+description: Use when designing, building, testing, packaging, or installing a Harness or Pi plugin, extension, skill, or terminal interaction, including from a pasted folder or repository address.
 ---
 
 # Plugin authoring
@@ -12,6 +12,25 @@ description: Use when designing, building, testing, or packaging a Harness or Pi
 5. For a TUI audit, examine information hierarchy, layout, navigation, keyboard and focus, states, errors, accessibility and narrow and wide terminals. Study source and published screenshots as available; record which claims each source supports. Capture terminal images only with an available, authorized capture mechanism. A PTY text capture is not a screenshot; explicitly report unavailable visual evidence.
 6. Test registration, behavior, failure and cancellation paths, non-interactive fallback, and trust/permission boundaries. Run relevant checks. Use `plugin_propose` with a name, description and complete text files (omit `package.json`) to submit the package for person-controlled review. It does not install, enable or trust the plugin. Report the proposal ID, evidence and checks actually performed.
 
+## Installing an existing skill or plugin
+
+A skill is a folder with a `SKILL.md`. Copy the whole folder, never only the `SKILL.md`, into a scope a session reads:
+
+| Scope | Folder | Who writes it |
+|---|---|---|
+| This project | `<repo>/.agents/skills/<name>/` or `<repo>/.pi/skills/<name>/` | you, as project files |
+| Every project of this operating-system user | `~/.agents/skills/<name>/` | you, but it is outside the workspace, so the write asks the person |
+| Every account of this harness | `<state>/accounts/_shared/pi/skills/<name>/` | a person, when they want one shared copy |
+| Variant, library, package, Hub | `skills/<name>/SKILL.md` | only a person commits these |
+
+- Keep the folder name and the frontmatter `name` equal, and copy `reference/`, `scripts/` and every file the `SKILL.md` links to. Its relative references resolve against the skill folder.
+- For a pasted folder or repository address, clone it into a temporary folder inside the workspace, find `<name>/SKILL.md`, and copy that folder whole. A `tree` or `blob` page address is not a package address: install the repository itself, or copy the skill folder as above. Never write into `.claude/skills`; this harness does not read it.
+- A skill installed this way is available in the next session, not this one; say so.
+- A variant holds `SKILL.md` and flat `scripts/` files only, so a skill with a `reference/` folder stays in the scopes above.
+- `plugin_propose` is for a package you write. Do not propose someone else's skill as a way to install it: a proposal carries text only, is capped at 1 MiB, and becomes a local copy with no update path.
+
+When the person asks for a variant, library, Hub or package install, name the exact step (`/skills`, `/components`, `/hub`, `/plugins`) and the source, and leave the commit to them.
+
 ## Terminal example
 
 For a small interactive command, prefer a built-in UI over a custom renderer: