Skip to content

Inbox: code files as attachments, and project_path on the plannotator_inbox tool - #1826

Merged
backnotprop merged 2 commits into
mainfrom
fix/inbox-code-attachments-project-path
Oct 10, 2026
Merged

backnotprop merged 2 commits into
mainfrom
fix/inbox-code-attachments-project-path

Conversation

@backnotprop

@backnotprop backnotprop commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

Two fixes to obvious Inbox attachment problems. Out of scope, because each needs a decision: inline images, a lightbox, PDFs, a size cap, Show in Finder, and attaching any file type.

1. Code and script files as attachments (kind code)

recordInboxAttachments refused every file outside annotate's annotatable set, so an agent could not attach the script it ran (.ts, .mjs, .sh, .py, .swift, ...).

  • Accepted set. The set comes from the existing code-file list, CODE_FILE_REGEX in packages/core/code-file.ts. Annotate's code-file links already use it. I widened that list by .mjs, .cjs, .mts and .cts ([cm]?[jt]s|[jt]sx). As a side effect, markdown links to those files now count as code-file links in plan review and annotate too. The extensionless names come from the same list: Makefile, Dockerfile, Rakefile, Gemfile, Procfile, Vagrantfile, Brewfile, Justfile. A name that both sets know (.json, .yaml, .toml, .ini, .xml) keeps the kind text.

  • Refusals. Every existing refusal still applies:

    • a path outside the project root
    • a path that is not a regular file
    • .env, by the named path and by its target (a load.sh symlink to .env is refused). New: any other .env. name outside the annotatable doc set is refused too, so .env.ts and .env.local.sh cannot slip in as code; .env.example stays accepted
    • every file is checked before anything is written

    New: a code file whose bytes are not UTF-8, or contain a NUL byte, is refused with validation_error: attachments[i]: <name>: not UTF-8 text (binary or another encoding).. This check uses isInboxTextBytes in core and applies to code files only, so text, markdown and HTML attachments behave exactly as before.

  • Rendering. A code file renders as one code block, highlighted by Plannotator's existing Shiki fence highlighting:

    • codeDocumentBlocks builds the block. It never uses the markdown pipeline, so a # comment in shell or Python does not become a heading.
    • Highlighting stops at CODE_HIGHLIGHT_MAX_CHARS (100,000 characters). Shiki makes one synchronous pass over the file, and a large file froze the window (measured: 300 KB of JS took 4 s, a 1.6 MB minified bundle 163 s). A larger file renders as one plain text node.
    • codeLanguageOf picks the language: the file's extension, with a few names mapped (Makefile → make, .h → c, ...). A grammar Shiki does not know stays plain text.
  • Read-only. You cannot comment on a code file. The text viewer's selection annotation does not work on a code block: the only option would be a whole-block comment, which would quote the entire file into the reply. So:

    • the window shows no toolstrip and passes readOnly to the Viewer;
    • the phone surface (SurfaceDocument) is read-only for code too;
    • store.saveAnnotation refuses an annotation on a code attachment with 422 validation_error.
  • Serving. Unchanged: by id only, text/plain, CSP sandbox, nosniff. The sent-version blob and "changed since sent" work as for every other kind.

  • Labels and agent docs.

    • The tile reads "Code (.sh)", or "Code (Makefile)" for a name without an extension.
    • The send_message attachments description lists source code and scripts.
    • In the plannotator inbox --help guide, the attachments line names example code files. Its test checks each one against the Inbox's own name rule and kind.
  • iPhone contract. adr/implementation/inbox-mobile.md does not list attachment kinds. It says only that "every attachment kind is text", which still holds. code is an additive kind: the app (now in the Workspaces repo) should show any kind it does not know as text. I did not edit the contract doc.

2. Optional project_path on the plannotator_inbox tool

Every connection filled project_path with the session's working folder and kept the field out of the schema. An agent working in a subfolder that is not a git repo (a meeting-notes folder, for example) therefore filed threads under that folder, and relative attachment paths resolved against it.

  • Schema. The shared contract (packages/shared/inbox/connection.ts) now offers an optional project_path in the agent's schema, described as "The repository or folder this is about; defaults to your working folder." The other filled fields (agent_session, agent_host, agent_name) stay hidden. The mod's byte-for-byte copy (apps/hook/hooks/mod/inbox-contract.ts) is updated, and inbox-contract.test.ts passes.

  • Shape check. inboxToolCall refuses a value that is not a string, is empty, contains a control character or line break, or is longer than 4096 characters. It returns a valid value as projectPath; arguments still holds the working folder.

  • Resolution. Each connection resolves the path against the working folder (an absolute path is used as given) to an existing folder's real path, then passes that path in place of the cwd:

    • Pi and OpenCode: inboxProjectDir in agent-link.ts.
    • The Claude Code mod: INBOX_PROJECT_DIR_SCRIPT, which runs cd with CDPATH= and ./ before a relative name, then pwd -P.

    A path that is not an existing folder is refused before the Inbox is reached or started. Without project_path, behavior is unchanged.

  • Server side. The Inbox still resolves project_path to the git toplevel or the folder. Relative attachments now resolve against the folder the agent named, because the server already uses an absolute project_path as the base.

  • No new exposure. Any MCP client could already pass any project_path to /mcp.

  • Version skew. None: project_path is an existing MCP argument on every Inbox that has the tool, so an older Inbox takes it as is. The tool list is part of the prompt prefix, so the new schema applies from the next session only, as documented.

  • Docs. The help guide's line about filled fields now says an agent can pass project_path to override the working folder.

Docs

  • AGENTS.md: the Inbox "Attachments and annotation" section (the code kind, the binary refusal, the read-only viewer), "Agent connections" (the optional project_path) and the mod's Inbox paragraph.
  • apps/marketing/src/content/docs/reference/inbox.md: one line on file types, one line on project_path.

Tests

  • packages/core/inbox-attachments.test.ts (new): kinds, refusals, the label, isInboxTextBytes. code-file.test.ts adds .mjs, .cjs, .mts and .cts.
  • packages/shared/inbox/attachments.test.ts (new): .sh, .ts, .swift, .mjs and Makefile are recorded as code with their blobs. Binary content (ELF bytes, Latin-1 bytes) is refused and no blob is written. .env is refused by name and through a symlink with a code name. A path outside the project is refused.
  • packages/server/inbox-attachments.test.ts: a script is served with text/plain, sandbox and nosniff, its view carries the text, and an annotation on it gets 422. Binary content gets validation_error over MCP.
  • packages/inbox/codeAttachment.test.tsx (new DOM test, added to the DOM allowlist in test.yml): the pane renders one language-sh code block with no heading and no toolstrip; the tile reads "Code (.sh)".
  • packages/shared/inbox/connection.test.ts (new): project_path is in the schema and optional while the other filled fields stay hidden; the working folder is still filled without it; malformed values are refused.
  • packages/server/inbox-agent-project-path.test.ts (new): the Pi/OpenCode connection against a real in-process Inbox.
    • A relative or absolute project_path files the thread under that project, and relative attachments resolve against it.
    • Without it, the working folder is used.
    • A bad path is refused while the Inbox is stopped, and its start command never runs.
  • apps/hook/hooks/mod/inbox.test.ts: the same pass-through and refusal through the mod against a real Inbox. After the refusal, the registry still names the dead Inbox, so nothing started it.
  • Updated for the new optional property: the schema checks in the mod and Pi Inbox tests, and apps/hook/tests/register.test.ts.

Results:

  • bun run typecheck (including apps/hook/hooks/mod/tsconfig.json): passes.
  • bun test apps/hook/hooks/mod/: 157 pass.
  • packages/server/inbox*, packages/shared/inbox, packages/core, apps/hook/server/inbox*: 493 pass.
  • packages/ui, packages/inbox, packages/editor, packages/core: pass.
  • apps/opencode-plugin/inbox.test.ts and apps/pi-extension/inbox.test.ts (real Pi, scripted model): 7 pass, 1 skip (the old-CLI floor test).
  • The DOM test passes under DOM_TESTS=1.
  • Not run locally: the engine-harness apps/hook/tests/register.test.ts (scripts/test-claude-code-mod.sh, which runs claude plugin test). It would read the real ~/.claude, and CI does not run it either.

…_inbox tool

- Source code and scripts (the code-file set, CODE_FILE_REGEX, now also
  .mjs/.cjs/.mts/.cts) attach as kind "code": refused when the bytes are
  not UTF-8 text, shown read-only as one highlighted code block in the
  window and the phone surface; annotations on them are refused.
- plannotator_inbox takes an optional project_path (the repository or
  folder a call is about). Connections resolve it against the working
  folder and refuse a path that is not an existing folder before the
  Inbox is reached (the mod, Pi and OpenCode).
…e .env family

- codeDocumentBlocks highlights only up to CODE_HIGHLIGHT_MAX_CHARS
  (100,000): Shiki is one synchronous pass, which froze the window on a
  large file. Above it the block has no language (one plain text node).
- inboxAttachmentNameRefusal refuses any .env.* name outside the
  annotatable doc set (.env.ts, .env.local.sh); .env.example stays.
- The binary refusal reads "not UTF-8 text (binary or another encoding)".
@backnotprop
backnotprop force-pushed the fix/inbox-code-attachments-project-path branch from 596c06c to 27471e2 Compare October 10, 2026 22:21
@backnotprop
backnotprop merged commit 4c65979 into main Oct 10, 2026
23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant