Preserve runtime completion and packaged CLI contracts

.gitignore

@@ -11,6 +11,7 @@ node_modules/
 # Build output
 dist/
 build/
+lib/
 *.tsbuildinfo
 
 # --- Secrets / environment (CRITICAL) ---

HANDOFF.md

@@ -1,6 +1,24 @@
 # NodeAgent developer handoff
 
-Read this file first, then [the runtime walkthrough](docs/START_HERE.md). The current consumer/recovery repair merged in PR4 at canonical `5362505`; the source-header follow-on below starts from that exact revision. The separately preserved Pi draft is not integrated. Independent source and installed-consumer review passes for the bounded slice below. The [portable judgment](evidence/current-consumer-20260905/judge/E6e_NODEAGENT_CURRENT_CONSUMER_FINAL_JUDGE.md.txt), manifest and Git history identify the reviewed implementation and its later publication metadata.
+## Current runtime salvage on main 6112cabe
+
+This candidate selectively integrates the preserved runtime/event/Pi seam onto current main `6112cabe1f56a6279890206e35d03b9e339c02f5`. It retains the current chat, graph, scripts, templates, tours and security overrides. The original primary draft and branch are preserved separately. Read [the packed runtime instructions](README.md#packed-runtime-and-optional-pi-adapter) for the current scoped package name, CLI template paths, optional peer and completion/error/cost contract.
+
+Use Node 22.19 or newer, `npm ci`, `npm run check`, then `npm pack`. The normal check retains its existing missing-credential skips for Convex/live-provider paths; a skipped provider check is not provider proof. Its generated JSON receipts belong to the run that wrote them. Historical checked-in smoke receipts and the evidence packets below retain their original source identities. Fresh run logs, exact source bindings, packed-consumer results and failed attempts are retained separately for independent review.
+
+The adapter's original fulfilled-result assumption confused terminal SDK failure with successful completion. Its new public contract accepts only natural completion without tools as `done`. Real SDK 0.80.10 event streams now cover failure, abort, truncation, callback failure and bounded concurrent/repeated requests using injected local ports. Runtime and adapter entrypoints are ESM with declarations. The optional SDK is not loaded by the root/runtime import. The package allowlist includes both existing CLI templates and the chat template lock; no npm publication is performed by this work.
+
+The actual 2026-09-07 local proof passed the normal check once: 57 tests across nine files, typecheck, library/UI builds, frame/durable/SQLite, both scaffold smokes, three tours/36 steps/11 citations and a zero-finding production audit. The full development install still reported nine advisories (three moderate, five high, one critical). Convex was not configured, live-provider work skipped, and the official Omnigent CLI was absent; the separate npm `omniagent` probe passed.
+
+The actual tarball has 37 exact source/build members, including all 15 chat and 11 dashboard template files, the chat lock and npm's three automatically included ancestor READMEs. Its SHA-256 is `02c71cb9bb0389f4b74cae22749da3335560873c22bee46e116b3c285343849f`. The final tarball is a documentation-only successor, SHA-256 `3c0b306137e2f5e4cade8619305186837013c9d2eafa40dceb6d8d0a70b6eea0`: only its README install instructions changed (chat `npm ci`, dashboard first `npm install`). Its other 36 members are byte-exact to the executed consumer tarball; that executable proof is carried forward, and the final README is separately reviewed. Both fresh installs reported zero audit findings. One installed consumer verified root/runtime imports with the optional peer absent, a typed missing-peer error, doctor and both exact scaffold copies. A separate exact-Pi consumer exercised ten concurrent and ten repeated completion/tool/truncation/error/abort outcomes using the actual built adapter and SDK stream primitive. Source scenarios also covered caller abort and rejected text callbacks. These are local fixture outcomes, with zero provider requests, not provider or production-load proof.
+
+This slice does not change the UI's response-recovery semantics or assess its pixels again. Existing graph/readability/accessibility, development-advisory, human, provider and deployment limits below remain. A passed local source or packed-consumer check cannot establish production readiness or a full grade.
+
+---
+
+# Historical consumer and UI handoff
+
+Read this file first, then [the runtime walkthrough](docs/START_HERE.md). The current consumer/recovery repair merged in PR4 at canonical `5362505`; the source-header follow-on below starts from that exact revision. At that historical checkpoint, the separately preserved Pi draft was not integrated. Independent source and installed-consumer review passes for the bounded slice below. The [portable judgment](evidence/current-consumer-20260905/judge/E6e_NODEAGENT_CURRENT_CONSUMER_FINAL_JUDGE.md.txt), manifest and Git history identify the reviewed implementation and its later publication metadata.
 
 A developer can run the repository's local scenario and generate a separate chat application without credentials. Both chats use scripted local adapters; displayed confidence numbers come from fixtures. Their browser conversations reset on reload. The library's durable/SQLite demonstration is a separate integration and does not persist either browser chat.
 

README.md

@@ -478,3 +478,35 @@ module that borrows the pattern cites it in its header comment.
 ## License
 
 MIT © [Homen Shum](https://github.com/homenshum)
+
+
+## Packed runtime and optional Pi adapter
+
+The source package is `@homenshum/nodeagent`. From this checkout, use Node 22.19 or newer, `npm ci`, then `npm pack`. Packing runs the library build; the tarball includes the ESM/type entrypoints, CLI and both existing app templates. It intentionally excludes source UI, private evidence and development tools. This local package workflow does not publish an npm release.
+
+In a fresh directory, run `npm init -y` and `npm install "<absolute path to the generated .tgz>"`. The root and `@homenshum/nodeagent/runtime` entrypoints work without the optional Pi peer:
+
+```js
+import { createNodeAgentEvent } from "@homenshum/nodeagent/runtime";
+const event = createNodeAgentEvent({
+  eventId: "review-1", runId: "local-1", sequence: 0,
+  type: "review.started", occurredAt: "2026-09-07T00:00:00Z",
+  payload: { artifact: "local-example" },
+});
+```
+
+The packaged CLI is separate from the repository's richer developer CLI. These commands copy local templates without installing or starting the generated apps:
+
+```powershell
+node node_modules/@homenshum/nodeagent/bin/nodeagent.mjs doctor
+node node_modules/@homenshum/nodeagent/bin/nodeagent.mjs apps scaffold chat-ui --dir "../NodeAgent Chat"
+node node_modules/@homenshum/nodeagent/bin/nodeagent.mjs apps scaffold local-dashboard --dir "../NodeAgent Dashboard"
+```
+
+The chat template includes a lockfile: use `npm ci` in the generated chat directory. The dashboard template has no checked-in lockfile: use `npm install` for its first install and retain the generated lock for later `npm ci` runs. Follow each template's README for its demo, smoke and build commands; `--auto` on scaffold performs the existing install/demo/verification sequence. The examples use local scripted adapters, not external providers.
+
+For the optional adapter, explicitly install `@earendil-works/pi-ai@0.80.10` (requires Node >=22.19), then import `createPiAiAdapter` and `PiAiAdapterError` from `@homenshum/nodeagent/providers/pi-ai`. Calling an adapter with its default loader can use provider credentials and network; injected `models`/`loadModels` ports support offline consumers. NodeAgent delegates provider auth, transport, timeouts and retries to Pi. It does not automatically invoke the adapter from the existing chat UI or execute returned tool calls.
+
+`next()` reports `done: true` only for a natural `stop` without tool calls. `length` (truncated output) and `toolUse` remain incomplete. SDK terminal `error` and `aborted` messages reject with `PiAiAdapterError` (`provider_error` or `aborted`), retaining `stopReason` and reported usage. Thrown provider failures preserve their cause. A text consumer failure rejects with `callback_error`; streaming failure aborts that call and ends its event stream. Deltas already delivered cannot be withdrawn, and cancellation is not rollback of tools or external effects. No automatic retry is added.
+
+Token counts are passed through from Pi. `costUsd` is Pi's model-rate calculation and is labelled `costKind: "estimated"`, including configured zero rates; it is not a provider invoice or an invented minimum price. Missing optional peer/model failures remain typed errors. Offline SDK scenarios exercise actual event-stream primitives with injected responses; they do not certify provider availability, billing, production concurrency or whole-product readiness.

nodekit.yaml

@@ -40,6 +40,10 @@ proof:
   receiptSchema: null
 
 contractDeclarations:
+  - concept: nodeagent.event-protocol
+    signature: nodeagent.event/v1
+    path: src/features/node-agent/protocol/events.ts
+    mode: canonical
   - concept: nodeagent.agent-run
     signature: agent-run-result
     path: src/features/node-agent/types/nodeAgentTypes.ts
@@ -49,4 +53,9 @@ contractDeclarations:
     path: src/features/node-agent/runtime/durableRuntime.ts
     mode: canonical
 
+  - concept: nodeagent.provider-pi
+    signature: agent-model-adapter
+    path: src/features/node-agent/providers/piAiAdapter.ts
+    mode: canonical
+
 architectureExceptions: []