@uppercut-labs/agent-native 0.0.0-stage → 1.1.0

package/docs/evidence/UAN-017-version-migrations.md

@@ -0,0 +1,50 @@
+# UAN-017 version migration evidence
+
+## Scope
+
+The portable composition entrypoint now provides exact-major selection, stable explicit aliases,
+structural definition comparisons, same-ID breaking replacement rejection, reviewed major migration
+records, explicit lifecycle policy, and guarded pack migration validation. It does not import
+handlers or runtime adapters.
+
+E08 independently packs a contract-only album package containing v1 and v2. Its old binding uses the
+shared internal data lookup while retaining the single-title output. Its new binding requires locale
+and returns localized titles. JSON fixtures lock both shapes.
+
+## Reproduction
+
+From the repository root:
+
+```sh
+npm run build
+node --test test/composition.test.mjs test/public-exports.test.mjs
+npm run typecheck
+npm run lint
+npm run format:check
+npm run example:e08
+```
+
+The E08 suite checks exact selection and alias stability, distinct outputs, structural default/unit,
+rename and required-field reporting, mandatory semantic review for schema-identical majors,
+same-identity replacement rejection, implicit retirement rejection, independent consumer processes,
+and the contract-only import boundary.
+
+Observed on `research` (Darwin arm64, Node 24.18.0, npm 11.16.0): typecheck, format check, build,
+and focused lint exited successfully after the final review fixes. The full lint had exited
+successfully before those fixes. The focused composition/public-export suite passed 14/14. Biome
+reported non-fatal style suggestions in the schema-diff code. The standalone E08 harness
+packed and installed both packages from tarballs, passed 9/9 tests with zero audited vulnerabilities
+in that exported fixture, and returned the v1 `Kind of Blue` output. `git diff --check` passed.
+
+The post-review tests reject a spoofed pack authority, a structural multi-major pack without
+reviewed migration policy, forged semantic/contract reports, a new property in a closed v1 output
+schema under the same ID, and fake lifecycle `get()` claims without matching entries. E03's
+lockfile export fix and E12's canonical ID remain untouched. A full repository suite was not rerun
+for this focused slice.
+
+## Limits
+
+- Structural comparison reports only information represented in JSON Schema and risk/access metadata.
+- Rename detection matches a unique removed/added property with identical structure; review determines intent.
+- Lifecycle policy is local application metadata; no remote registry or package signature is provided.
+- Removal validation enforces a prior deprecated state but does not schedule retention or notify consumers.

package/docs/evidence/UAN-018-surface-overrides.md

@@ -0,0 +1,30 @@
+# UAN-018 surface override and schema evidence
+
+## Scope
+
+A definition may explicitly choose an HTTP path/method and a CLI command/aliases. GET is restricted to read capabilities with a representable top-level query schema. The HTTP handler, generated OpenAPI operation, local CLI, and remote CLI use that definition. Defaults retain the canonical POST route and canonical CLI identity. This is a local implementation slice, not a production host certification.
+
+E10 exports the unchanged existing `searchContent({ query, limit })` function and data from `service-before` into a fresh consumer. Its new binding preserves `GET /api/content/search?q=night&limit=1`, exposes `content-search` and `search`, and leaves unrelated health and content routes available. The before-state source files were not edited.
+
+## Reproduction and observed results
+
+On canonical `research` (Darwin arm64, Node 25.9.0, npm 11.12.1) after integrating the isolated Node 24 worker:
+
+```sh
+npm run typecheck
+npm run build
+node --test test/composition.test.mjs test/http.test.mjs test/cli.test.mjs test/zod.test.mjs
+npm run example:e10
+npm run example:e12
+npm run docs:check
+npm run format:check
+npm run lint
+```
+
+All commands exited successfully. The focused root suite passed 36/36, fresh E10 installed from a package tarball and passed 4/4 plus a CLI smoke call, E12 passed 6/6, and the docs checker validated 27 HTML pages and 26 search entries. The E10 and E12 exported installs each reported zero audit vulnerabilities. The isolated worker had already passed Node 24 typecheck/build/format/lint, 24 focused tests, and fresh E10 4/4. A full local repository suite was not repeated; Node 22/24 CI is the integration gate.
+
+Negative tests cover GET on a write capability, duplicate HTTP routes and CLI aliases, unsupported or malformed query conversions, missing/invalid input, bounded GET query bytes, non-finite JSON numbers, unsupported Zod transforms, invalid output, and a JSON `__proto__` field without prototype mutation. Remote CLI calls follow the overridden GET route and query mapping. Same-ID surface changes now fail the UAN-017 compatibility guard; a description-only change remains compatible.
+
+## Limits
+
+The GET projection supports documented scalar and flat-array query fields; nested objects and unsupported conversions fail rather than being coerced. The example uses a local Node host and synthetic public data. It does not validate an external API gateway, deployed identity, browser agent, or npm registry installation. The public package remains `private: true` at `0.0.0`.

package/docs/evidence/UAN-019-doctor.md

@@ -0,0 +1,19 @@
+# UAN-019 doctor evidence
+
+This integration adds the `./doctor` public subpath and E11 fault/repair fixture to the unreleased `0.0.0` source package. The report schema is `uan.doctor-report/v1`; findings use stable `checkId` values, explicit evidence levels and sources, and selected/required check profiles. The E11 `local` profile selects six configuration and artifact checks. The `full` profile adds endpoint reachability and a fixture-specific health exchange. It does not claim a real host.
+
+## Canonical research checkout verification
+
+On macOS research with Node 24.18.0, after integrating UAN-018, UAN-020, and the bounded UAN-021 docs slice:
+
+- `npm run typecheck` and `npm run build` passed.
+- `node --test test/doctor.test.mjs test/discovery.test.mjs` passed 7/7, including Ajv validation of a serialized doctor report, invalid schema fields, required profile behavior, exception redaction, and policy-filtered listing without handler calls.
+- `npm run example:e11` built and packed the current package, installed an independent pinned E11 export, and passed its 7/7 tests. The fault variants and repaired variants include a destructive canary that must not run during diagnostics.
+- `npm run docs:check` rendered 29 documentation pages and validated 30 generated HTML pages and 29 search entries after the doctor guide was added.
+- Scoped Biome format/lint and `git diff --check` passed.
+
+The isolated worker also passed Node 24 typecheck/build, the same targeted doctor tests, and a fresh E11 standalone export before integration. CI on Node 22/24 is a separate gate and should be linked after this commit is pushed.
+
+## Boundaries
+
+No doctor check makes a network request by default. An explicit E11 loopback probe can verify its local health fixture only. Missing endpoint or browser context remains unknown/skipped. No production identity, real browser, remote MCP host, or application data is verified. Registry inspection and authorized listing are read-only and cannot replace execution-time authorization. The checked-in E11 values are fake local fixtures; real applications provide their own checks and controlled evidence sources.

package/docs/evidence/UAN-020-negative-security-fixtures.md

@@ -0,0 +1,61 @@
+# UAN-020 negative security fixture evidence
+
+This slice adds deterministic local fixtures for E07 authorization, identity, and MCP App
+resource behavior. Tests use official SDK clients over loopback HTTP. No production identity provider,
+remote MCP host, browser sandbox, or production network service is exercised.
+
+## Demonstrated behavior
+
+- E07 rechecks a durable grant on the next same-client call. After delete access is revoked, the tool
+  disappears from discovery, direct invocation is denied, the target playlist survives, and the other
+  tenant's playlist remains unchanged.
+- Wrong-issuer, wrong-audience, expired, low-scope, malformed, oversized, cross-tenant, hidden-tool,
+  and revoked calls do not mutate playlist state. Negative responses do not reflect the fixture token
+  or adversarial payload sentinels.
+- Two tenants have independent grants and record ownership. Revoking Alice's delete grant does not
+  change Bob's playlist or grant.
+- MCP App registration rejects non-`ui://` schemes, traversal segments, undeclared capability IDs,
+  protocol-relative scripts, and external CSS origins. A legitimate bundled resource completes an
+  SDK list/read roundtrip with `text/html;profile=mcp-app`.
+- MCP App resources inherit capability discovery. An anonymous client cannot list or directly read a
+  protected resource. An authenticated client can read it while its grant is live; after revocation,
+  the next list/read in that same client session is denied without executing the protected binding.
+- The E07 process refuses empty or missing explicit persistence paths. A canary starts it in an empty temporary working
+  directory and verifies failure creates no default files. This is an E07-only no-default-mutation
+  claim, not evidence about CLI init or doctor behavior.
+
+## Reproduction
+
+Run from the repository root with the checked-in dependency set:
+
+```sh
+npm run build
+node --test test/mcp.test.mjs test/mcp-apps-security.test.mjs
+npm run example:e07
+npm run example:e09
+npx biome format src/mcp-apps.ts test/mcp.test.mjs test/mcp-apps-security.test.mjs examples/e07-playlist-permissions/project/src/server.mjs examples/e07-playlist-permissions/project/test/e07.test.mjs
+npx biome lint src/mcp-apps.ts test/mcp.test.mjs test/mcp-apps-security.test.mjs examples/e07-playlist-permissions/project/src/server.mjs examples/e07-playlist-permissions/project/test/e07.test.mjs
+npm run typecheck
+git diff --check
+```
+
+Record the exact local command results in the UAN-020 handoff; this note does not treat commands as
+passing until they have run in the integration worktree.
+
+## Limits and integration dependencies
+
+- Static token names and the JSON stores exist only in explicit E07 test mode. They are not a JWT
+  implementation, production credential, cross-process lock, or production persistence design.
+- The MCP transport is loopback HTTP using official SDK clients. No commercial host, iframe origin,
+  CSP enforcement engine, OAuth server, intermediary cache, or concurrent distributed session was tested.
+  Deployed cache-control and cross-surface cache isolation remain open.
+- UAN-018 owns CLI, HTTP, and contract integration. UAN-019 owns doctor integration. This slice makes
+  no claim about those surfaces and does not edit their files.
+- The no-default-mutation canary is intentionally limited to E07's explicit local persistence paths.
+  UAN-018/UAN-019 must integrate their own init/doctor mutation evidence before a cross-surface claim.
+
+## Isolated research verification
+
+At public base 0257a9b, the isolated research checkout passed Node 24 typecheck and build, the focused MCP test file (13/13), the MCP App security regressions (2/2), standalone E07 (4/4), and standalone E09 (3/3). Scoped Biome format and lint passed; lint emitted only existing template-literal style suggestions. This is local fixture evidence, not canonical CI or real-host verification.
+
+The first standalone E07 run failed 3/4 because the fixture accepted empty persistence paths and its new canary waited for a process that had started. The fixture now rejects empty paths and the canary has a three-second deadline. The second standalone E07 run passed 4/4. The MCP App validator now checks URL-bearing attributes across tags, rejects entity-bearing URL values and external candidates in srcset, and rejects meta refresh directives while allowing bundled relative resources. The focused regressions include unquoted script/image URLs, character references, mixed srcset, form/base URLs, quoted-attribute delimiters, CSS URL/import/escape attempts, and caller mutation after validation. The validator returns frozen copies of the reviewed resource fields. Host CSP enforcement remains a separate unverified boundary.

package/docs/evidence/UAN-020-operational-failure-safety.md

@@ -0,0 +1,49 @@
+# UAN-020 operational failure safety evidence
+
+This is a local fixture result from an isolated research checkout at public base `8a502b5` on
+Node.js 24.18.0. It extends the E07/MCP App threat-fixture note without claiming a deployed host.
+
+## Timed-out writes
+
+A protected MCP write used the official client/server SDK over loopback HTTP, a fixture token and
+current in-memory grant, and a 20 ms deadline. Its handler deliberately ignored the aborted signal,
+then committed after 60 ms. The client received a tool error saying the write may have completed and
+warning against retry. After the handler settled, the test observed one invocation, one commit and
+an aborted signal. The adapter made no second invocation. This demonstrates uncertain completion,
+not cancellation or at-most-once semantics under a real network retry.
+
+The generated HTTP adapter and remote CLI currently expose public reads only. A direct protected
+HTTP write returned `404` before its binding ran. The same protected write submitted to remote CLI
+returned `capability-unavailable` before its fetcher or binding ran. CLI local mode has no timeout
+implementation. These are explicit surface limits, not write-timeout
+claims for HTTP or CLI.
+
+## Default operation and browser boundary
+
+Default init detection and plan creation left the sample project directory, Astro config and
+lockfile byte-identical and created no provisioning canary marker. E11's fresh packed install
+passed seven fixture checks: its default doctor scans eight fault/repair scenarios without calling
+any capability handler or destructive canary. An application can supply its own doctor observer;
+that observer's side effects remain an application responsibility. The E07 server's separate
+no-default-persistence-path canary is recorded in the threat-fixture note.
+
+E03's fresh packed Next.js production build found the fake server-only sentinel in one server
+artifact and absent from 20 browser artifacts, including nine browser source maps. A negative
+control appended that sentinel to one emitted browser source map; the scanner failed with
+`server-only sentinel leaked into browser artifacts`. The map was restored byte-for-byte and the
+scanner then passed again. The sentinel is deliberately fake; this does not prove absence of every
+possible secret in arbitrary future application code. No deployed browser was tested.
+
+## Focused reproduction
+
+```sh
+npm run typecheck
+npm run build
+node --test test/mcp.test.mjs test/cli.test.mjs test/http.test.mjs test/init.test.mjs
+npm run example:e11
+npm run example:e03
+```
+
+The source-map negative control was run against E03's ignored `.exported/.next/static` output and
+restored afterward; it did not change tracked fixture files. Only focused checks were run in this
+isolated clone. Broad Node 22/24 CI and real-host validation remain integration gates.

package/docs/evidence/UAN-021-docs-coverage.md

@@ -0,0 +1,30 @@
+# UAN-021 documentation coverage evidence
+
+This documentation audit used an isolated clone on `research` at public base
+`79f7e4ea8324ed616d83c04715a1eaf4dd175144`, Node.js 24.18.0 and
+`npm ci --ignore-scripts --no-audit --no-fund`. The clone has no canonical
+Git remote write. The package remains private at `0.0.0`.
+
+## Checked result
+
+- Every E01-E12 coverage record now carries requirement IDs and a guide with a
+  source-backed region from that example's tested project source. The docs
+  coverage validator rejects missing paths, stale negative probes, missing
+  source regions, omitted example scripts, and missing CI wiring.
+- The generated reference lists the 18 current typed package subpaths and
+  runner flags and typed adapter configuration directly from `package.json` and checked source. A parser
+  option or guarded bound change requires a reference update.
+- Public guides now give a Node prerequisite, root export command, expected
+  fixture result, relevant failure and repair, and source or example link.
+  Compatibility and support statements were reconciled with the existing
+  E01-E12 fixtures. They do not claim production or universal host support.
+- `node --test docs-site/coverage-check.test.mjs docs-site/source-regions.test.mjs docs-site/reference.test.mjs`
+  passed 8 of 8 focused tests. `npm run docs:check` built 36 HTML
+  pages including the home page, verified 35 search entries, and validated
+  twelve example coverage records. `node --check` passed for ten
+  source files with new marker comments; scoped Biome format/lint passed.
+
+The docs command validates wiring and generated pages. This audit did not
+rerun all twelve exported projects; that is the root `npm run check` gate
+on Node 22/24 CI. It did not test deployed docs, physical browsers, native
+WebMCP, a commercial MCP Apps host, or an npm installation.

package/docs/evidence/UAN-022-cross-platform-license-notices.md

@@ -0,0 +1,39 @@
+# UAN-022 cross-platform optional-integration license and notice review
+
+Checked 2026-10-10 on macOS arm64 with Node 26.10.0 and npm 11.19.1. The consumer depended on the published `@uppercut-labs/agent-native@0.1.1` registry tarball (SHA-256 `a1ce884f89eadba319d6fbad5c9b09b05575a7ab15998bcfd4a6ad8cc8228fbb`) plus the pinned optional integrations `@modelcontextprotocol/server@2.3.0`, `@modelcontextprotocol/ext-apps@2.0.3`, `astro@7.3.5` and `zod@4.6.5`. This extends the [macOS-only inventory](UAN-022-overhead-license-audit.md) to Linux and Windows package trees. It is a package-metadata and shipped-file review, not legal advice.
+
+## Method
+
+For each target, a fresh project ran `npm install --ignore-scripts --no-audit --no-fund --os=<os> --cpu=<cpu>` (and `--libc=glibc` for Linux). npm then installs the platform-specific optional packages for that target instead of the host's. Every `package-lock.json` entry was matched to a physically installed `package.json`; its `name`, `version` and `license` were recorded, along with any top-level `LICENSE`, `COPYING`, `NOTICE`, `THIRD-PARTY` or `AUTHORS` file. The native binaries were installed, not executed: this checks what an application would redistribute, not runtime behavior on those operating systems.
+
+## Result by target
+
+| Target | Lockfile paths | Installed packages | Without a top-level license file |
+| --- | ---: | ---: | ---: |
+| darwin arm64 | 304 | 205 | 9 |
+| linux x64 glibc | 304 | 204 | 9 |
+| linux arm64 glibc | 304 | 204 | 9 |
+| win32 x64 | 304 | 203 | 8 |
+
+Every installed manifest declared a license. Across targets the license set is the same: MIT, ISC, Apache-2.0, BSD-2-Clause, BSD-3-Clause, BlueOak-1.0.0, CC0-1.0, MPL-2.0, Python-2.0 and LGPL-3.0-or-later. The only differences between targets are the native packages for Astro's compiler, Satteri, esbuild, Rolldown, Sharp/libvips and Lightning CSS, plus macOS-only `fsevents`. Since the earlier inventory, transitive `@rolldown/binding-*` moved from 1.2.12 to 1.2.13 (MIT), and `@img/sharp-win32-x64@0.35.5` declares `Apache-2.0 AND LGPL-3.0-or-later`.
+
+## Packages that need application attention
+
+| Package | Targets | License | Shipped notice |
+| --- | --- | --- | --- |
+| `@img/sharp-libvips-<platform>@1.3.4` | darwin arm64, linux x64, linux arm64 | LGPL-3.0-or-later | No license text. The README has a table of component licenses. |
+| `@img/sharp-win32-x64@0.35.5` | win32 x64 | Apache-2.0 AND LGPL-3.0-or-later | Has a `LICENSE` file, but it contains only Apache-2.0 text, not the LGPL text. It bundles `libvips-42.dll`. |
+| `lightningcss` and `lightningcss-<platform>@1.33.0` | all | MPL-2.0 | `LICENSE` present |
+| `argparse@2.0.1` | all | Python-2.0 | `LICENSE` present |
+| `lru-cache@11.5.3`, `sax@1.6.1`, `common-ancestor-path@2.0.0` | all | BlueOak-1.0.0 | `LICENSE.md` present |
+| `mdn-data@2.0.28`, `mdn-data@2.27.1` | all | CC0-1.0 | `LICENSE` present |
+
+Some MIT/ISC packages ship no top-level license file. They are the platform bindings for `@astrojs/compiler-binding`, `@bruits/satteri`, `@esbuild` and `@rolldown/binding`, plus `am-i-vibing`, `boolbase`, `piccolore` and `process-ancestry`. An application that redistributes them should take the notice from the parent project's repository.
+
+## Decision
+
+The Agent Native package itself has zero hard runtime dependencies. A core or browser consumer installs only the MIT tarball on every target, as `npm run check:portability` checks. All LGPL, MPL and other notice-bearing packages arrive only when an application chooses the Astro integration. Sharp/libvips arrives through Astro's image pipeline. These packages are present on every target, not just macOS, and on Windows the LGPL component ships inside an Apache-2.0-labeled package.
+
+This closes the cross-platform inventory gate for the `0.1.1` preview. No change to the package or its peer ranges is needed. An application that bundles or redistributes an Astro build toolchain, especially a desktop or container image, must collect its own notices. It should use the versions its own lockfile resolves and should not rely on this snapshot. Server and static-site deployments that ship only Astro's build output do not redistribute these build-time packages.
+
+To reproduce: create a project with the five dependencies above, run the install command once per target in an empty directory, and compare the lockfile entries with the installed manifests.

package/docs/evidence/UAN-022-overhead-license-audit.md

@@ -0,0 +1,233 @@
+# UAN-022 focused overhead and resolved license inventory
+
+Measured 2026-10-03 on research macOS arm64, Node 24.18.0, from isolated source commit `84a5e479f51177a1321630b3955c6bfb93f2e169`. This is package evidence for the private `0.0.0` candidate, not an npmjs installation or release certification. A normal `npm pack --json` ran `prepack` and built the declared exports. The resulting tarball was 135,833 bytes. All consumers below installed that tarball with `npm install --ignore-scripts --no-audit --no-fund`.
+
+## Cold-process invocation and browser bundles
+
+| Observation | Samples / scope | Result |
+| --- | --- | --- |
+| `runDoctor` with one required passing fixture check | 12 separate Node processes from a packed core consumer | min 22.608 ms; median 23.446 ms; max 24.685 ms |
+| Application-owned local CLI fixture, `greet --mode local --name Timing` | 12 separate Node processes from the same packed consumer | min 25.981 ms; median 27.482 ms; max 30.809 ms |
+| Synthetic Vite client retaining `createBrowserCapabilityAdapter(document)` from `/browser` | one production build with selected peer tree | 7,392 JS bytes; 2,772 gzip bytes |
+| E06 browser theme example, installed from the same tarball | one production Vite build with Zod 4.6.5 and Vite 8.3.2 | 86,176 JS bytes; 25,532 gzip bytes |
+
+Timing used Python `time.perf_counter()` around each `node` subprocess and checked a successful exit. Every sample started a new Node process, while the host file cache and npm cache were warm. The doctor fixture verified an exit-0 report with one finding; it did not contact a remote host. The CLI used the repository's `test/fixtures/packed-cli-smoke.mjs`, including process startup and local execution. The synthetic bundle used `vite build` and assigned the adapter to `window` to prevent tree shaking. Gzip counts use level 9 with a zero timestamp. The synthetic bundle contained no MCP server SDK string. These are observed macOS measurements, not cross-platform performance budgets.
+
+## Installed dependency and license metadata
+
+The core/browser consumer manifest depended only on the tarball. Its installed runtime tree contained one package, `@uppercut-labs/agent-native@0.0.0`, whose package metadata declares MIT. No optional peers were installed.
+
+The selected-integration consumer explicitly depended on the same tarball plus `@modelcontextprotocol/server@2.3.0`, `@modelcontextprotocol/ext-apps@2.0.3`, `astro@7.3.5`, and `zod@4.6.5`. Its resolved lockfile had 303 package paths; 204 package paths were physically installed on this macOS arm64 host and 99 platform-specific or otherwise omitted paths had no installed package manifest. The 204 installed paths represented 204 distinct name/version pairs. Every installed package manifest supplied a license value. Counts by the installed package manifests: Apache-2.0: 8, BSD-2-Clause: 8, BSD-3-Clause: 3, BlueOak-1.0.0: 3, CC0-1.0: 2, ISC: 10, LGPL-3.0-or-later: 1, MIT: 166, MPL-2.0: 2, Python-2.0: 1.
+
+The full inventory below records installed package names, versions and package-manifest license metadata; it does not examine license text, notices, bundled binaries, patent terms, or redistribution obligations. In particular, the installed tree includes `@img/sharp-libvips-darwin-arm64@1.3.4` (LGPL-3.0-or-later), `lightningcss@1.33.0` and `lightningcss-darwin-arm64@1.33.0` (MPL-2.0), and `argparse@2.0.1` (Python-2.0). Legal/notice review and inventory on Windows/Linux remain release qualifications for applications selecting these optional integrations. License metadata can change when the consumer resolves newer transitive versions.
+
+To reproduce the scope: pack this commit normally; create fresh npm projects with the dependency sets above; run `npm install --ignore-scripts --no-audit --no-fund`; compare each `package-lock.json` entry to a physically installed `node_modules/<entry>/package.json` and read that manifest's `name`, `version` and `license`. The browser client entrypoint is bundled from `import { createBrowserCapabilityAdapter } from '@uppercut-labs/agent-native/browser'`. The E06 result comes from its project `npm run build` with the packed tarball substituted for its local package dependency. No full root test suite was repeated for this evidence.
+
+## Resolved installed inventory
+
+| Package | Version | Manifest license |
+| --- | --- | --- |
+| `@astrojs/compiler-binding` | 0.5.1 | MIT |
+| `@astrojs/compiler-binding-darwin-arm64` | 0.5.1 | MIT |
+| `@astrojs/compiler-rs` | 0.5.1 | MIT |
+| `@astrojs/internal-helpers` | 0.11.0 | MIT |
+| `@astrojs/markdown-satteri` | 0.4.2 | MIT |
+| `@astrojs/prism` | 4.0.2 | MIT |
+| `@astrojs/telemetry` | 3.3.3 | MIT |
+| `@babel/helper-string-parser` | 7.29.7 | MIT |
+| `@babel/helper-validator-identifier` | 7.29.7 | MIT |
+| `@babel/parser` | 7.29.9 | MIT |
+| `@babel/types` | 7.29.8 | MIT |
+| `@bruits/satteri-darwin-arm64` | 0.10.5 | MIT |
+| `@capsizecss/unpack` | 4.0.1 | MIT |
+| `@clack/core` | 1.5.1 | MIT |
+| `@clack/prompts` | 1.8.1 | MIT |
+| `@esbuild/darwin-arm64` | 0.28.2 | MIT |
+| `@img/colour` | 1.1.0 | MIT |
+| `@img/sharp-darwin-arm64` | 0.35.5 | Apache-2.0 |
+| `@img/sharp-libvips-darwin-arm64` | 1.3.4 | LGPL-3.0-or-later |
+| `@jridgewell/sourcemap-codec` | 1.6.0 | MIT |
+| `@modelcontextprotocol/client` | 2.3.0 | Apache-2.0 |
+| `@modelcontextprotocol/core` | 2.3.0 | Apache-2.0 |
+| `@modelcontextprotocol/ext-apps` | 2.0.3 | MIT |
+| `@modelcontextprotocol/server` | 2.3.0 | Apache-2.0 |
+| `@oslojs/encoding` | 1.1.0 | MIT |
+| `@oxc-project/types` | 0.152.0 | MIT |
+| `@rolldown/binding-darwin-arm64` | 1.2.12 | MIT |
+| `@rolldown/pluginutils` | 1.0.1 | MIT |
+| `@shikijs/core` | 4.5.0 | MIT |
+| `@shikijs/engine-javascript` | 4.5.0 | MIT |
+| `@shikijs/engine-oniguruma` | 4.5.0 | MIT |
+| `@shikijs/langs` | 4.5.0 | MIT |
+| `@shikijs/primitive` | 4.5.0 | MIT |
+| `@shikijs/themes` | 4.5.0 | MIT |
+| `@shikijs/types` | 4.5.0 | MIT |
+| `@shikijs/vscode-textmate` | 10.0.2 | MIT |
+| `@standard-schema/spec` | 1.1.0 | MIT |
+| `@types/estree` | 1.0.9 | MIT |
+| `@types/estree-jsx` | 1.0.5 | MIT |
+| `@types/hast` | 3.0.5 | MIT |
+| `@types/mdast` | 4.0.4 | MIT |
+| `@types/nlcst` | 2.0.3 | MIT |
+| `@types/unist` | 3.0.3 | MIT |
+| `@ungap/structured-clone` | 1.4.0 | ISC |
+| `@uppercut-labs/agent-native` | 0.0.0 | MIT |
+| `am-i-vibing` | 0.4.0 | MIT |
+| `anymatch` | 3.1.3 | ISC |
+| `argparse` | 2.0.1 | Python-2.0 |
+| `aria-query` | 5.3.2 | Apache-2.0 |
+| `astro` | 7.3.5 | MIT |
+| `axobject-query` | 4.1.0 | Apache-2.0 |
+| `bail` | 2.0.2 | MIT |
+| `boolbase` | 1.0.0 | ISC |
+| `ccount` | 2.0.1 | MIT |
+| `character-entities-html4` | 2.1.0 | MIT |
+| `character-entities-legacy` | 3.0.0 | MIT |
+| `chokidar` | 5.0.0 | MIT |
+| `ci-info` | 4.4.0 | MIT |
+| `clsx` | 2.1.1 | MIT |
+| `comma-separated-tokens` | 2.0.3 | MIT |
+| `commander` | 11.1.0 | MIT |
+| `common-ancestor-path` | 2.0.0 | BlueOak-1.0.0 |
+| `cookie` | 2.0.1 | MIT |
+| `cookie-es` | 1.2.3 | MIT |
+| `cross-spawn` | 7.0.6 | MIT |
+| `crossws` | 0.3.5 | MIT |
+| `css-select` | 6.0.0 | BSD-2-Clause |
+| `css-tree` | 2.2.1 | MIT |
+| `css-tree` | 3.2.1 | MIT |
+| `css-what` | 7.0.0 | BSD-2-Clause |
+| `csso` | 5.0.5 | MIT |
+| `defu` | 6.1.7 | MIT |
+| `dequal` | 2.0.3 | MIT |
+| `destr` | 2.0.5 | MIT |
+| `detect-libc` | 2.1.2 | Apache-2.0 |
+| `devalue` | 5.9.4 | MIT |
+| `devlop` | 1.1.0 | MIT |
+| `diff` | 9.0.0 | BSD-3-Clause |
+| `dom-serializer` | 2.0.0 | MIT |
+| `domelementtype` | 2.3.0 | BSD-2-Clause |
+| `domhandler` | 5.0.3 | BSD-2-Clause |
+| `domutils` | 3.2.2 | BSD-2-Clause |
+| `dset` | 3.1.4 | MIT |
+| `entities` | 4.5.0 | BSD-2-Clause |
+| `es-module-lexer` | 2.3.2 | MIT |
+| `esbuild` | 0.28.2 | MIT |
+| `eventemitter3` | 5.0.4 | MIT |
+| `eventsource` | 3.0.7 | MIT |
+| `eventsource-parser` | 3.1.1 | MIT |
+| `extend` | 3.0.2 | MIT |
+| `fast-string-truncated-width` | 3.0.3 | MIT |
+| `fast-string-width` | 3.0.2 | MIT |
+| `fast-wrap-ansi` | 0.2.2 | MIT |
+| `fdir` | 6.5.0 | MIT |
+| `find-proc` | 0.2.0 | MIT |
+| `flattie` | 1.1.1 | MIT |
+| `fontace` | 0.4.1 | MIT |
+| `fontkitten` | 1.0.3 | MIT |
+| `fsevents` | 2.3.3 | MIT |
+| `get-tsconfig` | 5.0.0-beta.4 | MIT |
+| `github-slugger` | 2.0.0 | ISC |
+| `h3` | 1.15.11 | MIT |
+| `hast-util-to-html` | 9.0.5 | MIT |
+| `hast-util-whitespace` | 3.0.0 | MIT |
+| `html-escaper` | 3.0.3 | MIT |
+| `html-void-elements` | 3.0.0 | MIT |
+| `http-cache-semantics` | 4.2.0 | BSD-2-Clause |
+| `iron-webcrypto` | 1.2.1 | MIT |
+| `is-docker` | 4.0.0 | MIT |
+| `is-plain-obj` | 4.1.0 | MIT |
+| `isexe` | 2.0.0 | ISC |
+| `jose` | 6.2.12 | MIT |
+| `js-yaml` | 4.3.2 | MIT |
+| `jsonc-parser` | 3.3.1 | MIT |
+| `lightningcss` | 1.33.0 | MPL-2.0 |
+| `lightningcss-darwin-arm64` | 1.33.0 | MPL-2.0 |
+| `lru-cache` | 11.5.3 | BlueOak-1.0.0 |
+| `magic-string` | 1.4.2 | MIT |
+| `magicast` | 0.5.5 | MIT |
+| `mdast-util-to-hast` | 13.2.1 | MIT |
+| `mdn-data` | 2.0.28 | CC0-1.0 |
+| `mdn-data` | 2.27.1 | CC0-1.0 |
+| `micromark-util-character` | 2.1.1 | MIT |
+| `micromark-util-encode` | 2.0.1 | MIT |
+| `micromark-util-sanitize-uri` | 2.0.1 | MIT |
+| `micromark-util-symbol` | 2.0.1 | MIT |
+| `micromark-util-types` | 2.0.3 | MIT |
+| `mrmime` | 2.0.1 | MIT |
+| `nanoid` | 3.3.19 | MIT |
+| `neotraverse` | 1.0.1 | MIT |
+| `nlcst-to-string` | 4.0.0 | MIT |
+| `node-fetch-native` | 1.6.7 | MIT |
+| `node-mock-http` | 1.0.5 | MIT |
+| `normalize-path` | 3.0.0 | MIT |
+| `nth-check` | 2.1.1 | BSD-2-Clause |
+| `obug` | 3.0.0 | MIT |
+| `ofetch` | 1.5.1 | MIT |
+| `ohash` | 2.0.12 | MIT |
+| `oniguruma-parser` | 0.12.2 | MIT |
+| `oniguruma-to-es` | 4.3.6 | MIT |
+| `p-limit` | 7.3.3 | MIT |
+| `p-queue` | 9.3.3 | MIT |
+| `p-timeout` | 7.0.2 | MIT |
+| `package-manager-detector` | 1.8.0 | MIT |
+| `path-key` | 3.1.1 | MIT |
+| `piccolore` | 0.1.3 | ISC |
+| `picocolors` | 1.1.1 | ISC |
+| `picomatch` | 2.3.2 | MIT |
+| `picomatch` | 4.0.7 | MIT |
+| `pkce-challenge` | 5.0.1 | MIT |
+| `postcss` | 8.5.28 | MIT |
+| `prismjs` | 1.30.0 | MIT |
+| `process-ancestry` | 0.1.0 | MIT |
+| `property-information` | 7.2.0 | MIT |
+| `radix3` | 1.1.2 | MIT |
+| `readdirp` | 5.1.1 | MIT |
+| `regex` | 6.1.0 | MIT |
+| `regex-recursion` | 6.0.2 | MIT |
+| `regex-utilities` | 2.3.0 | MIT |
+| `resolve-pkg-maps` | 1.0.0 | MIT |
+| `retext-smartypants` | 6.2.0 | MIT |
+| `rolldown` | 1.2.12 | MIT |
+| `satteri` | 0.10.5 | MIT |
+| `sax` | 1.6.1 | BlueOak-1.0.0 |
+| `semver` | 7.8.5 | ISC |
+| `sharp` | 0.35.5 | Apache-2.0 |
+| `shebang-command` | 2.0.0 | MIT |
+| `shebang-regex` | 3.0.0 | MIT |
+| `shiki` | 4.5.0 | MIT |
+| `sisteransi` | 1.0.5 | MIT |
+| `smol-toml` | 1.9.0 | BSD-3-Clause |
+| `source-map-js` | 1.2.2 | BSD-3-Clause |
+| `space-separated-tokens` | 2.0.2 | MIT |
+| `stringify-entities` | 4.0.4 | MIT |
+| `svgo` | 4.1.0 | MIT |
+| `tiny-inflate` | 1.0.3 | MIT |
+| `tinyclip` | 1.0.3 | MIT |
+| `tinyexec` | 1.3.1 | MIT |
+| `tinyglobby` | 0.2.17 | MIT |
+| `trim-lines` | 3.0.1 | MIT |
+| `trough` | 2.2.0 | MIT |
+| `ufo` | 1.6.4 | MIT |
+| `ultrahtml` | 1.7.0 | MIT |
+| `uncrypto` | 0.1.3 | MIT |
+| `undici` | 8.11.2 | MIT |
+| `unified` | 11.0.5 | MIT |
+| `unifont` | 0.7.5 | MIT |
+| `unist-util-is` | 6.0.1 | MIT |
+| `unist-util-position` | 5.0.0 | MIT |
+| `unist-util-stringify-position` | 4.0.0 | MIT |
+| `unist-util-visit` | 5.1.0 | MIT |
+| `unist-util-visit-parents` | 6.0.2 | MIT |
+| `unstorage` | 1.17.5 | MIT |
+| `verkit` | 0.4.1 | MIT |
+| `vfile` | 6.0.3 | MIT |
+| `vfile-message` | 4.0.3 | MIT |
+| `vite` | 8.3.2 | MIT |
+| `vitefu` | 1.1.3 | MIT |
+| `which` | 2.0.2 | ISC |
+| `xxhash-wasm` | 1.1.0 | MIT |
+| `yargs-parser` | 22.0.0 | ISC |
+| `yocto-queue` | 1.2.2 | MIT |
+| `zod` | 4.6.5 | MIT |
+| `zwitch` | 2.0.4 | MIT |

package/docs/evidence/UAN-022-package-portability.md

@@ -0,0 +1,54 @@
+# UAN-022 package installation portability (partial)
+
+Environment: research macOS host, Node 24.18.0, npm from that Node installation, local package version 0.0.0. The clean source baseline was commit cf499a8. These are fresh npm tarball installations with install scripts disabled for the isolated size comparison; representative examples use their normal standalone npm-ci harness.
+
+## Measured baseline and optional-peer change
+
+| Fresh consumer | Package tarball | Installed node_modules disk use | MCP server | Zod |
+| --- | ---: | ---: | --- | --- |
+| Baseline core/browser, hard dependencies | 115,834 bytes | 16,876 KiB | yes | yes |
+| Changed core/browser, no peer selected | 115,848 bytes | 764 KiB | no | no |
+| Changed browser with explicit Zod | same package | 9,000 KiB | no | yes |
+| Changed MCP with explicit server SDK | same package | 16,876 KiB | yes | yes |
+
+The changed core/browser installed tree contained 503,177 file bytes before this evidence page was added. The disk-use drop against the original baseline is about 95.5 percent. The npm tarball size is nearly unchanged because exports remain in one umbrella package; this result measures dependency installation rather than proving a smaller client bundle.
+
+The new npm run check:portability builds and packs the package, checks all exported files are present, installs a fresh core/browser consumer, imports both entrypoints, verifies that all optional peers remain absent, and caps installed file bytes at 2,000,000 (about four times the measured 503,177-byte baseline). A later run including the check script itself reported 115,864 tarball bytes and 503,276 installed file bytes.
+
+## Packed examples
+
+- E01 static Astro: 12 tests and static build passed; installed Zod for its schema and no MCP server.
+- E02 on-demand Astro: standalone live HTTP/MCP verification passed with an explicit MCP server.
+- E03 Next 16.3.8: two tests, official MCP route smoke, production build and browser secret boundary passed after declaring the MCP server directly.
+- E04 Worker sidecar: nine fixture tests, Wrangler dry-run bundle scan, and live official MCP client roundtrip passed after `sdkSchema()` began giving the Worker validator a mutable JSON copy. The first integrated CI run and the untouched cf499a8 research clone had returned HTTP 500 because the validator tried to annotate a frozen schema. Node 22/24 CI after this repair remains the integration gate.
+- E05 Node/Hono CLI: 12 tests, local/remote parity and CLI start passed with an explicit MCP server.
+- E06 browser-only: one test and Vite build passed; the emitted JS asset measured 86.17 kB / 25.78 kB gzip and the installed tree contained Zod but no MCP server.
+- E08 contract pack: nine tests and the independent demo passed; no MCP server or Zod installed.
+
+Node 24 typecheck and build, scoped Biome format, git diff check and production npm audit (zero reported vulnerabilities) passed. No full local root test suite was repeated for this slice.
+
+## Packed CLI and direct-license inventory (2026-10-03)
+
+The same fresh core/browser consumer now runs the package's CLI adapter in an application-owned process with no optional peers. A small fixture declares a read-only `smoke:greet@1` capability using the core schema port, then calls `runCapabilityCli`. On research macOS Node 24.18.0, the packed check passed `--help`, `--version`, a successful local typed-flag invocation, and an invalid-input exit-2 envelope. The local invocation measured about 30 ms wall time including Node process startup on this host; it is an observation, not a cross-platform budget. The package is a library with no `bin` entry, so there is no global `agent-native` command to test. E05 remains the representative application-owned local/remote CLI with Hono and explicit MCP/Zod peers.
+
+The check reported about 128 KB of tarball data and 555 KB of installed files for this fresh consumer; exact bytes change as included documentation changes. The installed package has zero hard runtime dependencies; MCP server, MCP Apps, Astro and Zod remained absent. Exact direct license metadata from the npm registry for this candidate's pinned optional peers:
+
+| Package | Version | Registry license |
+| --- | --- | --- |
+| @uppercut-labs/agent-native | 0.0.0 local tarball | MIT (`LICENSE` in tarball) |
+| @modelcontextprotocol/server | 2.3.0 | Apache-2.0 |
+| @modelcontextprotocol/ext-apps | 2.0.3 | MIT |
+| astro | 7.3.5 tested; peer range 7.x | MIT |
+| zod | 4.6.5 | MIT |
+
+This is a direct-package inventory, not a license review of every transitive dependency. The core/browser consumer installs no optional peer, so its runtime license set is the Agent Native tarball. Applications selecting framework/MCP/Zod integrations must inventory their actual resolved dependency tree.
+
+## Windows packed CLI smoke (2026-10-03)
+
+A tarball packed from canonical `72dab23` on research was copied to a fresh temporary Windows project whose path contains spaces (`Agent Native Windows CLI Smoke`). The project had its own `package.json` and npm used an explicit `--prefix` with `--omit=optional --ignore-scripts`. On Windows Node 24.18.0/npm 12.1.0, the 129,299-byte tarball installed 125 package files totaling 557,803 bytes. MCP, Astro and Zod optional peers were absent. Module resolution pointed inside that temporary project's `node_modules`.
+
+The application-owned packed CLI printed help and version, returned a successful `smoke:greet@1` local invocation (`Hello, Windows!`, exit 0), and returned a structured `invalid-input` envelope with exit 2 for a missing required argument. This is a Windows packed-library CLI adapter check, not a global `bin` command or a hosted remote CLI claim. The first attempted installation lacked a local manifest and npm selected the home project; the added dependency was uninstalled, its manifest and lockfile were verified free of Agent Native, and the prior `graceful-fs` package was present again. The reported result is from the subsequent explicitly isolated project.
+
+## Remaining qualification
+
+Windows packed CLI help/version/local invocation/invalid-input passed in an isolated path with spaces. Linux packed CLI will run in the Node 22/24 CI matrix once this change is integrated; the result must be checked there. Cold doctor timing, independent client bundle budgets, transitive dependency license review and outside-repository npm release installation remain open. One macOS timing sample is insufficient to set cross-platform performance thresholds. No npm publication or commercial host support is claimed.

package/docs/evidence/UAN-023-commercial-agent-hosts.md

@@ -0,0 +1,36 @@
+# UAN-023 commercial agent hosts over remote MCP
+
+Checked 2026-10-10 on macOS arm64 with Node 26.10.0. The server was the flagship E04 Worker sidecar on local workerd (Wrangler `dev --local`). It serves the shared E01 album contract over Streamable HTTP MCP at a loopback address. Each host ran from a temporary working directory under the operator's existing sign-in. No credential was added for this test.
+
+## Antigravity CLI: tool invocation verified
+
+The Antigravity CLI (`agy`, Google) ran with model `gemini-3.8-flash-low`. Its HTTP MCP server entry was added for the test with `agy mcp add` and removed afterwards.
+
+| Run | Host version | Observation |
+| --- | --- | --- |
+| Manual | 1.2.14 | Host listed `cap_15_example.catalog_12_album.lookup_v1`, called it through `call_mcp_tool` with `{"slug":"first-light"}`, received `{"result":{"kind":"found",…}}` and answered `First Light` |
+| `node test/uan023-agent-host.mjs agy` | 1.3.3 (auto-updated) | Same found call and answer. A second prompt sent the invalid slug `Not A Slug!` unchanged; the tool returned an error and no album |
+
+## Claude Code: tool invocation verified
+
+Claude Code 2.1.286 ran with an isolated `--mcp-config` and `--strict-mcp-config`, the tool allowlist limited to the probe server, and model `haiku`.
+
+- **Connection:** an earlier attempt that day reported the server `connected` and exposed exactly one tool, `mcp__albums__cap_15_example_catalog_12_album_lookup_v1`. That tool name is Claude Code's own sanitized projection. That attempt stopped before any model turn because the standalone CLI sign-in had expired.
+- **Invocation:** with the operator's Claude OAuth token supplied through `CLAUDE_CODE_OAUTH_TOKEN`, `node test/uan023-agent-host.mjs claude` passed. The host called the tool with `{"slug":"first-light"}` and answered `First Light`. The unchanged invalid slug `Not A Slug!` returned a tool result with `is_error: true` and no album.
+
+## Reproduce
+
+```sh
+npm ci
+npm run example:e04
+node test/uan023-agent-host.mjs agy
+CLAUDE_MODEL=haiku node test/uan023-agent-host.mjs claude
+```
+
+The script starts the sidecar on a free loopback port. For Antigravity it registers a temporary `uan-albums-probe` MCP server, runs the two prompts, asserts the actual tool calls from the host's `stream-json` events, and always removes the server and stops the Worker. It uses model inference on the operator's account, so it is not part of `npm run check`.
+
+## Limits
+
+- Each host version was observed once on one machine. Host model behavior may vary between runs.
+- The server ran on loopback. No deployed sidecar, external identity provider or protected capability was used.
+- MCP Apps UI rendering in these hosts was not tested; the rendered MCP Apps host evidence remains the [Inspector run](UAN-023-inspector-web-and-astro-adoption.md).