feat(commonly): commonly_attach_file extension tool + path-policy plugin-sdk export

[samxu01]

Summary

Implements the kernel-layer file-delivery verb described in ADR-013 (Team-Commonly/commonly#287). Agents call commonly_attach_file with a workspace-relative path; the tool reads the file, uploads it via the agent runtime endpoint, and (optionally) posts a chat message containing the [[upload:...]] directive that the v2 inspector renders as a clickable preview pill.

This is the first of the ADR-013 implementation PRs — Phase 0b in the ADR's phasing. Phase 1 (default skill bundles for dev presets) and the gateway Dockerfile toolchain (OfficeCLI + pandoc + markitdown) follow in separate PRs.

Changes

Three files, all additive (177 insertions, 0 deletions):

1. extensions/commonly/src/client.ts — new uploadFile() method

Multipart/form-data POST to /api/agents/runtime/pods/:podId/uploads using the runtime token. Returns {_id, fileName, originalName, size, kind} which the tool embeds in the [[upload:...]] directive.

2. extensions/commonly/src/tools.ts — new commonly_attach_file tool

commonly_attach_file({
  podId: string,           // required
  filePath: string,        // workspace-relative, must not escape /workspace/<accountId>/
  message?: string,        // optional caption — posts message with directive appended
  replyToId?: string,      // optional reply threading
})
  → { ok, file: {_id, fileName, originalName, size, kind}, message? | directive }

Validates the path via toRelativeWorkspacePath, reads up to 25 MB, detects MIME from extension (server validates against the ADR-002 allowlist), uploads, and either posts a chat message or returns metadata for the caller to compose its own.

3. src/plugin-sdk/index.ts — exports path-policy helpers

`toRelativeWorkspacePath` / `toRelativeSandboxPath` / `resolvePathFromInput` from `src/agents/path-policy.js`. These existed in core but weren't visible to plugins. Phase 0a (iii) of ADR-013 verified the helpers are high quality (rejects `..`, resolves symlinks, cross-platform); they just needed the export.

Why kernel-layer

`commonly_attach_file` is runtime-agnostic by construction. Any runtime that produces a file in the agent workspace — gateway-resident agents, ADR-005 wrapper agents, future webhook agents — calls the tool with the same shape and the file lands in chat.

Test plan

This is a new tool with no existing tests. After merge:

• commonly bumps the submodule pointer
• Deploy Dev rebuilds the gateway image
• Hand-test: dev agent drops a fixture PDF in workspace, calls `commonly_attach_file`, file appears in chat with preview pill
• Hand-test: path-traversal attempt (`../../etc/passwd`) is rejected
• Hand-test: file >25MB is rejected

Unit-level vitest coverage is a follow-up — getting the surface in front of agents on dev first.

Companion

ADR-013 #287 (merged) — design doc.
Phase 0a findings #291 — closes Q1/11/12/13.

🤖 Generated with Claude Code