Skip to content

AGENTS.md

Latest commit

 

History

History
145 lines (122 loc) · 7.29 KB

AGENTS.md

File metadata and controls

145 lines (122 loc) · 7.29 KB
Raw

AGENTS.md

Last reviewed: 2026-02-12

Notes for agents working in this repo.

Read before changing behavior

  • Agent coding standards: docs/coding-standards.md
  • Tool behavior rules: src/tools/DECISIONS.md
  • UI/CSS architecture: src/ui/README.md (first-party preflight; keep it faithful)
  • Upstream divergences: docs/upstream-divergences.md (read before adding new divergences)
  • Docs index: docs/README.md
  • Model registry freshness: docs/model-updates.md (if Last verified > 1 week, refresh Pi deps + re-verify model IDs before model UX changes)

High-leverage conventions

Core tools: one source of truth

  • Define core tool names in src/tools/registry.ts (CORE_TOOL_NAMES, CoreToolName, createCoreTools()).
  • Do not duplicate tool-name lists; import CORE_TOOL_NAMES.
  • When adding/removing a core tool, update in the same PR:
    • src/tools/registry.ts
    • src/ui/tool-renderers.ts
    • src/ui/humanize-params.ts
    • src/context/tool-disclosure.ts
    • src/prompt/system-prompt.ts (if documented tool list changes)

UI i18n (t() layer)

  • All user-visible UI strings go through t() from src/language/index.ts. en.json is the source of truth (values must exactly match the intended English UI); zh-CN.json mirrors the key set. Parity + usage enforced by tests/i18n-locales.test.ts (runs in test:context).
  • Never call t() at module scope — language is set at boot, after module import; module-scope calls freeze to English. Store keys and resolve lazily (see src/ui/whimsical-messages.ts).
  • Never route agent-facing strings through t(): system prompt, tool names/descriptions/schemas, context injection, compaction prompts. Tool label is UI-only and safe. See prompt-caching notes below.
  • zh-CN is AI-generated; keep the "AI 翻译" marker on the language option (settings.section.language.zh).

Tool results (ToolResultMessage.details)

  • Keep human-readable output in result.content.
  • Put stable machine metadata in result.details.
  • UI should prefer details, with fallback for older persisted sessions.
  • Reuse guards/types from src/tools/tool-details.ts.

Workbook identity + session restore

  • Never persist raw Office.context.document.url.
  • Use getWorkbookContext() from src/workbook/context.ts.
  • Use src/workbook/session-association.ts helpers for SettingsStore mapping keys.

Security / HTML / local servers

  • Avoid innerHTML for user/tool/session content; use DOM APIs or src/utils/html.ts.
  • Keep markdown protections from installMarkedSafetyPatch() (src/compat/marked-safety.ts).
  • Keep strict origin allowlists in:
    • scripts/cors-proxy-server.mjs
    • scripts/tmux-bridge-server.mjs
    • scripts/python-bridge-server.mjs
  • Keep proxy target filtering strict in scripts/proxy-target-policy.mjs.
    • Do not commit permissive defaults (e.g. ALLOW_ALL_TARGET_HOSTS=1).

Bundle hygiene (Office WebView)

  • Avoid Node-only imports and side-effect barrel imports.
  • After import/dependency changes, run npm run build and check chunk sizes + Vite browser-compat warnings.

Prompt caching gotchas

  • Prompt cache keys are prefix-based and sensitive to: model identity, system prompt, tool schemas, and session key.
  • Keep static prefix content stable (no timestamps/random IDs in system prompt or tool metadata).
  • Prefer message-tail updates for volatile state (auto-context/system reminders) instead of mutating base prompt text every turn.
  • Keep tool ordering deterministic; do not rebuild tool lists with unstable ordering.
  • Do not reintroduce blanket eager setTools(...) on refresh passes when extension tools exist; use fingerprint + extension tool revision semantics.
  • When changing context/tool/model wiring, validate against docs/cache-observability-baselines.md and record expected vs observed prefixChangeReasons.

TypeScript policy

  • No // @ts-ignore.
  • If unavoidable: // @ts-expect-error -- <reason> with a real reason.
  • No explicit any, as any, non-null assertions, or direct unknown syntax.
  • Use DynamicValue only at true external/runtime boundaries, then parse/refine into concrete domain types before values flow inward.
  • Do not add generic object/record guards (isRecord, isObjectValue, isPlainObject, etc.); write concrete parsers or domain-specific predicates instead.
  • Type assertions and lint suppressions must stay local and explain the safety invariant.

Verification

  • npm run check
  • npm run build
  • npm run test:models
  • npm run test:context when touching prompt/context/tool disclosure/session wiring
  • npm run test:security when touching proxy/bridge/auth/HTML safety paths
  • Manual Excel smoke test when touching session persistence, tools, auth, or UI wiring

Visual UI verification (agent-browser)

Use the UI Gallery (src/ui-gallery.html) to verify CSS and component changes without needing Excel. It renders mock components with the real CSS theme.

# Ensure dev server is running (starts automatically if needed)
./scripts/ui-verify.sh                    # Full gallery screenshot
./scripts/ui-verify.sh diff-table         # Screenshot a specific section
./scripts/ui-verify.sh taskpane           # Screenshot the real taskpane (waits for Office timeout)
./scripts/ui-verify.sh stop               # Clean up browser session

Available gallery sections (use as argument): badges, file-items, tool-cards, tool-groups, diff-table, text-preview, buttons, toasts, markdown

Or use agent-browser directly for interactive inspection:

npx agent-browser --session pi-ui open http://localhost:3141/src/ui-gallery.html
npx agent-browser --session pi-ui wait 2000
npx agent-browser --session pi-ui snapshot -i          # See interactive elements
npx agent-browser --session pi-ui screenshot shot.png  # Capture
npx agent-browser --session pi-ui close                # Clean up

For full taskpane inspection (boots without Excel after 3s timeout):

npx agent-browser open http://localhost:3141/src/taskpane.html
npx agent-browser wait 4000           # Wait for Office.js fallback
npx agent-browser snapshot -i -c      # Interactive snapshot
npx agent-browser console --json      # Check for JS errors
npx agent-browser errors --json       # Check for page errors

When to add new gallery sections:

  • Adding a new component type → add a mock render in src/ui-gallery.ts
  • Changing CSS for an existing component → verify via ./scripts/ui-verify.sh <section>
  • Before/after comparison → screenshot before change, make edit, screenshot again

Pre-commit

  • .githooks/pre-commit runs npm run check.
  • Bypass only when needed: git commit --no-verify.

Excel sideloaded manifest gotcha (macOS)

Excel loads a sideloaded manifest from: ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/{add-in-id}.manifest.xml

If local changes do not show up:

  1. Verify sideloaded manifest points to https://localhost:3141/... (not production URL).
  2. Recopy manifest: cp manifest.xml ~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/a1b2c3d4-e5f6-7890-abcd-ef1234567890.manifest.xml
  3. Quit Excel fully and reopen.
  4. If still stale, clear WKWebView cache and relaunch Excel:
    • rm -rf ~/Library/Containers/com.microsoft.Excel/Data/Library/WebKit/
    • rm -rf ~/Library/Containers/com.microsoft.Excel/Data/Library/Caches/WebKit/