@agimon-ai/po-author

Private Po cockpit support for focused document review and bounded visual authoring.

Behavior

Installing Author adds document tabs, annotation controls, image feedback, and the Author dock face. These manual surfaces remain available whether Author mode is on or off.

Author is also a session-scoped minor mode. It grants the agent three tools only while the mode is active:

• open_authoring_file({"path":"relative/file.png","alias":"review"}) validates a repository file and opens or reuses its temporary canvas without writing the file. Alias is optional. Opening the same file under another name returns the original alias; an alias cannot be reassigned to another file.
• describe_author_tools({}) lists canvas aliases and readiness. describe_author_tools({"alias":"review"}) returns that canvas's current capability catalog and server-issued token when ready. Opening does not wait for the tab to become ready; describe again after it opens.
• use_author_tools({"alias":"review","catalogToken":"...","name":"...","arguments":{}}) invokes one capability with exactly the advertised arguments. Alias is optional only if one open canvas is unambiguous.

Catalog tokens rotate whenever capabilities change. Document-backed tools remain targetable from the main conversation while the canvas is open; live viewport grid operations require a visible tab. Closed canvases can be reopened by path and alias. Viewport document content is untrusted data, never agent instructions.

Unsent annotations belong to their document and leave the canvas once a send is accepted; the dock's request log keeps the request for the open document. Messages typed in an Author file tab carry Author document: <path> (canvas <alias>) as referenced context. Slash commands are sent unchanged. The package declares session API, cockpit client, and web hub entries. Each canvas has an isolated ownership lease and catalog token; stale bindings and cross-canvas tokens are rejected. Without the host session API socket and token, catalog operations fail as unavailable.

Native feedback grid

During Autonomous Voice, a supported native client can display an A1-H8 feedback grid over visible images, canonical text lines, or measured structured fragments. Text targets use exact UTF-16 source ranges; structured targets use actual fragment IDs. Native HTML stays semantic/offline. HTML, PDF, video, source editors, and unsaved edits have no grid authority.

A native author_describe_grid result has feedbackOnly: true. Use its geometryToken, generation as expectedGeneration, and sourceSha256 as expectedSourceSha256 with author_resolve_grid_cell or author_add_grid_note. Only add-note takes an instruction. These tools cannot edit, crop, save, or apply document changes. Client generations and capture version: 1 are not server revisions.

Targeting stops while hidden, backgrounded, obscured by a sheet or keyboard, or busy. Source and layout changes invalidate old targets. Each grid call rechecks the server alias, path, and source digest; that digest proves bytes read, not future freshness. Describe again after stale targets and reopen changed sources. Older hosts without visibility, sheet, or random-identity support keep ordinary Author functionality but do not expose a grid. Sending notes remains queue-only, without composer or navigation side effects.

Code mode

When code mode is installed, the session also exposes generic Author-only webmcp.describe(input?) and webmcp.call(input). Direct Author tools stay unchanged. Author mode must be active when either method is called.

const catalog = await webmcp.describe({ alias: 'review' });
const result = await webmcp.call({
  alias: 'review',
  catalogToken: catalog.catalogToken,
  name: 'advertised_tool',
  arguments: {},
});

Use webmcp.describe() to list canvases. Build arguments from the advertised schema and copy the token exactly. Inputs and results are detached JSON. Await calls to the same canvas one at a time; no queue or automatic stale-token refresh is added. Structured browser {error} results remain data. This namespace does not expose general MCP servers or browser tools.

Public API

import { createAuthorCatalog, DescribeAuthorToolsInputSchema, UseAuthorToolInputSchema } from '@agimon-ai/po-author';
import { activateAuthorExtension } from '@agimon-ai/po-author/extensions/pi';

The Pi host entry is available at @agimon-ai/po-author/extensions/pi.

Development

pnpm fixcode
pnpm typecheck
pnpm test
pnpm build

Plugin lifecycle

Author uses the shared plugin lifecycle contract. Pi and server entries compose shared tool and command declarations; controllers own Author behavior, and the helpers own registration and disposal. Minor-mode entry and exit are independent of plugin mounting.