@inneranimalmedia/agentsam-sdk 2.6.8 → 2.6.10

package/docs/architecture/HOOKS-MODELS-SELF-HOSTING-PLAN.md

@@ -0,0 +1,199 @@
+# Hooks, model inventory, and self-hosting plan
+
+Status: active implementation plan (2026-10-02)
+
+## Decisions
+
+### Hooks are one runtime concept
+
+AgentSam has one lifecycle event catalog, one output merge algorithm, and one
+receipt format. It has multiple **authoring sources**, not multiple kinds of
+hook:
+
+| Source | Authored in | Dashboard/CLI behavior | Durable definition row |
+|---|---|---|---|
+| `code` | SDK registration | visible, read-only | no |
+| `config` | `agentsam.hooks.json` or `.agentsam/hooks.json` | visible, file-owned | no |
+| `stored` | CLI/API/dashboard | visible and mutable | `agentsam_hook` |
+| `system` | AgentSam runtime | visible, read-only | only when a host intentionally materializes it |
+
+React hooks (`useAgentHooks`, `useHookList`) are UI implementation details and
+must never be called lifecycle hooks in product copy.
+
+Dispatch order is priority, then hook key. Source does not create a second
+semantics path. A source badge answers where to edit a definition. Execution
+receipts from all sources go to the same `agentsam_hook_execution` projection.
+
+### Portable ownership is owner + optional scope
+
+The portable hook schema deliberately has no `tenant_id`, `workspace_id`,
+`user_id`, `person_uuid`, or installation-specific foreign keys.
+
+- `owner_id` is an opaque host/account/local owner key.
+- `scope_type` is `global`, `account`, `repository`, `project`, or `session`.
+- `scope_ref` contains the corresponding opaque id/path when needed.
+- `agent_run_id`, `session_id`, and `conversation_id` are the common execution
+  correlations.
+- Rare correlations (plan, todo, workflow run, command run, route) belong in
+  `correlation_json`, not a permanently sparse column set.
+- `workflow_id` is a soft reference on the definition. The hook pack remains
+  installable without a workflow table family.
+- Handler credentials are references resolved by the host. They are never
+  values in `handler_config_json`.
+
+The canonical fresh-install SQL is
+`migrations/runtime/0005_agentsam_hooks.sql`. The standalone hooks package
+ships a generated byte-identical copy plus `schema/manifest.json`.
+
+Existing hosted tables with required `user_id` or tenant/workspace columns are
+**not** silently rebuilt. The hosted owner must inspect references and run an
+explicit copy/verify/swap migration. Portable initialization is idempotent and
+will not guess that `user_id` equals an account owner.
+
+### The existing model surfaces keep their jobs
+
+No new per-model-per-user table is introduced.
+
+| Existing surface | Authority |
+|---|---|
+| `src/models/catalog.js` / hosted `agentsam_model_catalog` | curated provider-qualified reference capabilities; never credential availability |
+| `agentsam_model_pricing` | global/versioned reference pricing |
+| `agentsam_plugins` with `plugin_kind='ai'` | one installation per account/environment/provider/credential reference; health and last good credential-scoped model snapshot |
+| `user_secrets` / machine vault | provider secret material; never model metadata |
+| `agentsam_api_credentials` | authentication to AgentSam itself; never provider keys |
+| `agentsam_model_eval_observations` | eval evidence; not a portable customer model catalog |
+
+A successful provider probe writes a compact
+`agentsam.provider-model-snapshot.v1` object into the AI plugin row's
+`metadata_json.model_snapshot`. It contains sorted model ids, count, hash, and
+fetch time. `recordAiPluginModelDiscovery` writes it through the existing
+plugin registry and health-check log. A failed probe updates health evidence
+but preserves the last good snapshot. Secret values and hashes of secret values
+are never included.
+
+The provider API remains the availability authority at use time. A snapshot is
+stale-while-revalidate evidence for UI convenience, not an authorization gate.
+Reference catalog enrichment is never an availability claim. Unknown models
+continue to work with unknown/reference capabilities where the adapter can use
+them.
+
+Provider/model identity is the pair `(provider, provider_model_id)`. The SDK's
+`model_key` already encodes that pair (`openai:gpt-…`, `cursor:…`). Hosted SQL
+must use `UNIQUE(provider, model_key)` (or a provider-qualified `model_key`),
+not global `UNIQUE(model_key)`. Provider ids should match SDK canonical ids:
+`openai`, `anthropic`, `gemini`, `xai`, `cursor`, `cloudflare`, and `ollama`.
+Display names are not ids.
+
+## Product and CLI experience
+
+`agentsam hooks` and `/hooks` are the factual control surface:
+
+- `status` — source counts, project config, and stored registry health.
+- `list` — merged dispatch order with source, handler, state, and priority.
+- `executions` — recent value-free receipts and redacted failures.
+- `validate` — portable config validation.
+- `init` — idempotently creates `.agentsam/hooks.json`.
+- `enable` / `disable` — toggles stored definitions only.
+
+The dashboard should consume the same status/list/execution projection. It must
+not maintain a second event list or merge algorithm. Code rows are read-only;
+config rows link to their source file; stored rows expose full editing. A future
+priority/disable override for code hooks must be an explicit overlay keyed by
+`(owner_id, source_kind, hook_key)`, not a copied code definition.
+
+The model picker follows a similar provenance rule:
+
+1. show models discovered for the selected plugin/credential installation;
+2. enrich from the global catalog when a provider-qualified match exists;
+3. label every limit/capability as provider, reference, or unknown;
+4. keep pinned/default visibility in the AI plugin's `config_json`;
+5. never write discovered ids into the global catalog.
+
+## Dogfooding matrix
+
+| Runtime point | Hook event | Current owner |
+|---|---|---|
+| interactive shell open/close | `session_start`, `session_end` | CLI shell |
+| submitted/transformed input | `user_prompt_submitted`, `user_prompt_transformed` | provider-neutral runner |
+| paid inference boundaries | `pre_model_use`, `post_model_use` | provider adapter |
+| capability side effects | `pre_tool_use`, `post_tool_use`, `post_tool_use_failure` | capability adapter |
+| provider/tool failures | `error_occurred` | provider/capability adapters |
+| autonomous continuation | `agent_stop` | runner with bounded continuation count |
+| delegated work | `subagent_start`, `subagent_stop` | delegated-agent adapter |
+
+The interactive CLI loads code, project config, and active stored hooks into the
+same runtime. `session_start.modified_config` may override the session's model,
+reasoning, service tier, and compaction preference; arbitrary process or path
+configuration is not applied. Session context is injected through normal
+context items. Every invocation uses the same receipt observer and local
+execution table.
+
+`session_end` remains best effort. Handlers must be idempotent, and durable
+cleanup must eventually be backed by an idle-session sweeper rather than an
+assumption that a process always exits normally.
+
+## Delivery sequence
+
+### Phase 1 — portable core (implemented in this change)
+
+- Canonical portable hook tables and schema-pack manifest.
+- Generic injected-SQL hook store for SQLite/D1-shaped adapters.
+- Stored/config/code source merging.
+- CLI `/hooks` discovery and value-free execution history.
+- Actual shell/runner dogfooding, including session and transformed-prompt
+  events.
+- Compact AI plugin model snapshot contract and existing-plugin persistence API with last-good preservation.
+
+### Phase 2 — hosted compatibility migration
+
+1. Inventory every FK/view/query referencing hosted `agentsam_hook` and
+   `agentsam_hook_execution`.
+2. Create `_v2` tables from the portable columns plus host-required indexes.
+3. Map `owner_id` from the hosted account authority; do not infer it from a
+   tenant/workspace label.
+4. Move legacy handler fields into `handler_config_json` and legacy correlation
+   fields into `correlation_json`.
+5. Validate row counts, active definitions, orphan references, JSON validity,
+   and sampled execution history.
+6. Swap in one transaction where supported; retain a rollback table until
+   production verification completes.
+7. Add the dashboard API only after ownership checks are enforced by the host.
+
+### Phase 3 — shared dashboard projection
+
+- Expose merged definitions and receipts through an injected HookRegistry API.
+- Add source badges, event filters, dry-run input, and last-failure state.
+- Add stored-hook create/edit with handler-specific forms.
+- Add explicit code-hook overrides without copying handler definitions.
+- Reuse the protocol conformance fixtures in UI/API integration tests.
+
+### Phase 4 — model snapshot persistence
+
+- Apply `createAiPluginProbePatch` in the hosted provider probe transaction.
+- Compare `models_hash`; avoid writes when the snapshot is unchanged.
+- Refresh stale snapshots in the background and through `agentsam models
+  --refresh` without blocking startup.
+- Keep last good ids on auth/network failures and expose health separately.
+- Add retention only to probe history, not the last good plugin snapshot.
+
+### Phase 5 — lifecycle reliability
+
+- Add stale-session sweep and idempotent cleanup jobs.
+- Add execution retention/compaction policy.
+- Add local↔remote receipt sync by immutable execution id where explicitly
+  enabled; never sync secrets or full prompt/tool values.
+- Run JSON conformance fixtures in JavaScript, Python, Go, and Rust CI.
+
+## Acceptance checks
+
+- Fresh SQLite and D1-shaped installs produce the same hook tables.
+- No portable hook query requires tenant/workspace/user tables.
+- A prompt value or tool result value cannot be found in a hook receipt row.
+- Config and stored hooks execute in one deterministic priority order.
+- The CLI lists every active source that can affect a turn.
+- A provider probe with 1,000 model ids produces one AI plugin metadata update,
+  not 1,000 catalog rows.
+- Failed model refreshes preserve the last successful model id list.
+- A catalog miss never blocks a provider-verified model solely because the
+  reference package is older.
+- Provider and AgentSam credentials remain separate authorities.

package/examples/hyperspace-demo/index.html

@@ -0,0 +1,16 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>AgentSam — Computational Hyperspace</title>
+    <style>
+      html, body, #root { margin: 0; height: 100%; background: #000; }
+      * { box-sizing: border-box; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/examples/hyperspace-demo/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "hyperspace-demo",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build"
+  },
+  "dependencies": {
+    "@inneranimalmedia/agentsam-loading-scene": "*",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.2.0",
+    "vite": "^8.2.0"
+  }
+}

package/examples/hyperspace-demo/src/main.tsx

@@ -0,0 +1,160 @@
+import { StrictMode, useEffect, useMemo, useState } from "react";
+import { createRoot } from "react-dom/client";
+import {
+  LoadingSceneController,
+  computationalHyperspace,
+  adaptAgentSamEvent,
+} from "@inneranimalmedia/agentsam-loading-scene";
+import {
+  LoadingScene,
+  LoadingSceneStatus,
+  LoadingSceneDevtools,
+} from "@inneranimalmedia/agentsam-loading-scene/react";
+
+const preset = computationalHyperspace;
+
+/**
+ * Simulated "create a site" run: realistic runtime events flow through
+ * the adapter → controller, exactly as a real CMS app would wire it.
+ * The renderer never sees any of these names.
+ */
+function simulateSiteCreation(controller: LoadingSceneController, onDone: () => void) {
+  const timeline: Array<[number, () => void]> = [];
+  const at = (ms: number, fn: () => void) => timeline.push([ms, fn]);
+  const ev = (raw: Parameters<typeof adaptAgentSamEvent>[0]) =>
+    controller.handle(adaptAgentSamEvent(raw));
+
+  at(0, () => ev({ type: "agent.session.started", operationId: "session", label: "Starting up" }));
+  at(900, () => controller.complete("session"));
+
+  at(1000, () => ev({ type: "context.workspace.loading", operationId: "ctx", label: "Gathering context" }));
+  // 19 rapid file reads — coalesced, no flicker
+  for (let i = 0; i < 19; i++) {
+    at(1200 + i * 60, () => ev({ type: "file.read", label: "Understanding your project" }));
+  }
+  at(2600, () => controller.complete("ctx"));
+
+  at(2700, () => ev({ type: "model.planning", operationId: "plan", label: "Planning your site" }));
+  at(5200, () => controller.complete("plan"));
+
+  // parallel tools + asset generation blending
+  at(5300, () => ev({ type: "tool.invoke", operationId: "t1", label: "Laying out pages" }));
+  at(5450, () => ev({ type: "tool.invoke", operationId: "t2", label: "Writing copy" }));
+  at(5600, () => ev({ type: "tool.image.generate", operationId: "hero", label: "Generating hero artwork" }));
+  at(9400, () => controller.complete("t1"));
+  at(10200, () => controller.complete("t2"));
+  at(12500, () => ev({ type: "content.asset.generated", operationId: "hero", label: "Hero artwork ready" }));
+
+  at(12800, () => ev({ type: "catalog.indexing", operationId: "idx", label: "Organizing your content" }));
+  at(15200, () => controller.complete("idx"));
+
+  at(15400, () => ev({ type: "site.build", operationId: "build", label: "Building your site", progress: 0 }));
+  at(16500, () => ev({ type: "site.build", operationId: "build", progress: 0.35 }));
+  at(17800, () => ev({ type: "site.build", operationId: "build", progress: 0.8 }));
+  at(18900, () => controller.complete("build"));
+
+  at(19000, () => ev({ type: "output.verify", operationId: "verify", label: "Checking everything" }));
+  at(21500, () => controller.complete("verify"));
+
+  at(21700, () => ev({ type: "site.deploy", operationId: "deploy", label: "Publishing" }));
+  at(24800, () => {
+    controller.complete("deploy");
+    onDone();
+  });
+
+  const ids = timeline.map(([ms, fn]) => window.setTimeout(fn, ms));
+  return () => ids.forEach((id) => window.clearTimeout(id));
+}
+
+function EditorSurface() {
+  return (
+    <div
+      style={{
+        height: "100%",
+        display: "grid",
+        gridTemplateRows: "56px 1fr",
+        color: "#d5d7e0",
+        fontFamily: "system-ui, sans-serif",
+      }}
+    >
+      <header
+        style={{
+          borderBottom: "1px solid rgba(255,255,255,0.08)",
+          display: "flex",
+          alignItems: "center",
+          padding: "0 20px",
+          gap: 16,
+          fontSize: 13,
+          letterSpacing: "0.06em",
+        }}
+      >
+        <strong style={{ color: "#8b7db7" }}>AgentSam</strong>
+        <span style={{ opacity: 0.5 }}>Fuel N Free Time — Home</span>
+        <span style={{ marginLeft: "auto", opacity: 0.4, fontSize: 12 }}>Draft saved</span>
+      </header>
+      <main style={{ padding: 32, display: "grid", gap: 20, alignContent: "start" }}>
+        <div style={{ height: 220, borderRadius: 10, background: "linear-gradient(135deg, rgba(139,125,183,0.18), rgba(104,117,173,0.1))", border: "1px solid rgba(255,255,255,0.07)", display: "flex", alignItems: "center", justifyContent: "center", fontSize: 14, opacity: 0.8 }}>
+          Hero section — generated artwork placed here
+        </div>
+        <div style={{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(180px, 1fr))", gap: 16 }}>
+          {["Collection grid", "Countdown banner", "Newsletter"].map((s) => (
+            <div key={s} style={{ height: 110, borderRadius: 8, border: "1px solid rgba(255,255,255,0.07)", background: "rgba(255,255,255,0.02)", display: "flex", alignItems: "center", justifyContent: "center", fontSize: 13, opacity: 0.65 }}>
+              {s}
+            </div>
+          ))}
+        </div>
+      </main>
+    </div>
+  );
+}
+
+function App() {
+  const controller = useMemo(() => new LoadingSceneController(preset), []);
+  const [run, setRun] = useState(0);
+  const debug = new URLSearchParams(window.location.search).get("debugRuntimeVisuals") === "1";
+
+  useEffect(() => {
+    if (debug) return; // devtools drive the controller instead
+    return simulateSiteCreation(controller, () => undefined);
+  }, [controller, run, debug]);
+
+  return (
+    <div style={{ position: "fixed", inset: 0 }}>
+      <LoadingScene controller={controller} preset={preset} style={{ width: "100%", height: "100%" }}>
+        <EditorSurface />
+      </LoadingScene>
+      <div style={{ position: "fixed", left: 24, bottom: 24, pointerEvents: "none" }}>
+        <LoadingSceneStatus controller={controller} preset={preset} />
+      </div>
+      {!debug && (
+        <button
+          onClick={() => {
+            controller.reset();
+            setRun((r) => r + 1);
+          }}
+          style={{
+            position: "fixed",
+            top: 16,
+            right: 16,
+            background: "rgba(255,255,255,0.05)",
+            border: "1px solid rgba(255,255,255,0.12)",
+            borderRadius: 6,
+            color: "#9ea1b0",
+            padding: "6px 12px",
+            fontSize: 12,
+            cursor: "pointer",
+          }}
+        >
+          Replay
+        </button>
+      )}
+      <LoadingSceneDevtools controller={controller} enabled={debug} />
+    </div>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);

package/examples/hyperspace-demo/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src"]
+}

package/examples/hyperspace-demo/vite.config.ts

@@ -0,0 +1,24 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import path from "node:path";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    host: "0.0.0.0",
+    port: 5181,
+    allowedHosts: true,
+  },
+  resolve: {
+    alias: {
+      "@inneranimalmedia/agentsam-loading-scene/react": path.resolve(
+        __dirname,
+        "../../packages/agentsam-loading-scene/src/react/index.ts",
+      ),
+      "@inneranimalmedia/agentsam-loading-scene": path.resolve(
+        __dirname,
+        "../../packages/agentsam-loading-scene/src/index.ts",
+      ),
+    },
+  },
+});

package/migrations/runtime/0005_agentsam_hooks.sql

@@ -0,0 +1,87 @@
+-- Portable AgentSam hook registry and execution evidence.
+--
+-- This is the standalone/local baseline. Shared hosts may map owner_id to their
+-- account authority, but tenant_id/workspace_id are intentionally not part of
+-- the portable contract. Repository/project/session applicability belongs in
+-- scope_type + scope_ref; less common correlations stay in JSON.
+--
+-- Handler secrets are references resolved by the host. Never store API keys,
+-- bearer tokens, or decrypted credentials in handler_config_json or receipts.
+
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS agentsam_hook (
+  id TEXT PRIMARY KEY DEFAULT ('hook_' || lower(hex(randomblob(8)))),
+  owner_id TEXT NOT NULL DEFAULT 'local',
+  hook_key TEXT NOT NULL CHECK(length(trim(hook_key)) > 0 AND hook_key = trim(hook_key)),
+  event_type TEXT NOT NULL CHECK(length(trim(event_type)) > 0 AND event_type = trim(event_type)),
+  source_kind TEXT NOT NULL DEFAULT 'stored'
+    CHECK(source_kind IN ('stored','config','code','system')),
+  scope_type TEXT NOT NULL DEFAULT 'project'
+    CHECK(scope_type IN ('global','account','repository','project','session')),
+  scope_ref TEXT,
+  handler_type TEXT NOT NULL DEFAULT 'log_only'
+    CHECK(length(trim(handler_type)) > 0 AND handler_type = trim(handler_type)),
+  handler_config_json TEXT NOT NULL DEFAULT '{}'
+    CHECK(json_valid(handler_config_json)),
+  match_json TEXT NOT NULL DEFAULT '{}'
+    CHECK(json_valid(match_json)),
+  failure_mode TEXT NOT NULL DEFAULT 'open'
+    CHECK(failure_mode IN ('open','closed','error')),
+  priority INTEGER NOT NULL DEFAULT 100,
+  timeout_ms INTEGER NOT NULL DEFAULT 30000
+    CHECK(timeout_ms BETWEEN 1 AND 600000),
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK(is_active IN (0,1)),
+  workflow_id TEXT,
+  description TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}'
+    CHECK(json_valid(metadata_json)),
+  revision INTEGER NOT NULL DEFAULT 1 CHECK(revision >= 1),
+  created_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_agentsam_hook_identity
+  ON agentsam_hook(owner_id, scope_type, IFNULL(scope_ref, ''), hook_key);
+CREATE INDEX IF NOT EXISTS idx_agentsam_hook_dispatch
+  ON agentsam_hook(owner_id, event_type, is_active, priority, hook_key);
+CREATE INDEX IF NOT EXISTS idx_agentsam_hook_scope
+  ON agentsam_hook(owner_id, scope_type, scope_ref, is_active);
+
+CREATE TABLE IF NOT EXISTS agentsam_hook_execution (
+  id TEXT PRIMARY KEY DEFAULT ('hexec_' || lower(hex(randomblob(8)))),
+  owner_id TEXT NOT NULL DEFAULT 'local',
+  hook_id TEXT,
+  hook_key TEXT NOT NULL,
+  source_kind TEXT NOT NULL DEFAULT 'stored'
+    CHECK(source_kind IN ('stored','config','code','system')),
+  event_type TEXT NOT NULL,
+  invocation_id TEXT,
+  agent_run_id TEXT,
+  session_id TEXT,
+  conversation_id TEXT,
+  status TEXT NOT NULL
+    CHECK(status IN ('completed','failed','timeout','skipped','blocked')),
+  duration_ms INTEGER NOT NULL DEFAULT 0 CHECK(duration_ms >= 0),
+  input_keys_json TEXT NOT NULL DEFAULT '[]' CHECK(json_valid(input_keys_json)),
+  output_keys_json TEXT NOT NULL DEFAULT '[]' CHECK(json_valid(output_keys_json)),
+  decision TEXT,
+  reason TEXT,
+  error_code TEXT,
+  error_message TEXT,
+  receipt_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(receipt_json)),
+  correlation_json TEXT NOT NULL DEFAULT '{}' CHECK(json_valid(correlation_json)),
+  ran_at_unix INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_hook_execution_hook
+  ON agentsam_hook_execution(owner_id, hook_key, ran_at_unix DESC);
+CREATE INDEX IF NOT EXISTS idx_agentsam_hook_execution_run
+  ON agentsam_hook_execution(agent_run_id, ran_at_unix DESC)
+  WHERE agent_run_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agentsam_hook_execution_session
+  ON agentsam_hook_execution(session_id, ran_at_unix DESC)
+  WHERE session_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agentsam_hook_execution_failure
+  ON agentsam_hook_execution(owner_id, status, ran_at_unix DESC)
+  WHERE status IN ('failed','timeout','blocked');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.6.8",
+  "version": "2.6.10",
   "description": "Portable AgentSam SDK and CLI kits for local scaffolding, repository intelligence, incremental indexing, identity adapters, and verified dependency maintenance.",
   "type": "module",
   "main": "./src/index.js",
@@ -90,6 +90,7 @@
     "./work-graph/adapters/business/projects": "./packages/work-graph/src/adapters/business/projects.js",
     "./errors": "./src/errors/index.js",
     "./errors/schema": "./protocol/errors/error-envelope.schema.json",
+    "./errors/schema-v2": "./protocol/errors/agentsam.error.v2.schema.json",
     "./errors/catalog": "./protocol/errors/error-catalog.json",
     "./cloudflare": "./src/cloudflare/index.js",
     "./eval": "./src/eval/index.js",
@@ -119,7 +120,21 @@
     "./theme/harbor": "./packages/theme-insurance-site/src/index.js",
     "./theme/summit": "./packages/theme-shinshu-site/src/index.js",
     "./models/inventory": "./src/models/inventory-core.js",
-    "./goap": "./packages/agentsam-goap/src/index.js"
+    "./models/provider-snapshot-schema": "./protocol/models/provider-model-snapshot.v1.schema.json",
+    "./local-engine": "./src/local-engine/index.js",
+    "./local-engine/contracts": "./src/local-engine/contracts.js",
+    "./local-engine/audit": "./src/local-engine/audit.js",
+    "./local-engine/assets": "./src/local-engine/assets.js",
+    "./local-engine/benchmark": "./src/local-engine/benchmark.js",
+    "./goap": "./packages/agentsam-goap/src/index.js",
+    "./hooks": "./packages/agentsam-hooks/src/index.js",
+    "./hooks/store": "./packages/agentsam-hooks/src/store.js",
+    "./hooks/protocol/input": "./protocol/hooks/agentsam.hook.v1.schema.json",
+    "./hooks/protocol/output": "./protocol/hooks/agentsam.hook.output.v1.schema.json",
+    "./hooks/protocol/config": "./protocol/hooks/agentsam.hooks.config.v1.schema.json",
+    "./hooks/protocol/receipt": "./protocol/hooks/agentsam.hook.receipt.v1.schema.json",
+    "./hooks/schema/manifest": "./packages/agentsam-hooks/schema/manifest.json",
+    "./hooks/schema/sqlite": "./migrations/runtime/0005_agentsam_hooks.sql"
   },
   "bin": {
     "agentsam": "bin/agentsam",
@@ -127,7 +142,8 @@
     "agentsam-scaffold": "bin/scaffold.mjs",
     "agentsam-auth-portal": "packages/identity/scripts/preview-auth-portal.mjs",
     "agentsam-rapid-rust": "bin/agentsam-rapid-rust",
-    "agentsam-rust": "bin/agentsam-rapid-rust"
+    "agentsam-rust": "bin/agentsam-rapid-rust",
+    "agentsam-hooks": "packages/agentsam-hooks/bin/agentsam-hooks.mjs"
   },
   "files": [
     "src",
@@ -137,6 +153,7 @@
     "packages/agentsam-brand/bin",
     "packages/agentsam-brand/src",
     "packages/agentsam-contracts",
+    "packages/agentsam-hooks",
     "packages/agentsam-errors",
     "packages/agentsam-repository",
     "packages/agentsam-knowledge",
@@ -226,9 +243,11 @@
     "packages/agentsam-docs-theme",
     "packages/agentsam-errors",
     "packages/agentsam-goap",
+    "packages/agentsam-hooks",
     "packages/agentsam-ide",
     "packages/agentsam-key-manager",
     "packages/agentsam-knowledge",
+    "packages/agentsam-loading-scene",
     "packages/agentsam-nav",
     "packages/agentsam-queue-control",
     "packages/agentsam-repository",
@@ -238,6 +257,7 @@
     "packages/agentsam-vault",
     "packages/agentsam-work",
     "packages/agentsam-workbench",
+    "packages/cms-runtime",
     "packages/connectors/cloudflare",
     "packages/heuristic-theme",
     "packages/identity",
@@ -251,7 +271,8 @@
     "packages/theme-insurance-site",
     "packages/theme-scenes",
     "packages/theme-shinshu-site",
-    "packages/work-graph"
+    "packages/work-graph",
+    "examples/hyperspace-demo"
   ],
   "scripts": {
     "test": "npm run test:standard && npm --prefix packages/identity test && npm --prefix packages/agentsam-brand test && npm run test:connectors && npm run test:providers",
@@ -265,7 +286,7 @@
     "test:terminal:mock": "node --test test/terminal/*.test.mjs",
     "test:live:terminal": "node --test test/live/*.live.test.mjs",
     "test:identity": "npm --prefix packages/identity test",
-    "test:workspaces": "npm --prefix packages/agentsam-contracts test && npm --prefix packages/agentsam-contracts run typecheck && npm --prefix packages/agentsam-errors test && npm --prefix packages/agentsam-repository test && npm --prefix packages/agentsam-workbench test && npm --prefix packages/agentsam-workbench run typecheck && npm --prefix packages/agentsam-nav run typecheck && npm --prefix packages/agentsam-shell-kit run typecheck && npm --prefix packages/work-graph test && npm --prefix packages/agentsam-queue-control test && npm --prefix packages/agentsam-goap test",
+    "test:workspaces": "npm --prefix packages/agentsam-contracts test && npm --prefix packages/agentsam-contracts run typecheck && npm --prefix packages/agentsam-errors test && npm --prefix packages/agentsam-vault test && npm --prefix packages/agentsam-repository test && npm --prefix packages/agentsam-workbench test && npm --prefix packages/agentsam-workbench run typecheck && npm --prefix packages/agentsam-nav run typecheck && npm --prefix packages/agentsam-shell-kit run typecheck && npm --prefix packages/work-graph test && npm --prefix packages/agentsam-queue-control test && npm --prefix packages/cms-runtime test && npm --prefix packages/agentsam-goap test && npm --prefix packages/agentsam-hooks test",
     "test:autorag": "npm --prefix packages/agentsam-knowledge test",
     "smoke": "node test/smoke.mjs",
     "verify:package": "node scripts/verify-package.mjs",
@@ -273,9 +294,9 @@
     "verify:bootstrap": "node scripts/verify-bootstrap.mjs",
     "verify:knowledge-package": "node scripts/verify-knowledge-package.mjs && npm run test:autorag",
     "test:python": "node scripts/verify-python.mjs",
-    "verify:release": "npm run verify && npm run verify:knowledge-package && npm run test:python && npm run security:release",
+    "verify:release": "npm run verify && npm run verify:packages:public && npm run verify:knowledge-package && npm run test:python && npm run security:release",
     "pack:check": "node scripts/verify-pack.mjs",
-    "verify": "npm run errors:check && npm run proto:check && npm test && npm run test:workspaces && npm run cad:registry:check && npm run app:validate && npm run verify:boundaries && npm run verify:package && npm run verify:bootstrap && npm run pack:check",
+    "verify": "npm run release:train:check && npm run errors:check && npm run proto:check && npm test && npm run test:workspaces && npm run cad:registry:check && npm run app:validate && npm run verify:boundaries && npm run verify:package && npm run verify:bootstrap && npm run pack:check",
     "publish:identity-alpha": "bash scripts/publish-identity-alpha.sh",
     "publish:identity-alpha:dry-run": "bash scripts/publish-identity-alpha.sh --dry-run",
     "publish:identity-alpha:publish-only": "bash scripts/publish-identity-alpha.sh --publish-only",
@@ -296,7 +317,8 @@
     "errors:check": "node scripts/verify-error-contracts.mjs",
     "cad:registry:check": "node scripts/cad-registry.mjs --check",
     "app:validate": "node bin/agentsam app validate --all",
-    "guard:apps": "npm run app:validate",
+    "app:packaging": "node scripts/verify-app-packaging.mjs --pack",
+    "guard:apps": "npm run app:validate && npm run app:packaging",
     "test:providers": "node --test packages/providers/completeful/test/*.test.mjs",
     "test:themes": "npm --prefix packages/heuristic-theme test && npm --prefix packages/theme-church-site test && npm --prefix packages/theme-companions-site test && npm --prefix packages/theme-floors-site test && npm --prefix packages/theme-fuelnfree-site test && npm --prefix packages/theme-handyman-site test && npm --prefix packages/theme-insurance-site test && npm --prefix packages/theme-shinshu-site test && npm --prefix packages/theme-scenes test",
     "test:theme-scenes": "npm --prefix packages/theme-scenes test",
@@ -305,7 +327,12 @@
     "prove:product": "node scripts/prove-agentsam-product.mjs",
     "security:release": "node scripts/verify-release-security.mjs",
     "verify:database-honesty": "node --test test/integration/database-hosted-honesty.test.mjs",
-    "ensure:cms-dist": "node scripts/ensure-cms-dist.mjs"
+    "ensure:cms-dist": "node scripts/ensure-cms-dist.mjs",
+    "release:train:check": "node scripts/release-train.mjs check",
+    "release:train:align": "node scripts/release-train.mjs align",
+    "ci:products": "node scripts/ci-products.mjs",
+    "verify:packages:public": "node scripts/verify-public-packages.mjs",
+    "test:hooks": "npm --prefix packages/agentsam-hooks test"
   },
   "engines": {
     "node": ">=22 <25",
@@ -314,7 +341,7 @@
   "dependencies": {
     "@clack/prompts": "^1.7.0",
     "@grpc/grpc-js": "^1.14.4",
-    "@inneranimalmedia/agentsam-errors": "2.6.8",
+    "@inneranimalmedia/agentsam-errors": "2.6.10",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "google-protobuf": "^3.21.4",
     "node-pty": "^1.1.0",