M5 — @thinkfleet/piece-agentmark Activepieces piece

[rrader26]

Summary

Sibling package in `pieces/agentmark/` that wraps the core AgentMark library as an Activepieces piece. Drop into any flow to convert web pages or PDFs into AgentMark snapshots and fill PDF forms — no code, no SDK install for the flow author.

Stacked on top of #6 (v0.7 MCP server). Merge #2 → #3 → #4 → #5 → #6 → this PR.

Three actions (v1)

Action	What it does	Use case
Capture Web Page	URL → AgentMark snapshot. Launches Chromium, snapshots, closes.	Hand off page state to an AI step in the same flow.
Capture PDF	PDF (URL / path / data URI / base64) → AgentMark with `kind: document` or `form`. Optional OCR via Tesseract + Poppler.	Read scanned forms, insurance quotes, county docs.
Fill PDF Form	Atomic AcroForm fill. Accepts field values by action ID OR original field name. Returns base64 / data URI; optional flatten.	Fill vendor applications / claim forms with CRM data.

Why this matters

• Growth OS gets it for free — Growth OS is built on Activepieces, so installing this piece adds AgentMark as a flow primitive immediately.
• Every other Activepieces deployment (community + commercial) can install independently.
• Flow authors don't need to learn the AgentMark SDK — they drag actions onto the canvas.

Tests (13 + 1 gated)

• Piece-shape assertions (display name, minimum release, action props)
• `fill_pdf_form` end-to-end:
  • Fill by action ID, by original field name
  • Unknown keys reported via `fields_skipped` (no throw)
  • `return_format: 'base64'` vs `'data_uri'`
  • `flatten` removes the form (verified by re-reading with pdf-lib)
  • Accepts `data:` URI source (no temp file)
• `snapshot_pdf` end-to-end (text PDF): produces `kind: form`
• `snapshot_web_page`: gated on `AGENTMARK_INTEGRATION=1` with a local HTTP server (no external network)

Cross-package hygiene fixes

Two real bugs caught during development:

1. Symlinked node_modules → duplicate modules. The piece's `node_modules/@thinkfleet/agentmark` symlinks back to the root, which made vitest pick up root tests twice (once normally, once via the symlink as a different module instance), breaking `instanceof` checks. Fixed via `vitest.config.ts` excluding `pieces/**` from root test discovery.
2. TypeScript emitting into parent `src/`. The piece's `tsc` followed the symlink and wrote compiled `.js` / `.d.ts` files into the parent's `src/`, which then shadowed the source files at test time. Fixed by setting `rootDir: ./src` and `preserveSymlinks: true` in the piece's tsconfig.

Architecture

```
pieces/agentmark/
├── package.json (file:../.. dep on parent during dev)
├── tsconfig.lib.json (rootDir: ./src + preserveSymlinks: true)
├── README.md
├── src/
│ ├── index.ts (createPiece export)
│ └── lib/
│ ├── common.ts (resolveBytes — URL/path/base64/data URI)
│ └── actions/
│ ├── snapshot-web-page.ts
│ ├── snapshot-pdf.ts
│ └── fill-pdf-form.ts
└── test/piece.test.ts (13 unit + 1 gated)
```

Distribution path

When v0.7 publishes to npm:

1. Bump `@thinkfleet/agentmark` from `file:../..` to `^0.7.0` in `pieces/agentmark/package.json`
2. `cd pieces/agentmark && npm publish --access public`

The piece can then be added to any Activepieces deployment via `@thinkfleet/piece-agentmark`.

Test plan

• Merge v0.3.0 — production-ready SDK surface + action executor #2 → v0.4.0 — PDF support + spec v0.2 (kind: document) #3 → v0.5.0 — OCR + render-backend pipeline (100% on insurance corpus) #4 → v0.6.0 — AcroForm extraction + PdfDocument fill/save SDK #5 → v0.7.0 — MCP server (any AI client can use AgentMark) #6 first
• At repo root: `npm install && npm test` — 207 unit + benchmark tests pass
• In `pieces/agentmark/`: `npm install && npm run build && npm test` — 13 piece tests pass
• Spot-check that `npm test` at the repo root does NOT recurse into `pieces/`
• Verify no `.js` / `.d.ts` files leak into parent `src/` after building the piece
• Smoke test: register the piece in an Activepieces dev instance, drag `Capture PDF` onto a flow, verify the action runs end-to-end

🤖 Generated with Claude Code