feat(adk): @pcc/adk skeleton with a pinned agent package and a clean external install check (R4 D1)

[LamaSu]

What

The first cut of R4 D1: packages/adk (@pcc/adk, working name), plus a clean external install check that proves the public kit installs and imports outside this workspace, with no npm publish.

It is interface work, per the reconciliation note (returns/pcc-adk.md §0.5 D1) and board row R4. The package is "private": true until the operator decides npm publishing and the public name (queue 36, D1 and D2). Nothing publishes.

The package

• Depends on the public @pcc/spec and @pcc/kernel-sdk only. It re-exports kernel-sdk, which is the digital-kernel backend (R2).
• Pinned agent package, with no hand-written tool JSON (#2392).
  • scripts/generate-agent-pin.mjs writes src/generated/agent-pin.ts from apps/dashboard/public/agent-package.json. The pin holds the schema, version (2.19.1), tool count (253) and the sha256 of the exact bytes, plus each tool's {method, path, required}.
  • A unit test fails when the pin is stale. So an agent-package change must regenerate the pin in the same PR (pnpm --filter @pcc/adk generate). FYI aeo.
• resolveToolRequest(name, input, { baseUrl }) turns a tool call into {method, url, body?}.
  • It is pure and never adds credentials, so the caller decides where a key goes.
  • It refuses endpoints that are not gateway paths. The live agent package still lists pcc_generate_ui at http://localhost:3200/api/generate, the N50/N11 class; R43 removes it.
  • It refuses ., .. and empty path parameters, which URL normalization would turn into a different route.
  • It refuses a base URL that is not plain http(s).
  • Path parameters are URL-encoded, and query keys are sorted.
• checkAgentPackage(text) compares a live /agent-package.json with the pin: sha256, version and tool count.

Clean external install: pnpm --filter @pcc/adk check:clean-install

1. Build, then pnpm pack, spec, kernel-sdk and adk. Pack rewrites workspace:*.
2. Boundary gate on every tarball. It fails on any of these:
   • a workspace: left in the package;
   • an @pcc/* dependency that is outside the packed set or private in the workspace;
   • a chain client (viem, ethers, wagmi, …);
   • a key or env file in the payload.
3. Install. A consumer project outside the workspace depends on the adk tarball, with pnpm.overrides pointing at the other two tarballs. It installs offline from the local pnpm store, so there is no network access.
4. Use. A plain Node ESM import, then a TypeScript consumer type-check against the installed declarations.

Result: passes. It prints "agent package 2.19.1 (253 tools)", then "a TypeScript consumer type-checks against the installed declarations". Negative checks:

• with viem added to adk, it fails at the gate (depends on chain client viem);
• with a private @pcc/gateway dependency, it fails at pack.

It is not wired into CI. A ci.yml step needs operator approval; I'll propose one once this shape is agreed.

Lockfile

pnpm-lock.yaml gains only the packages/adk importer (16 lines), and a frozen offline install accepts it. A plain pnpm install had also re-resolved unrelated zod peers for viem and wagmi. I dropped that churn deliberately.

Tests

• adk: 10 passed.
• tsc --noEmit clean.
• The clean-install check passes (see above).

Next (not in this PR)

• Re-export D2's planProvenance once feat(spec): planProvenance, the deterministic provenance planner (ADK D2) #406 lands.
• The CapabilityProject driver (D4).
• Economics helpers (D6) after feat(spec): economic agreements v1, an exact compiler to V-next per-unit payouts #360.
• A CI step for the clean-install check (operator).

🤖 Generated with Claude Code

https://claude.ai/code/session_01PkeiQMnVePeBGU9svhREFy