Expose installable NodeAgent runtime contracts and Pi AI adapter

.gitignore

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

README.md

@@ -81,6 +81,48 @@ npm run test           # full deterministic suite across modules, runtime, frame
 npm run build          # vite build, clean
 ```
 
+### Installable runtime and Pi AI provider
+
+The portable runtime is prepared for publishing under the collision-safe scoped
+package name `@homenshum/nodeagent`. Until the first release is published,
+install it from a pinned GitHub commit or local workspace. The unscoped
+`nodeagent` name belongs to another npm project and is not this repository.
+
+```bash
+# Until the first npm release, pin a reviewed GitHub commit:
+npm install github:HomenShum/NodeAgent#<commit-sha>
+
+# Optional live multi-provider route. NodeAgent still owns orchestration,
+# permissions, tools, durable state, and receipts.
+npm install @earendil-works/pi-ai
+```
+
+After the first scoped release, consumers can replace the GitHub specifier with
+`@homenshum/nodeagent`.
+
+Runtime consumers import the provider-neutral contracts from the package root
+or `@homenshum/nodeagent/runtime`. Pi AI is an optional peer and is loaded only
+when the adapter is used:
+
+```ts
+import { createPiAiAdapter } from "@homenshum/nodeagent/providers/pi-ai";
+
+const model = createPiAiAdapter({
+  provider: "openrouter",
+  model: "openai/gpt-4.1-mini",
+});
+
+const step = await model.next({
+  system: "Use typed tools and return inspectable work.",
+  messages: [{ role: "user", content: "Inspect the attached artifact." }],
+});
+```
+
+Pi AI resolves provider credentials at runtime and returns exact provider usage
+and cost information. Do not place keys in manifests, source, traces, or setup
+receipts. Current Pi AI releases require Node 22.19 or newer when this optional
+adapter is executed; the deterministic NodeAgent core remains usable without Pi.
+
 `nodeagent:frame:smoke` proves the Fable-like bounded frame path:
 `ReasoningFrame -> runNodeAgent -> FrameDelta -> verifier receipt`.
 `nodeagent:durable:smoke` proves the provider-neutral durable path:

nodekit.yaml

@@ -7,7 +7,9 @@ commandProfile: application
 
 canonicalFor:
   - nodeagent.agent-run
+  - nodeagent.event-protocol
   - nodeagent.policy-context
+  - nodeagent.provider-pi
 
 consumes:
   - nodeplatform.repo-contract
@@ -38,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
@@ -46,5 +52,9 @@ contractDeclarations:
     signature: policy-context
     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: []