# Longhand: browser delivery and next steps

## Goal

The agent investigates and prepares code changes for the user to understand
and apply. The main handoff appears on a local page with easy-to-copy code;
the terminal shows a short link. Mechanical work is a separate exception
that still needs a clear policy.

## Browser delivery: first version

Pi 0.87.0 supports custom tools and session events. `pi-web-access` shows
the pattern of a temporary HTTP server bound to `127.0.0.1`, a tokenized URL,
and a browser review page.

Current flow:

1. `longhand_publish` receives a structured proposal: diagnosis, location,
   complete code to paste, and verification steps.
2. The tool stores the proposal outside the project and serves a local page
   at `http://localhost:<port>/?session=<token>`.
3. The tool result shows the URL in the terminal. In interactive mode, that
   result ends the turn without another model call. In other modes, the agent
   replies with the URL in a short message.
4. The page shows the explanation, file, location, code with a **Copy code**
   button, and verification steps. **Makes sense**, **Request a change**, and
   a comment field send feedback to Pi. Opening or copying the page never
   changes project files.
5. Session shutdown closes the server. Pages are held only in memory, so
   links stop working when Pi exits, including after `--print`. Persistence
   can be added if users need it.

Publishing through a tool avoids capturing the final response with
`message_end`: Pi may already have streamed that response into the terminal.
The agent prepares the page before producing a short final response. The
tool stays active in longhand mode. If publishing fails, the agent should
give the complete handoff in chat so the code is not lost.

The first version supports one change per page, exact placement, a complete
code block without line numbers or diff markers, a copy button, and a clear
statement that the page has not applied the code. Its server follows the
`pi-web-access` pattern without depending on that package.

References:

- Pi 0.87.0 local `docs/extensions.md`: `registerTool`, `message_end`,
  `agent_settled`, and `session_shutdown`.
- `pi-web-access`: <https://github.com/nicobailon/pi-web-access>, its Curator
  and remote access documentation, `curator-server.ts`, and `curator-page.ts`.

## Token use and cache

Two short guidelines attached to `longhand_publish` are present only while
the tool is active. The extension no longer replaces the complete
`systemPrompt` on every turn. Pi can record a prompt change instead of
forcing a complete replacement. Toggling the tool set can still cause a
cache miss, depending on the provider and model.

Publishing the page does not call another model. The agent generates the
proposal once in the tool arguments; the server turns those values into
HTML. In interactive mode, `terminate: true` avoids a call that would only
repeat the URL. The six-field schema adds some input overhead, and JSON
serialization adds some output overhead. Measure real usage before claiming
net savings across providers.

## Remaining work

- Define which tasks count as mechanical and how to authorize execution with
  limited scope, without making users copy repetitive edits by hand.
- Align the prompt with the guard's actual behavior: formatters and package
  managers can write files after confirmation.
- Treat `guard.ts` as protection against common mistakes, not shell
  isolation. Decide whether the mode needs real isolation.
- Limit `.longhand.json` to read-only tools or require explicit permission
  before enabling tools that write.
- After the user applies code, let the agent inspect the diff and run checks
  without claiming that it made the change.
- Expand the public README with the project's motivation and evidence.