Skip to content

AGENTS.md

Latest commit

 

History

History
55 lines (44 loc) · 3.05 KB

AGENTS.md

File metadata and controls

55 lines (44 loc) · 3.05 KB
Raw

agentak

Agentak is a standalone Preact chat UI with an optional Pi agent (agentak/pi) and a Chrome MV3 side panel. This is a pnpm workspace.

Rules

  • Use explicit .ts/.tsx import extensions. Use relative imports in src/ and test/. The @/ alias is only for extension/; it points to ../src.
  • Use Preact, not React. React and Vue are optional host adapters only.
  • Write Simplified Technical English. Keep design and comments minimal.
  • Do not add or run end-to-end tests. Browser checks are manual.
  • Read .agents/components.md before UI work.
  • The library has no component stylesheet. Direct component/AgentChat users install the exported token CSS; mountChat() and framework wrappers inject it unless disabled.
  • Run package scripts from the repository root. package.json is the command authority.

Architectural invariants

  • ChatSession is the only seam between the UI and an agent. The root, components, and framework entries must not import @earendil-works/*; only agentak/pi loads Pi.
  • A session is required. UI wrappers never dispose it; the creator owns disposal.
  • React and Vue wrappers own one outer element. Preact alone owns its children. No Preact node crosses the public boundary: hosts contribute with definitions — actions (ChatAction[]), emptyItems (ChatEmptyItem[]) and prompts. The only door for host rendering is registerElements() on agentak/components.
  • All dependencies stay external. Lazy Pi provider/catalog/Markdown imports must remain lazy for consumer bundlers and MV3.
  • The extension compiles library source through @, not dist.

Focused docs

Known gaps requiring real-browser checks

No real-browser validation has covered the complete chat or side panel. Before release, check real provider keys, WebMCP invocation, model catalog loading, persisted keys, active-tab following, per-site history, badge colors, chrome: tool failures, bundled wllama/OPFS, and WebAuthn PRF device lock. The panel's wllama worker and device-lock user-gesture flow are the highest-risk paths.

Gemini Nano calls tools through the prompt: declarations in the system turn, and a tool_code block read back out of the answer. No real model has been checked against it, so how often a small model writes a call the parser can read is unknown.

Compaction runs from the meter's button, from ChatSession.compact(), and by itself when the window is nearly spent or a turn was refused for overrunning it. None of it has had a real-provider check — the overrun path least of all, since it is a provider's own wording that decides. The panel currently reads the active tab but cannot navigate or operate other tabs.