@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.2

package/docs/AUTH_IDENTITY_CONTRACT.md

@@ -6,47 +6,45 @@ The `agentsam-sdk` package owns the portable public configuration contract. Cons
 
 | Variable | Meaning |
 | --- | --- |
-| `IAM_ORIGIN` | Canonical IAM authority and browser/OAuth/API origin. |
+| `IAM_OAUTH_ISSUER` | Canonical IAM authority/issuer for browser OAuth and platform account requests. |
+| `IAM_ORIGIN` | Migration fallback for the IAM issuer. New code resolves `IAM_OAUTH_ISSUER` first. |
 | `IAM_CLIENT_ID` | OAuth client id for an application using IAM identity. |
 | `IAM_CLIENT_SECRET` | OAuth client secret. Keep it server-side. |
-| `AGENTSAM_SDK_KEY` | Account/delegated SDK bearer. Raw values use the `sdk_` prefix and are sent as `Authorization: Bearer …`. |
-| `AGENTSAM_BRIDGE_KEY` | Machine/integration credential. It is never a substitute for user SDK authentication. |
+| `AGENTSAM_API_KEY` | Reusable account/delegated API credential. Raw values use the `aak_` prefix and are sent as `Authorization: Bearer …`. |
+| `AGENTSAM_BRIDGE_KEY` | Infrastructure/machine integration trust. It is never a substitute for account authentication. |
 
-The host-side durable verifier for SDK credentials is `agentsam_sdk_tokens`. The SDK defines the public credential semantics; the host owns the database and authorization implementation.
+The host-side durable verifier for reusable AgentSam API credentials is `agentsam_api_credentials`. The SDK defines the public credential semantics; the host owns credential issuance, hashing, storage, revocation, and authorization.
 
-`AGENTSAM_BRIDGE_KEY` remains the direct machine-secret environment variable. A host may additionally resolve a hashed credential from `agentsam_sdk_tokens` when that row has `token_type='integration'`. That does not turn the bridge credential into user authentication.
+Interactive browser login is intentionally separate from `AGENTSAM_API_KEY`. The CLI stores an opaque machine-local browser session under `~/.agentsam/auth/session.json`; it does not turn that session into a reusable API key.
 
 ## Migration compatibility
 
-The current migration window accepts two deprecated read fallbacks:
+The issuer resolver accepts `IAM_ORIGIN` only when `IAM_OAUTH_ISSUER` is absent. The retired `AGENTSAM_SDK_KEY`, `AGENTSAM_SDK_TOKEN`, `sdk_` bearer, and `agentsam_sdk_tokens` account-auth contract is not read by the current SDK.
 
-```text
-IAM_ORIGIN
-  fallback: IAM_OAUTH_ISSUER
-
-AGENTSAM_SDK_KEY
-  fallback: AGENTSAM_SDK_TOKEN
-```
-
-Canonical names always win when both are present. New scaffolds, docs, and writes emit only the canonical names. Compatibility aliases are intentionally not a permanent parallel configuration surface.
-
-Older platform-base aliases (`IAM_CORE_URL`, `AGENTSAM_CORE_URL`, `AGENTSAM_BASE_URL`) are compatibility-only. SDK clients prefer `IAM_ORIGIN`.
+Older platform-base aliases (`IAM_CORE_URL`, `AGENTSAM_CORE_URL`, `AGENTSAM_BASE_URL`) remain compatibility-only where legacy clients still consume them.
 
 ## Credential boundaries
 
 ```text
-human/account SDK lane
-  AGENTSAM_SDK_KEY
-    -> sdk_* bearer
-    -> Authorization: Bearer <sdk_*>
+reusable account API lane
+  AGENTSAM_API_KEY
+    -> aak_* bearer
+    -> Authorization: Bearer <aak_*>
     -> account/delegated authority
-    -> agentsam_sdk_tokens
+    -> agentsam_api_credentials (hashed verifier on the host)
+
+interactive browser lane
+  agentsam login
+    -> opaque browser session credential
+    -> ~/.agentsam/auth/session.json
+    -> interactive account authority
+    -> never rewritten as AGENTSAM_API_KEY
 
-machine/integration lane
-  AGENTSAM_BRIDGE_KEY
+machine/infrastructure lane
+  enrolled opaque machine credential / infrastructure bridge trust
     -> machine principal
-    -> no user/workspace identity injection
-    -> host env secret OR agentsam_sdk_tokens(token_type='integration')
+    -> server resolves connection -> instance -> account
+    -> never accepted as account API auth
 ```
 
-Browser OAuth uses `IAM_ORIGIN` together with `IAM_CLIENT_ID` and `IAM_CLIENT_SECRET`. Repository identity, workspace labels, or machine trust do not prove account authority.
+Repository identity, workspace labels, terminal instance ids, and machine trust do not prove reusable account authority. Provider credentials such as `OPENAI_API_KEY`, `GEMINI_API_KEY`, `CURSOR_API_KEY`, and Cloudflare credentials are managed separately by the machine provider-credential service.

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/SDK_WORKER.md

@@ -47,16 +47,17 @@ agentsam-sdk
 ├─ AGENTSAM_WAI        -> Workers AI provider
 ├─ EXECOS              -> execos service binding
 ├─ PTY_SERVICE         -> iam-vpc VPC service
-├─ IAM_ORIGIN          -> https://inneranimalmedia.com
+├─ IAM_OAUTH_ISSUER    -> https://inneranimalmedia.com
+├─ IAM_ORIGIN          -> migration fallback
 ├─ IAM_CLIENT_ID       -> public OAuth client id
 ├─ IAM_CLIENT_SECRET   -> secret
-├─ AGENTSAM_SDK_KEY    -> secret
+├─ AGENTSAM_API_KEY    -> aak_ account credential (only when a reusable account credential is needed)
 └─ AGENTSAM_BRIDGE_KEY -> secret
 ```
 
 Hosted model credentials are secrets: `XAI_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. Grok model inference is the `XAI_API_KEY` provider lane and is independent from the pre-wired Grok gate viewer identity/session system.
 
-`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` and `AGENTSAM_SDK_TOKEN` are SDK 2.5 migration-read aliases only; new configuration uses `IAM_ORIGIN` and `AGENTSAM_SDK_KEY`.
+`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` is the canonical IAM authority; `IAM_ORIGIN` is a migration fallback. Reusable account API credentials use `AGENTSAM_API_KEY` with an `aak_` prefix. Browser login sessions and machine/infrastructure credentials remain separate and must not be promoted into account API keys.
 
 ## Ollama
 

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);