feat(plugins): Foundations Pack — OS basics (apps, clipboard, files, state)

[rrader26]

Summary

• New `createFoundationsPlugin()` adds 14 cross-platform tools across four surfaces: app launching, clipboard, allowlisted filesystem, durable state.
• Pure Node (only shells out to OS-shipped binaries — no external npm deps).
• Opt-in; not part of the default plugin set.

Why

Foundation for everything in the "AI agent does anything on a desktop" mandate. Today the desktop driver can manipulate a running app's accessibility tree, but the agent can't:

• launch an app or open a file
• copy/paste between apps
• read/write working files outside what the running app exposes
• remember anything across MCP sessions

These four surfaces unblock all of that. Together they're the OS-basics layer that complements (not replaces) the desktop driver.

Tools shipped

Surface	Tools
Apps	`agentmark_app_run`
Clipboard	`agentmark_clipboard_read`, `agentmark_clipboard_write`
Filesystem	`agentmark_files_list`, `..._read`, `..._write`, `..._stat`, `..._delete`, `..._move`, `..._mkdir`
State	`agentmark_state_get`, `..._set`, `..._delete`, `..._list`

Safety

Filesystem ops are gated by an allowlist (default: `cwd` + `os.tmpdir`). Every path is canonicalised via `realpath` before the prefix check, so symlinks like `~/Documents/safe → /etc` can't escape. Roots are themselves canonicalised on first use to handle macOS's `/var → /private/var` alias.

App launch detaches by default so the spawned app survives the MCP server's death; safe for any UI app.

State store writes atomically (temp file + rename), mode 0600 on POSIX. Single global namespace per user — not a database, don't put megabytes in it.

Usage

```ts
import {
createMcpServer,
createWebPlugin, createPdfPlugin, createDesktopPlugin, createMetaPlugin,
createFoundationsPlugin,
} from '@thinkfleet/agentmark'

const foundations = createFoundationsPlugin({
fileRoots: ['/Users/me/Documents', '/Users/me/Downloads'],
})

createMcpServer({
plugins: [web, pdf, desktop, foundations, meta],
})
```

Test plan

• `pnpm build` clean
• `pnpm test` — 355 pass / 10 skip (16 new tests: allowlist enforcement + symlink-escape resistance + state round-trip + plugin registration + handler error paths)
• Manual smoke on macOS: `agentmark_app_run` opens TextEdit; `agentmark_clipboard_write` followed by ⌘V in TextEdit pastes the right text
• Manual smoke on Windows VM: same drill with Notepad

What's next in the roadmap

• PR-γ: Window management (focus / move / resize / minimize / close / screenshot) — needs bridge changes
• Then: Snapshot diff → Recipes → Self-healing IDs → Vision fallback → Recording → Notifications → Network tools → Voice → Process introspection → Hotkeys

🤖 Generated with Claude Code