@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.1

package/docs/PLATFORM_RUNTIME_EVENTS.md

@@ -0,0 +1,48 @@
+# Platform runtime event dependency
+
+Status: **SDK consumer ready; platform producer pending.**
+
+The standalone CLI does not depend on a platform event endpoint. Local/provider execution emits runtime events directly into the same presenter used by future platform-connected sessions.
+
+The cross-repo dependency is in `SamPrimeaux/inneranimalmedia`: its pending agent-runtime SSE/event channel must eventually deliver the same normalized envelope consumed by:
+
+`src/ui/cli/runtime-events.js -> normalizeRuntimeEventEnvelope()`
+
+The SDK intentionally does **not** invent a route such as `/api/sdk/agent/runs`. Endpoint ownership, authorization, reconnection, and SSE lifecycle belong to the platform repository.
+
+## Producer contract
+
+Each platform event delivered to the SDK must normalize to:
+
+```js
+{
+  schema_version: 1,
+  type: "tool.started",
+  timestamp: "2026-09-18T00:00:00.000Z",
+  run_id: "run_...",
+  sequence: 3,
+  payload: {
+    // event-specific data
+  }
+}
+```
+
+`run_id` and `sequence` are optional when the source cannot supply them. `type` is required. `payload` is always normalized to an object.
+
+The SDK adds the internal contract marker `schema: "agentsam-runtime-event-v1"` after normalization. Platform producers do not need to know about CLI rendering, spinners, plans, approval prompts, compaction UI, or footer layout. They only emit the envelope.
+
+Current event vocabulary is declared in `src/telemetry/events.js`, including model, usage, cost, context, tool, approval, plan/task, timer, waiting-input, error, and run lifecycle events.
+
+## Boundary
+
+Standalone completion is not blocked by this dependency.
+
+The release-blocking standalone path is:
+
+provider/local runtime -> AgentEvent -> normalizeRuntimeEventEnvelope -> CLI presenter
+
+The later platform-connected path should be:
+
+platform runtime -> SSE/WebSocket transport -> normalizeRuntimeEventEnvelope -> same CLI presenter
+
+If platform integration requires changing the presenter contract instead of only adding the transport connection, treat that as a contract regression.

package/docs/RELEASES.md

@@ -1,14 +1,14 @@
 # `@inneranimalmedia/agentsam-sdk` release receipts
 
-**2.6.0 is the current release candidate on `main`; it is not published yet.**
-The npm `latest` dist-tag is **2.5.0**. The private identity workspace continues to
+**2.6.0 is published and is the npm `latest` release.** The private identity workspace continues to
 ship through root SDK exports and is not published separately.
 
-Release-candidate base: `2643c164b0a745d0772f1aa9808c03bbe3873c94`. The final tagged publish commit will be recorded
-here after release. Publishing remains manual and `prepublishOnly` runs
-`npm run verify:release`.
+Published at `2026-09-12T21:14:57.827Z` from git SHA
+`ae32fba0a761cb18c5f940957bdcd58e3cab6072`, tagged `v2.6.0`. Registry integrity:
+`sha512-98xvyIXGcX6/S0nFUkB2+s4zPxF5WvN/eYBjt6s575uC/ux/xB9Y0dH+pw7ur5TMRkQj7JDR4XN5cSy6I2Hr+w==`.
+Publishing remains manual and `prepublishOnly` runs `npm run verify:release`.
 
-## 2.6.0 candidate highlights
+## 2.6.0 highlights
 
 - Interactive AgentSam now has persistent machine-local account/session identity with explicit `login`, `logout`, `whoami`, and `resume` flows.
 - `/models` and model-selection UX bind to the canonical model inventory v2 contract instead of maintaining a second CLI catalog.
@@ -31,7 +31,7 @@ here after release. Publishing remains manual and `prepublishOnly` runs
 
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
-| 2.6.0 | _(pending)_ | _(tag at publish)_ | Release candidate; interactive model/session SSOT and account-scoped runtime receipts. |
+| 2.6.0 | 2026-09-12T21:14:57.827Z | `ae32fba0a761cb18c5f940957bdcd58e3cab6072` | Published package; npm `latest`; registry `gitHead`, shasum, integrity, and `v2.6.0` tag verified. |
 | 2.5.0 | 2026-09-11T21:27:11.516Z | `da28623dc4808025b77605ed09aa16217b1db607` | Published package; registry `gitHead` receipt. |
 | 2.4.1 | 2026-09-11T05:45:03.622Z | `a256ababededd904da555e7898bc8afd753737d2` | Latest published package before 2.5.0. |
 | 2.4.0 | 2026-09-11T05:29:02.811Z | `81c8659977953bed53c2adb0a341ce7382be4794` | Published 2.4 line. |

package/docs/SOURCE_ARCHITECTURE.md

@@ -0,0 +1,58 @@
+# AgentSam SDK source architecture
+
+The SDK root is the product/package composition layer, not the permanent home for every reusable subsystem.
+
+## Ownership rule
+
+New reusable code should have an explicit owner:
+
+- `packages/agentsam-contracts/` — framework-neutral wire/types vocabulary shared across AgentSam products and repositories.
+- `packages/identity/` — identity/auth contracts and adapters.
+- `packages/connectors/*/` — provider-specific connectors.
+- `packages/agentsam-workbench/` — reusable UI/workbench primitives.
+- `apps/*/` — self-contained applications with their own frontend/backend/shared package boundaries.
+- root `src/commands/`, `src/cli.js`, and `src/index.js` — SDK/CLI composition and public facade.
+
+`src/lib/` is a legacy extraction zone. Its current files are supported, but new unrelated reusable modules must not be added there. The source-boundary verifier freezes that surface so it can shrink over time.
+
+## Package extraction status
+
+Do not split the repo into micro-packages for their own sake. Extract a subsystem when it has a coherent public responsibility and can own its tests.
+
+**Extracted:** `packages/agentsam-repository/` now owns Git identity, Merkle/filemeta algorithms, repository graph runtime normalization, and snapshot persistence. Root SDK exports and CLI/runtime consumers compose that package without restoring `src/lib/merkle` or `src/lib/git-context.js`.
+
+Next coherent extractions:
+
+1. **Runtime/core** — account session, provider credentials, execution approvals, run/session primitives, and telemetry composition that are not CLI-specific.
+2. **Knowledge/indexing** — repository knowledge engine, stores, indexing provider contracts, and service client/runtime seams.
+
+The root CLI should depend on these packages; packages must not depend on root CLI/commands/UI internals.
+
+## Test placement
+
+Package behavior belongs with the package:
+
+```text
+packages/identity/tests/*
+packages/agentsam-contracts/test/*
+packages/agentsam-workbench/test/*
+packages/connectors/cloudflare/tests/*
+```
+
+Root SDK tests should move toward explicit roles:
+
+```text
+test/integration/*   cross-package/root-facade behavior
+test/cli/*           CLI command behavior
+test/release/*       packaging/release hygiene
+```
+
+The existing flat `test/*.test.mjs` set is legacy debt. It is frozen: old tests may remain while their owning subsystem is extracted, but new flat tests are rejected by `npm run verify:boundaries`.
+
+## App isolation
+
+Every `apps/<name>/` is a self-contained application boundary. Apps may consume documented SDK/package exports, but must not deep-import root `src/` implementation files. Reusable app logic should live in that app's `shared/` package first, then move to a top-level package only when it is genuinely cross-application.
+
+## Company graph / Merkle authority
+
+`agentsam-sdk` defines the portable vocabulary and deterministic algorithms. `inneranimalmedia` owns account-scoped operational persistence. The SDK must not introduce tenant/workspace/user ownership aliases or environment variables that impersonate authenticated account/repository authority.

package/docs/TEST_TIERS.md

@@ -0,0 +1,26 @@
+# AgentSam SDK test tiers
+
+The release-blocking test gate must be deterministic and must not require ExecOS, a user-hosted terminal tunnel, a cloud VM, or any other live external daemon.
+
+## Release-blocking tiers
+
+`npm test` runs these tiers:
+
+- `npm run test:unit` — deterministic unit/contract tests.
+- `npm run test:integration:mock` — integration behavior against local or mocked dependencies.
+- `npm run test:terminal:mock` — terminal/PTY behavior through an injected mock PTY transport. No ExecOS or tunnel is contacted.
+- identity and connector tests already included by the root `npm test` script.
+
+These tiers are the standard release gate and are suitable for GitHub Actions.
+
+## Live terminal tier
+
+`npm run test:live:terminal` is deliberately outside `npm test` and `npm run verify`.
+
+Set `AGENTSAM_LIVE_TERMINAL_WS_URL` to a real enrolled terminal WebSocket URL when an operator intentionally wants to exercise a live transport. `AGENTSAM_LIVE_TERMINAL_AUTH` may be supplied when that endpoint requires an Authorization header.
+
+If no live URL is supplied, the live test is skipped. A tunnel outage must never make the package release gate red.
+
+## Rule
+
+Tests may verify terminal protocol semantics in the release-blocking suite only through a local/mock transport. Any test that depends on ExecOS, a provisioned IAM terminal connection, Cloudflare Tunnel, or a real remote PTY belongs in the explicit live tier.

package/migrations/runtime/0001_cli_runtime.sql

@@ -0,0 +1,298 @@
+-- AgentSam portable CLI/runtime state.
+-- Compatible with Node SQLite and Cloudflare D1.
+-- Identity is account_id when available; standalone installs may leave account_id NULL.
+-- Derived from live IAM runtime tables on 2026-09-17, with tenant/workspace fields intentionally removed.
+
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE IF NOT EXISTS agentsam_agent_run (
+  id TEXT PRIMARY KEY NOT NULL,
+  account_id TEXT,
+  conversation_id TEXT,
+  external_agent_id TEXT,
+  external_run_id TEXT,
+  parent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE SET NULL,
+  source_client TEXT,
+  surface TEXT,
+  mode TEXT NOT NULL DEFAULT 'agent'
+    CHECK (mode IN ('ask','plan','agent','debug','multitask')),
+  model_key TEXT,
+  reasoning_effort TEXT,
+  requested_service_tier TEXT,
+  actual_service_tier TEXT,
+  selected_by TEXT CHECK (selected_by IS NULL OR selected_by IN ('manual','automatic','fallback')),
+  status TEXT NOT NULL DEFAULT 'queued'
+    CHECK (status IN ('queued','running','paused','completed','failed','partial','cancelled')),
+  cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK (cancel_requested IN (0,1)),
+  error_code TEXT,
+  error_message TEXT,
+  model_call_count INTEGER NOT NULL DEFAULT 0 CHECK (model_call_count >= 0),
+  tool_call_count INTEGER NOT NULL DEFAULT 0 CHECK (tool_call_count >= 0),
+  input_tokens INTEGER NOT NULL DEFAULT 0 CHECK (input_tokens >= 0),
+  cached_input_tokens INTEGER NOT NULL DEFAULT 0 CHECK (cached_input_tokens >= 0),
+  output_tokens INTEGER NOT NULL DEFAULT 0 CHECK (output_tokens >= 0),
+  reasoning_tokens INTEGER NOT NULL DEFAULT 0 CHECK (reasoning_tokens >= 0),
+  cost_usd REAL NOT NULL DEFAULT 0 CHECK (cost_usd >= 0),
+  created_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  started_at_unix INTEGER,
+  completed_at_unix INTEGER,
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  latency_ms INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_account_updated
+  ON agentsam_agent_run(account_id, updated_at_unix DESC);
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_parent
+  ON agentsam_agent_run(parent_run_id, created_at_unix);
+
+CREATE TABLE IF NOT EXISTS agentsam_compaction_events (
+  id TEXT PRIMARY KEY DEFAULT ('cmp_' || lower(hex(randomblob(8)))),
+  account_id TEXT,
+  agent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE SET NULL,
+  conversation_id TEXT,
+  compaction_type TEXT NOT NULL DEFAULT 'context_summary'
+    CHECK (compaction_type IN (
+      'context_summary','data_summary','run_summary','usage_summary',
+      'memory_summary','rule_summary','audit_summary','performance_summary','routing_summary'
+    )),
+  compaction_scope TEXT NOT NULL DEFAULT 'agent_run'
+    CHECK (compaction_scope IN ('rowset','table','agent_run','workflow','system')),
+  compaction_strategy TEXT NOT NULL DEFAULT 'summarize'
+    CHECK (compaction_strategy IN ('summarize','truncate','selective','full','rollup','audit')),
+  source_kind TEXT NOT NULL DEFAULT 'api'
+    CHECK (source_kind IN (
+      'd1','sqlite','r2','supabase','vectorize','hyperdrive','github',
+      'filesystem','worker_logs','api','browser','screenshot','mixed'
+    )),
+  source_table TEXT NOT NULL DEFAULT '',
+  source_row_count INTEGER NOT NULL DEFAULT 0,
+  source_min_epoch INTEGER,
+  source_max_epoch INTEGER,
+  source_filter_json TEXT NOT NULL DEFAULT '{}',
+  source_snapshot_json TEXT NOT NULL DEFAULT '{}',
+  source_query_hash TEXT NOT NULL DEFAULT '',
+  content_hash TEXT NOT NULL DEFAULT '',
+  provider TEXT NOT NULL DEFAULT '',
+  model_key TEXT NOT NULL DEFAULT '',
+  tokens_before INTEGER NOT NULL DEFAULT 0,
+  tokens_after INTEGER NOT NULL DEFAULT 0,
+  tokens_saved INTEGER GENERATED ALWAYS AS (tokens_before - tokens_after) STORED,
+  cost_before_usd REAL NOT NULL DEFAULT 0,
+  cost_after_usd REAL NOT NULL DEFAULT 0,
+  cost_saved_usd REAL GENERATED ALWAYS AS (cost_before_usd - cost_after_usd) STORED,
+  status TEXT NOT NULL DEFAULT 'completed'
+    CHECK(status IN ('queued','running','completed','failed','cancelled','needs_review')),
+  summary_text TEXT NOT NULL DEFAULT '',
+  summary_json TEXT NOT NULL DEFAULT '{}',
+  metrics_json TEXT NOT NULL DEFAULT '{}',
+  findings_json TEXT NOT NULL DEFAULT '{}',
+  recommended_actions_json TEXT NOT NULL DEFAULT '[]',
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  source_stored TEXT NOT NULL DEFAULT 'local:agentsam_compaction_events',
+  source_url TEXT NOT NULL DEFAULT '',
+  report_artifact_url TEXT NOT NULL DEFAULT '',
+  expires_at_epoch INTEGER,
+  compacted_at_epoch INTEGER NOT NULL DEFAULT (unixepoch()),
+  created_at_epoch INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at_epoch INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_compaction_run
+  ON agentsam_compaction_events(agent_run_id, compacted_at_epoch DESC);
+CREATE INDEX IF NOT EXISTS idx_agentsam_compaction_expiry
+  ON agentsam_compaction_events(expires_at_epoch)
+  WHERE expires_at_epoch IS NOT NULL;
+
+CREATE TABLE IF NOT EXISTS agentsam_context_digest (
+  id TEXT PRIMARY KEY,
+  account_id TEXT,
+  digest_type TEXT NOT NULL CHECK (
+    digest_type IN (
+      'schema','repo','docs','memory','tool_registry','route_map',
+      'session','deployment','rag','conversation','handoff','project'
+    )
+  ),
+  project_id TEXT,
+  agent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE SET NULL,
+  session_id TEXT,
+  source_hash TEXT NOT NULL,
+  digest_hash TEXT NOT NULL UNIQUE,
+  raw_size_bytes INTEGER,
+  reduced_size_bytes INTEGER,
+  token_count INTEGER,
+  digest_text TEXT NOT NULL,
+  generation_model TEXT,
+  namespace TEXT,
+  hit_count INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  created_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  source_updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  expires_at_unix INTEGER,
+  embedding_model TEXT,
+  embedding_dimensions INTEGER,
+  compaction_event_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_context_digest_session
+  ON agentsam_context_digest(session_id, source_updated_at_unix DESC)
+  WHERE session_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agentsam_context_digest_run
+  ON agentsam_context_digest(agent_run_id, source_updated_at_unix DESC)
+  WHERE agent_run_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agentsam_context_digest_compaction
+  ON agentsam_context_digest(compaction_event_id)
+  WHERE compaction_event_id IS NOT NULL;
+
+CREATE TRIGGER IF NOT EXISTS context_digest_set_initial_expiry
+AFTER INSERT ON agentsam_context_digest
+WHEN NEW.expires_at_unix IS NULL
+BEGIN
+  UPDATE agentsam_context_digest
+  SET expires_at_unix = CASE
+    WHEN NEW.digest_type IN ('session','conversation','handoff')
+      THEN unixepoch() + 2592000
+    ELSE NULL
+  END
+  WHERE id = NEW.id;
+END;
+
+CREATE TRIGGER IF NOT EXISTS context_digest_extend_on_hit
+AFTER UPDATE OF hit_count ON agentsam_context_digest
+WHEN NEW.hit_count > OLD.hit_count AND OLD.expires_at_unix IS NOT NULL
+BEGIN
+  UPDATE agentsam_context_digest
+  SET expires_at_unix = unixepoch() + 2592000,
+      updated_at_unix = unixepoch(),
+      updated_at = datetime('now')
+  WHERE id = NEW.id;
+END;
+
+CREATE TABLE IF NOT EXISTS agentsam_plans (
+  id TEXT PRIMARY KEY,
+  account_id TEXT,
+  session_id TEXT,
+  agent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE SET NULL,
+  plan_type TEXT NOT NULL DEFAULT 'feature'
+    CHECK(plan_type IN ('daily','sprint','incident','feature','refactor','run')),
+  title TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active'
+    CHECK(status IN ('draft','active','complete','abandoned')),
+  summary_text TEXT NOT NULL DEFAULT '',
+  token_budget INTEGER,
+  tokens_used INTEGER NOT NULL DEFAULT 0 CHECK(tokens_used >= 0),
+  cost_usd REAL NOT NULL DEFAULT 0 CHECK(cost_usd >= 0),
+  tasks_total INTEGER NOT NULL DEFAULT 0 CHECK(tasks_total >= 0),
+  tasks_done INTEGER NOT NULL DEFAULT 0 CHECK(tasks_done >= 0),
+  tasks_blocked INTEGER NOT NULL DEFAULT 0 CHECK(tasks_blocked >= 0),
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_todo (
+  id TEXT PRIMARY KEY,
+  account_id TEXT,
+  plan_id TEXT REFERENCES agentsam_plans(id) ON DELETE CASCADE,
+  agent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE SET NULL,
+  title TEXT NOT NULL,
+  description TEXT,
+  status TEXT NOT NULL DEFAULT 'open'
+    CHECK(status IN ('open','running','blocked','complete','cancelled')),
+  priority TEXT NOT NULL DEFAULT 'medium'
+    CHECK(priority IN ('low','medium','high','critical')),
+  sort_order INTEGER NOT NULL DEFAULT 50,
+  token_budget INTEGER,
+  tokens_used INTEGER NOT NULL DEFAULT 0 CHECK(tokens_used >= 0),
+  cost_usd REAL NOT NULL DEFAULT 0 CHECK(cost_usd >= 0),
+  requires_approval INTEGER NOT NULL DEFAULT 0 CHECK(requires_approval IN (0,1)),
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  started_at_unix INTEGER,
+  completed_at_unix INTEGER,
+  created_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_todo_plan
+  ON agentsam_todo(plan_id, sort_order, created_at_unix);
+
+CREATE TABLE IF NOT EXISTS agentsam_approval_queue (
+  id TEXT PRIMARY KEY DEFAULT ('appr_' || lower(hex(randomblob(8)))),
+  account_id TEXT,
+  session_id TEXT,
+  conversation_id TEXT,
+  agent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE SET NULL,
+  plan_id TEXT REFERENCES agentsam_plans(id) ON DELETE SET NULL,
+  todo_id TEXT REFERENCES agentsam_todo(id) ON DELETE SET NULL,
+  capability_key TEXT,
+  tool_name TEXT,
+  action_summary TEXT NOT NULL,
+  sanitized_input_json TEXT NOT NULL DEFAULT '{}',
+  response_json TEXT NOT NULL DEFAULT '{}',
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  risk_level TEXT NOT NULL DEFAULT 'medium'
+    CHECK (risk_level IN ('low','medium','high','critical')),
+  approval_type TEXT NOT NULL DEFAULT 'tool'
+    CHECK (approval_type IN (
+      'tool','workflow','command','script','deploy','db_write','r2_write',
+      'github_write','terminal','spawn','escalation','route_upgrade'
+    )),
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending','approved','denied','expired')),
+  approved_by TEXT,
+  decided_at INTEGER,
+  expires_at INTEGER DEFAULT (unixepoch() + 300),
+  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_approval_pending
+  ON agentsam_approval_queue(status, expires_at)
+  WHERE status = 'pending';
+
+CREATE TABLE IF NOT EXISTS active_timers (
+  id TEXT PRIMARY KEY,
+  account_id TEXT,
+  label TEXT NOT NULL DEFAULT '',
+  timer_kind TEXT NOT NULL CHECK (timer_kind IN ('stopwatch','countdown')),
+  status TEXT NOT NULL DEFAULT 'running'
+    CHECK (status IN ('running','paused','completed','cancelled','expired')),
+  started_at_unix INTEGER NOT NULL,
+  ends_at_unix INTEGER,
+  paused_at_unix INTEGER,
+  elapsed_seconds INTEGER NOT NULL DEFAULT 0,
+  completed_at_unix INTEGER,
+  agent_run_id TEXT REFERENCES agentsam_agent_run(id) ON DELETE CASCADE,
+  approval_queue_id TEXT REFERENCES agentsam_approval_queue(id) ON DELETE CASCADE,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  CHECK (
+    timer_kind != 'countdown'
+    OR (ends_at_unix IS NOT NULL AND ends_at_unix > started_at_unix)
+  ),
+  CHECK (agent_run_id IS NOT NULL OR approval_queue_id IS NOT NULL)
+);
+
+CREATE INDEX IF NOT EXISTS idx_active_timers_running
+  ON active_timers(status, ends_at_unix)
+  WHERE status = 'running';
+
+CREATE TABLE IF NOT EXISTS agentsam_cron_runs (
+  id TEXT PRIMARY KEY DEFAULT ('acr_' || lower(hex(randomblob(8)))),
+  account_id TEXT,
+  job_name TEXT NOT NULL,
+  cron_expression TEXT,
+  status TEXT NOT NULL DEFAULT 'running'
+    CHECK(status IN ('running','completed','failed','skipped')),
+  started_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  completed_at INTEGER,
+  duration_ms INTEGER,
+  rows_read INTEGER NOT NULL DEFAULT 0,
+  rows_written INTEGER NOT NULL DEFAULT 0,
+  error_message TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_cron_runs_job_started
+  ON agentsam_cron_runs(job_name, started_at DESC);

package/package.json

@@ -1,23 +1,28 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.6.0",
+  "version": "2.6.1",
   "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",
   "exports": {
     ".": "./src/index.js",
-    "./git-context": "./src/lib/git-context.js",
+    "./git-context": "./packages/agentsam-repository/src/git-context.js",
     "./bridge-client": "./src/lib/bridge-client.js",
     "./local/sqlite": "./src/local/sqlite.js",
     "./dockerize": "./src/lib/dockerize.js",
     "./mini": "./src/lib/mini/index.js",
-    "./merkle": "./src/lib/merkle/index.js",
+    "./merkle": "./packages/agentsam-repository/src/merkle/index.js",
     "./deploy-receipt": "./src/lib/deploy-receipt/index.js",
     "./knowledge": "./src/knowledge/index.js",
     "./knowledge-service-client": "./src/knowledge/service/client.js",
+    "./knowledge-service-grpc-client": "./src/knowledge/service/grpc-client.js",
     "./capabilities": "./src/capabilities/index.js",
     "./capability-manifest": "./protocol/capabilities/manifest.json",
     "./repository": "./src/repository/index.js",
+    "./repository/contracts": "./packages/agentsam-repository/src/contracts.js",
+    "./repository/identity-schema": "./protocol/repository/repository-identity.schema.json",
+    "./repository/contract-schema": "./protocol/repository/repository-contract.schema.json",
+    "./repository/dependency-schema": "./protocol/repository/repository-dependency.schema.json",
     "./agent": "./src/agent/index.js",
     "./presets": "./src/presets/index.js",
     "./preset-catalog": "./protocol/presets/catalog.json",
@@ -71,6 +76,7 @@
   "files": [
     "src",
     "packages/identity",
+    "packages/agentsam-repository",
     "packages/connectors/cloudflare",
     "templates",
     "docs",
@@ -78,6 +84,7 @@
     "test",
     "python",
     "protocol",
+    "migrations",
     "skills",
     "services/knowledge/package.json",
     "services/knowledge/package-lock.json",
@@ -93,19 +100,28 @@
     "packages/agentsam-shell-kit",
     "packages/identity",
     "packages/agentsam-contracts",
+    "packages/agentsam-repository",
     "packages/agentsam-workbench"
   ],
   "scripts": {
-    "test": "node test/smoke.mjs && node --test test/*.test.mjs && npm --prefix packages/identity test && npm run test:connectors",
+    "test": "npm run test:standard && npm --prefix packages/identity test && npm run test:connectors",
+    "test:standard": "node test/smoke.mjs && npm run test:unit && npm run test:cli && npm run test:integration:mock && npm run test:terminal:mock",
+    "test:unit": "node --test test/*.test.mjs",
+    "test:cli": "node --test test/cli/*.test.mjs",
+    "test:integration:mock": "node --test test/integration/*.test.mjs",
+    "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-repository test && npm --prefix packages/agentsam-workbench test && npm --prefix packages/agentsam-workbench run typecheck && npm --prefix packages/agentsam-shell-kit run typecheck",
     "smoke": "node test/smoke.mjs",
     "verify:package": "node scripts/verify-package.mjs",
+    "verify:boundaries": "node scripts/verify-source-boundaries.mjs",
     "verify:bootstrap": "node scripts/verify-bootstrap.mjs",
     "verify:knowledge-package": "node scripts/verify-knowledge-package.mjs",
     "test:python": "node scripts/verify-python.mjs",
     "verify:release": "npm run verify && npm run verify:knowledge-package && npm run test:python && npm run security:check",
     "pack:check": "npm pack --dry-run --json",
-    "verify": "npm test && npm run verify:package && npm run verify:bootstrap && npm run pack:check",
+    "verify": "npm run proto:check && npm test && npm run test:workspaces && 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",
@@ -115,7 +131,9 @@
     "security:repair": "node src/security/cli.mjs repair",
     "ui:preview": "node scripts/ui-preview.mjs",
     "test:connectors": "node --test packages/connectors/cloudflare/tests/**/*.test.mjs",
-    "verify:npm10-lock": "node apps/local-studio/scripts/verify-npm10-lock.mjs"
+    "verify:npm10-lock": "node apps/local-studio/scripts/verify-npm10-lock.mjs",
+    "proto:generate": "node scripts/generate-proto.mjs",
+    "proto:check": "node scripts/verify-proto.mjs"
   },
   "engines": {
     "node": ">=22 <25",
@@ -123,6 +141,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "@grpc/grpc-js": "^1.14.4",
+    "google-protobuf": "^3.21.4",
     "node-pty": "^1.0.0",
     "pg": "8.16.3",
     "picocolors": "^1.1.1",
@@ -156,7 +176,8 @@
   },
   "devDependencies": {
     "@electric-sql/pglite": "0.5.8",
-    "@electric-sql/pglite-pgvector": "0.0.9"
+    "@electric-sql/pglite-pgvector": "0.0.9",
+    "grpc-tools": "^1.13.1"
   },
   "packageManager": "npm@10.9.2"
 }

package/packages/agentsam-repository/README.md

@@ -0,0 +1,15 @@
+# @inneranimalmedia/agentsam-repository
+
+Owned repository/runtime package for AgentSam.
+
+It owns deterministic repository identity and Merkle behavior that must be reusable independently of the CLI surface:
+
+- Git remote/context normalization
+- Merkle content trees and snapshots
+- semantic/file metadata classification
+- Merkle persistence contracts and Cloudflare binding adapters
+- repository graph runtime normalization
+
+It does **not** own authenticated account sessions, CLI commands, UI rendering, knowledge retrieval, deployment orchestration, or product application state. Those layers consume this package through explicit imports.
+
+The workspace is private while the extraction stabilizes. Cross-repository consumers should continue using the published `@inneranimalmedia/agentsam-sdk` facade until this package receives its own release policy.

package/packages/agentsam-repository/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@inneranimalmedia/agentsam-repository",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Portable AgentSam repository identity, Merkle, semantic file metadata, persistence, and repository graph runtime contracts.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./git-context": "./src/git-context.js",
+    "./contracts": "./src/contracts.js",
+    "./merkle": "./src/merkle/index.js",
+    "./merkle/persistence": "./src/merkle/persistence.js",
+    "./merkle/cloudflare-persistence": "./src/merkle/cloudflare-persistence.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "node": ">=22 <25"
+  }
+}