@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.

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.