@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.4

package/migrations/d1/0011_agentsam_skill_v2.sql

@@ -0,0 +1,185 @@
+-- 0011_agentsam_skill_v2.sql
+-- Skill redesign: identity/config · metrics · retrieval (three tables).
+-- Fresh installs: apply this file directly.
+-- Production hosts with legacy agentsam_skill: use 0011b_agentsam_skill_v2_cutover.sql
+--
+-- Ownership: account_id only (no tenant_id / user_id / person_uuid / workspace_id / scope).
+-- No FK to agentsam_account — that table is not present on IAM D1; account_id aligns with
+-- accounts.id (au_*) when the row is account-owned.
+--
+-- Published npm lane: partial unique on slash_trigger WHERE is_published = 1
+-- (two accounts cannot both publish the same /trigger).
+
+CREATE TABLE IF NOT EXISTS agentsam_skill (
+  id                 TEXT PRIMARY KEY,
+  account_id         TEXT NOT NULL,
+
+  name               TEXT NOT NULL,
+  slash_trigger      TEXT NOT NULL
+                       CHECK (slash_trigger GLOB '/[a-z0-9][a-z0-9-]*'),
+
+  npm_package_name   TEXT,
+  npm_version        TEXT,
+  is_published       INTEGER NOT NULL DEFAULT 0 CHECK (is_published IN (0,1)),
+
+  description        TEXT NOT NULL DEFAULT '',
+  content_markdown   TEXT NOT NULL DEFAULT '',
+  file_path          TEXT NOT NULL DEFAULT '',
+  content_checksum   TEXT NOT NULL DEFAULT '',
+
+  globs              TEXT NOT NULL DEFAULT '[]',
+  always_apply       INTEGER NOT NULL DEFAULT 0 CHECK (always_apply IN (0,1)),
+  task_types_json    TEXT NOT NULL DEFAULT '[]',
+  route_keys_json    TEXT NOT NULL DEFAULT '[]',
+
+  access_mode        TEXT NOT NULL DEFAULT 'read_write'
+                       CHECK (access_mode IN ('read_only','read_write')),
+
+  icon               TEXT NOT NULL DEFAULT '',
+  tags_json          TEXT NOT NULL DEFAULT '[]',
+  metadata_json      TEXT NOT NULL DEFAULT '{}',
+
+  invocation_count   INTEGER NOT NULL DEFAULT 0,
+  last_invoked_at    TEXT,
+
+  version            INTEGER NOT NULL DEFAULT 1,
+  is_active          INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0,1)),
+  sort_order         INTEGER NOT NULL DEFAULT 0,
+
+  created_at         TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at         TEXT NOT NULL DEFAULT (datetime('now')),
+
+  UNIQUE (account_id, slash_trigger),
+  UNIQUE (npm_package_name, npm_version)
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_account ON agentsam_skill(account_id);
+CREATE INDEX IF NOT EXISTS idx_skill_active ON agentsam_skill(is_active) WHERE is_active = 1;
+CREATE INDEX IF NOT EXISTS idx_skill_published ON agentsam_skill(is_published) WHERE is_published = 1;
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_skill_published_slash
+  ON agentsam_skill(slash_trigger) WHERE is_published = 1;
+
+CREATE TABLE IF NOT EXISTS agentsam_skill_metrics (
+  skill_id           TEXT PRIMARY KEY REFERENCES agentsam_skill(id) ON DELETE CASCADE,
+  byte_size          INTEGER NOT NULL DEFAULT 0,
+  char_count         INTEGER NOT NULL DEFAULT 0,
+  line_count         INTEGER NOT NULL DEFAULT 0,
+  estimated_tokens   INTEGER NOT NULL DEFAULT 0,
+  estimation_method  TEXT NOT NULL DEFAULT 'chars_div_4'
+                       CHECK (estimation_method IN ('chars_div_4','tiktoken_cl100k','tiktoken_o200k','provider_reported')),
+  computed_at        TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_skill_retrieval (
+  id                 TEXT PRIMARY KEY,
+  skill_id           TEXT NOT NULL REFERENCES agentsam_skill(id) ON DELETE CASCADE,
+
+  provider           TEXT NOT NULL CHECK (provider IN (
+                        'local_fs',
+                        'cloudflare_d1',
+                        'cloudflare_hyperdrive',
+                        'cloudflare_r2',
+                        'cloudflare_vectorize',
+                        'supabase_postgres',
+                        'supabase_vectorize'
+                      )),
+  strategy           TEXT NOT NULL CHECK (strategy IN (
+                        'relational',
+                        'object_store',
+                        'vector_index',
+                        'none'
+                      )),
+
+  is_primary         INTEGER NOT NULL DEFAULT 0 CHECK (is_primary IN (0,1)),
+
+  index_name         TEXT,
+  namespace          TEXT,
+  connection_ref     TEXT,
+  embedding_model    TEXT,
+  dimensions         INTEGER,
+
+  config_json        TEXT NOT NULL DEFAULT '{}',
+  last_synced_at     TEXT,
+  created_at         TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at         TEXT NOT NULL DEFAULT (datetime('now')),
+
+  UNIQUE (skill_id, provider, strategy)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_skill_retrieval_primary
+  ON agentsam_skill_retrieval(skill_id) WHERE is_primary = 1;
+
+CREATE INDEX IF NOT EXISTS idx_skill_retrieval_skill ON agentsam_skill_retrieval(skill_id);
+
+CREATE TABLE IF NOT EXISTS agentsam_skill_revision (
+  id               TEXT PRIMARY KEY DEFAULT ('skillrev_' || lower(hex(randomblob(8)))),
+  skill_id         TEXT NOT NULL REFERENCES agentsam_skill(id) ON DELETE CASCADE,
+  content_markdown TEXT NOT NULL,
+  version          INTEGER NOT NULL,
+  changed_by       TEXT NOT NULL DEFAULT 'system',
+  change_note      TEXT,
+  created_at       TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_revision_skill_id ON agentsam_skill_revision(skill_id);
+CREATE INDEX IF NOT EXISTS idx_skill_revision_version ON agentsam_skill_revision(skill_id, version);
+
+CREATE TABLE IF NOT EXISTS agentsam_skill_invocation (
+  id              TEXT PRIMARY KEY DEFAULT ('skillinv_' || lower(hex(randomblob(8)))),
+  skill_id        TEXT NOT NULL REFERENCES agentsam_skill(id) ON DELETE CASCADE,
+  account_id      TEXT NOT NULL,
+  repository_id   TEXT,
+  conversation_id TEXT,
+  trigger_method  TEXT NOT NULL DEFAULT 'slash'
+    CHECK (trigger_method IN ('slash','at','auto','api')),
+  input_summary   TEXT,
+  success         INTEGER NOT NULL DEFAULT 1,
+  error_message   TEXT,
+  duration_ms     INTEGER,
+  model_used      TEXT,
+  tokens_in       INTEGER DEFAULT 0,
+  tokens_out      INTEGER DEFAULT 0,
+  cost_usd        REAL DEFAULT 0.0,
+  invoked_at      TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_invoc_skill_id ON agentsam_skill_invocation(skill_id);
+CREATE INDEX IF NOT EXISTS idx_skill_invoc_account ON agentsam_skill_invocation(account_id);
+CREATE INDEX IF NOT EXISTS idx_skill_invoc_invoked ON agentsam_skill_invocation(invoked_at);
+
+-- updated_at bump (D1/SQLite)
+-- Avoid recursion: only bump when the statement did not already set updated_at.
+CREATE TRIGGER IF NOT EXISTS trg_skill_updated_at
+AFTER UPDATE ON agentsam_skill
+WHEN NEW.updated_at IS OLD.updated_at
+BEGIN
+  UPDATE agentsam_skill SET updated_at = datetime('now') WHERE id = NEW.id;
+END;
+
+-- Auto metrics on insert/content change (chars/4 heuristic)
+CREATE TRIGGER IF NOT EXISTS trg_skill_metrics_insert
+AFTER INSERT ON agentsam_skill
+BEGIN
+  INSERT INTO agentsam_skill_metrics (skill_id, byte_size, char_count, line_count, estimated_tokens)
+  VALUES (
+    NEW.id,
+    LENGTH(CAST(NEW.content_markdown AS BLOB)),
+    LENGTH(NEW.content_markdown),
+    LENGTH(NEW.content_markdown) - LENGTH(REPLACE(NEW.content_markdown, char(10), '')) + 1,
+    CAST(LENGTH(NEW.content_markdown) / 4.0 AS INTEGER)
+  );
+END;
+
+CREATE TRIGGER IF NOT EXISTS trg_skill_metrics_update
+AFTER UPDATE OF content_markdown ON agentsam_skill
+BEGIN
+  UPDATE agentsam_skill_metrics SET
+    byte_size         = LENGTH(CAST(NEW.content_markdown AS BLOB)),
+    char_count        = LENGTH(NEW.content_markdown),
+    line_count        = LENGTH(NEW.content_markdown) - LENGTH(REPLACE(NEW.content_markdown, char(10), '')) + 1,
+    estimated_tokens  = CAST(LENGTH(NEW.content_markdown) / 4.0 AS INTEGER),
+    estimation_method = 'chars_div_4',
+    computed_at       = datetime('now')
+  WHERE skill_id = NEW.id;
+END;

package/migrations/d1/0011b_agentsam_skill_v2_cutover.sql

@@ -0,0 +1,22 @@
+-- 0011b_agentsam_skill_v2_cutover.sql
+-- ORCHESTRATION NOTES (do not run this whole file via wrangler --file on large DBs —
+-- D1 import may D1_RESET_DO). Apply in steps:
+--
+--   1) RENAME (one statement each):
+--        ALTER TABLE agentsam_skill RENAME TO agentsam_skill_legacy;
+--        ALTER TABLE agentsam_skill_revision RENAME TO agentsam_skill_revision_legacy;
+--        ALTER TABLE agentsam_skill_invocation RENAME TO agentsam_skill_invocation_legacy;
+--   2) DDL:     --file migrations/d1/0011_agentsam_skill_v2.sql
+--   3) Backfill skills: --file migrations/d1/0011c_agentsam_skill_v2_backfill.sql
+--   4) Retrieval+revisions: --file migrations/d1/0011d_agentsam_skill_v2_retrieval_revisions.sql
+--   5) Verify counts: skill == legacy == metrics == retrieval; revisions match legacy.
+--   6) Keep *_legacy until verified. Drop only after a bake period.
+--
+-- Applied remotely on inneranimalmedia-business 2026-09-25 (88 skills).
+-- Notes:
+--   - No FK to agentsam_account (table absent); account_id aligns with accounts.au_* when present.
+--   - Partial unique idx_skill_published_slash included (published slash triggers globally unique).
+--   - Empty slash_trigger → /skill-{id-slug}; dual vectorize → /vectorize-lanes-dual.
+--   - Dropped columns preserved under metadata_json.legacy.
+
+SELECT 'see header comments — run cutover in steps' AS note;

package/migrations/d1/0011c_agentsam_skill_v2_backfill.sql

@@ -0,0 +1,76 @@
+-- Backfill agentsam_skill v2 from agentsam_skill_legacy (run after 0011 DDL + rename).
+-- Empty slash_trigger → derive from skill id (avoids /unnamed collisions).
+
+INSERT INTO agentsam_skill (
+  id, account_id, name, slash_trigger,
+  description, content_markdown, file_path, content_checksum,
+  globs, always_apply, task_types_json, route_keys_json,
+  access_mode, icon, tags_json, metadata_json,
+  invocation_count, last_invoked_at, version, is_active, sort_order,
+  created_at, updated_at
+)
+SELECT
+  l.id,
+  CASE
+    WHEN l.user_id GLOB 'au_*' THEN l.user_id
+    WHEN l.user_id = 'sam_primeaux' THEN 'au_8a5b76b737a9f14c'
+    WHEN l.user_id IN ('platform', 'system') THEN l.user_id
+    WHEN l.person_uuid IS NOT NULL AND TRIM(l.person_uuid) != '' THEN 'person:' || l.person_uuid
+    WHEN l.tenant_id IS NOT NULL AND TRIM(l.tenant_id) != '' THEN 'tenant:' || l.tenant_id
+    ELSE 'account_orphan'
+  END,
+  COALESCE(NULLIF(TRIM(l.name), ''), l.id),
+  CASE
+    WHEN l.id = 'skill_agentsam_dual_vectorize_lanes' THEN '/vectorize-lanes-dual'
+    WHEN l.slash_trigger IS NULL OR TRIM(l.slash_trigger) = ''
+      THEN '/skill-' || lower(substr(replace(replace(l.id, 'skill_', ''), '_', '-'), 1, 40))
+    WHEN lower(CASE
+           WHEN l.slash_trigger GLOB '/*' THEN l.slash_trigger
+           ELSE '/' || l.slash_trigger
+         END) GLOB '/[a-z0-9][a-z0-9-]*'
+      THEN lower(CASE
+           WHEN l.slash_trigger GLOB '/*' THEN l.slash_trigger
+           ELSE '/' || l.slash_trigger
+         END)
+    ELSE '/skill-' || lower(substr(replace(replace(l.id, 'skill_', ''), '_', '-'), 1, 40))
+  END,
+  COALESCE(l.description, ''),
+  COALESCE(l.content_markdown, ''),
+  COALESCE(l.file_path, ''),
+  '',
+  CASE
+    WHEN l.globs IS NULL OR TRIM(l.globs) = '' THEN '[]'
+    WHEN l.globs GLOB '[*' THEN l.globs
+    ELSE json_array(l.globs)
+  END,
+  COALESCE(l.always_apply, 0),
+  COALESCE(NULLIF(TRIM(l.task_types_json), ''), '[]'),
+  COALESCE(NULLIF(TRIM(l.route_keys_json), ''), '[]'),
+  CASE
+    WHEN l.access_mode IN ('read_only', 'read_write') THEN l.access_mode
+    ELSE 'read_write'
+  END,
+  COALESCE(l.icon, ''),
+  COALESCE(NULLIF(TRIM(l.tags_json), ''), '[]'),
+  json_object(
+    'legacy', json_object(
+      'tenant_id', l.tenant_id,
+      'user_id', l.user_id,
+      'person_uuid', l.person_uuid,
+      'workspace_id', l.workspace_id,
+      'scope', l.scope,
+      'default_model_key', l.default_model_key,
+      'model_constraints_json', l.model_constraints_json,
+      'token_estimate', l.token_estimate,
+      'retrieval_strategy', l.retrieval_strategy,
+      'slash_trigger_raw', l.slash_trigger
+    )
+  ),
+  COALESCE(l.invocation_count, 0),
+  l.last_invoked_at,
+  COALESCE(l.version, 1),
+  COALESCE(l.is_active, 1),
+  COALESCE(l.sort_order, 0),
+  COALESCE(l.created_at, datetime('now')),
+  COALESCE(l.updated_at, datetime('now'))
+FROM agentsam_skill_legacy l;

package/migrations/d1/0011d_agentsam_skill_v2_retrieval_revisions.sql

@@ -0,0 +1,50 @@
+-- Retrieval + revision backfill after skill rows exist.
+
+INSERT INTO agentsam_skill_retrieval (
+  id, skill_id, provider, strategy, is_primary,
+  index_name, connection_ref, config_json
+)
+SELECT
+  'skillret_' || lower(hex(randomblob(8))),
+  s.id,
+  CASE
+    WHEN lower(COALESCE(json_extract(s.metadata_json, '$.legacy.retrieval_strategy'), '')) IN ('r2', 'object_store')
+      THEN 'cloudflare_r2'
+    WHEN lower(COALESCE(json_extract(s.metadata_json, '$.legacy.retrieval_strategy'), '')) IN ('vectorize', 'vector')
+      THEN 'cloudflare_vectorize'
+    ELSE 'cloudflare_d1'
+  END,
+  CASE
+    WHEN lower(COALESCE(json_extract(s.metadata_json, '$.legacy.retrieval_strategy'), '')) IN ('r2', 'object_store')
+      THEN 'object_store'
+    WHEN lower(COALESCE(json_extract(s.metadata_json, '$.legacy.retrieval_strategy'), '')) IN ('vectorize', 'vector')
+      THEN 'vector_index'
+    ELSE 'relational'
+  END,
+  1,
+  NULLIF(TRIM(s.file_path), ''),
+  CASE
+    WHEN lower(COALESCE(json_extract(s.metadata_json, '$.legacy.retrieval_strategy'), '')) IN ('r2', 'object_store')
+      THEN 'WEBSITE_ASSETS'
+    ELSE 'DB'
+  END,
+  '{}'
+FROM agentsam_skill s
+WHERE NOT EXISTS (
+  SELECT 1 FROM agentsam_skill_retrieval r WHERE r.skill_id = s.id
+);
+
+INSERT INTO agentsam_skill_revision (
+  id, skill_id, content_markdown, version, changed_by, change_note, created_at
+)
+SELECT
+  r.id,
+  r.skill_id,
+  r.content_markdown,
+  r.version,
+  COALESCE(NULLIF(TRIM(r.changed_by), ''), 'system'),
+  r.change_note,
+  COALESCE(r.created_at, datetime('now'))
+FROM agentsam_skill_revision_legacy r
+WHERE EXISTS (SELECT 1 FROM agentsam_skill s WHERE s.id = r.skill_id)
+  AND NOT EXISTS (SELECT 1 FROM agentsam_skill_revision x WHERE x.id = r.id);

package/migrations/d1/0012_agentsam_tools_required_seed.sql

@@ -0,0 +1,67 @@
+-- 0012_agentsam_tools_required_seed.sql
+-- Registers required tool_key stubs for new projects.
+-- Full handler schemas live in the host agentsam_tools registry; this seed
+-- guarantees GOAP / search_tools / multitask can resolve the required set.
+-- Idempotent: skips rows that already exist by tool_key.
+
+INSERT INTO agentsam_tools (
+  id, tool_name, tool_key, tool_code, display_name, tool_category,
+  handler_type, description, is_active, risk_level, domain, account_id
+)
+SELECT
+  'ast_req_' || lower(hex(randomblob(6))),
+  key,
+  key,
+  key,
+  key,
+  'platform',
+  'terminal',
+  'Required AgentSam tool seed · see registry/tools/required-seed.json',
+  1,
+  'low',
+  'general',
+  '*'
+FROM (
+  SELECT 'fs_read_file' AS key UNION ALL SELECT 'fs_write_file' UNION ALL SELECT 'fs_edit_file'
+  UNION ALL SELECT 'fs_list_dir' UNION ALL SELECT 'fs_search_files'
+  UNION ALL SELECT 'agentsam_filesystem_walk' UNION ALL SELECT 'agentsam_filesystem_stat_many'
+  UNION ALL SELECT 'agentsam_filesystem_hash_many' UNION ALL SELECT 'agentsam_filesystem_git_status'
+  UNION ALL SELECT 'agentsam_github_read' UNION ALL SELECT 'agentsam_github_write'
+  UNION ALL SELECT 'agentsam_github_pr' UNION ALL SELECT 'agentsam_github_pr_merge'
+  UNION ALL SELECT 'agentsam_github_issue' UNION ALL SELECT 'agentsam_github_search'
+  UNION ALL SELECT 'agentsam_github_tree' UNION ALL SELECT 'agentsam_github_read_many'
+  UNION ALL SELECT 'agentsam_github_patch' UNION ALL SELECT 'agentsam_github_grep'
+  UNION ALL SELECT 'agentsam_github_create_repo' UNION ALL SELECT 'agentsam_grep'
+  UNION ALL SELECT 'browser_navigate'
+  UNION ALL SELECT 'agentsam_memory_search' UNION ALL SELECT 'agentsam_memory_manager'
+  UNION ALL SELECT 'agentsam_memory_commit'
+  UNION ALL SELECT 'agentsam_d1_query' UNION ALL SELECT 'agentsam_d1_write'
+  UNION ALL SELECT 'agentsam_supabase_query' UNION ALL SELECT 'agentsam_supabase_write'
+  UNION ALL SELECT 'agentsam_supabase_vector'
+  UNION ALL SELECT 'agentsam_r2_get' UNION ALL SELECT 'agentsam_r2_put' UNION ALL SELECT 'agentsam_r2_delete'
+  UNION ALL SELECT 'agentsam_cf_vectorize' UNION ALL SELECT 'agentsam_cf_d1_list'
+  UNION ALL SELECT 'agentsam_cf_workers_list' UNION ALL SELECT 'agentsam_cf_worker_get'
+  UNION ALL SELECT 'agentsam_cf_worker_code'
+  UNION ALL SELECT 'agentsam_autorag'
+  UNION ALL SELECT 'agentsam_terminal_local' UNION ALL SELECT 'agentsam_terminal_sandbox'
+  UNION ALL SELECT 'agentsam_terminal_remote'
+  UNION ALL SELECT 'agentsam_create_subagent' UNION ALL SELECT 'agentsam_container_exec'
+  UNION ALL SELECT 'search_cloudflare_documentation' UNION ALL SELECT 'agentsam_spawn_tree'
+  UNION ALL SELECT 'agentsam_run_agent'
+  UNION ALL SELECT 'agentsam_ticket_list' UNION ALL SELECT 'agentsam_ticket_get'
+  UNION ALL SELECT 'agentsam_ticket_create' UNION ALL SELECT 'agentsam_ticket_set_status'
+  UNION ALL SELECT 'agentsam_code_interpreter'
+  UNION ALL SELECT 'cad_generate' UNION ALL SELECT 'cad_job_cancel' UNION ALL SELECT 'cad_job_status'
+  UNION ALL SELECT 'agentsam_search_tools'
+  UNION ALL SELECT 'agentsam_codebase_retrieve' UNION ALL SELECT 'agentsam_knowledge_ingest_segment'
+  UNION ALL SELECT 'agentsam_multitask_spawn' UNION ALL SELECT 'agentsam_multitask_status'
+  UNION ALL SELECT 'agentsam_multitask_cancel'
+  UNION ALL SELECT 'agentsam_merkle_build' UNION ALL SELECT 'agentsam_merkle_get'
+  UNION ALL SELECT 'agentsam_merkle_compare' UNION ALL SELECT 'agentsam_merkle_explain'
+  UNION ALL SELECT 'agentsam_merkle_delete'
+  UNION ALL SELECT 'agentsam_repo_intelligence' UNION ALL SELECT 'agentsam_code_index_build'
+  UNION ALL SELECT 'agentsam_repository_snapshot'
+) AS required
+WHERE NOT EXISTS (
+  SELECT 1 FROM agentsam_tools t WHERE t.tool_key = required.key OR t.tool_name = required.key
+);

package/migrations/d1/0013_identity_oauth_states.sql

@@ -0,0 +1,15 @@
+-- identity_oauth_states — PKCE state for /api/oauth/{provider}/start (identity login).
+-- Deliberately NOT named oauth_states (collides with Stripe Connect schema on this D1).
+-- Required for Sign in with Cloudflare on agentsam.inneranimalmedia.com.
+
+CREATE TABLE IF NOT EXISTS identity_oauth_states (
+  state TEXT PRIMARY KEY NOT NULL,
+  provider TEXT NOT NULL,
+  code_verifier TEXT NOT NULL,
+  redirect_to TEXT,
+  expires_at INTEGER NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_identity_oauth_states_expires
+  ON identity_oauth_states(expires_at);

package/migrations/d1/0014_auth_event_log.sql

@@ -0,0 +1,20 @@
+-- auth_event_log — append-only auth audit (identity package).
+-- status remains outcome-only (ok|failed). Rich context lives in metadata_json.
+
+CREATE TABLE IF NOT EXISTS auth_event_log (
+  id TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT,
+  event_type TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'ok',
+  provider TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  ip_hash TEXT,
+  user_agent_hash TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_auth_event_log_user_created
+  ON auth_event_log(user_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_auth_event_log_type_created
+  ON auth_event_log(event_type, created_at DESC);

package/migrations/d1/0015_identity_oauth_state_app_id.sql

@@ -0,0 +1,3 @@
+-- Optional app_id on OAuth PKCE state so post-login resumes the initiating app.
+
+ALTER TABLE identity_oauth_states ADD COLUMN app_id TEXT;

package/migrations/d1/README_PORTABLE_CONTROL_PLANE.md

@@ -0,0 +1,16 @@
+# Portable control-plane schemas (tickets · memory · skills · tools)
+
+Apply from the repo that owns the SQL (agentsam-sdk `migrations/d1/`).
+
+| File | Purpose |
+|------|---------|
+| `0010_portable_tickets_memory.sql` | Account-owned `agentsam_tickets` + events + `agentsam_memory` + outbox. `account_id` + `repository_id` **NOT NULL**. |
+| `0011_agentsam_skill_v2.sql` | Skill identity · metrics · retrieval (3-table redesign). Legacy hosts: rename old → `agentsam_skill_legacy`, backfill, verify. |
+| `0012_agentsam_tools_required_seed.sql` | Idempotent seed of required `tool_key` rows for GOAP / multitask. Manifest: `registry/tools/required-seed.json`. |
+
+## Law
+
+- **NULL `repository_id` on memory/ticket writes = broken implementation.** Resolve repo identity from `agentsam inspect` / snapshot before insert.
+- Customer tickets use **their** D1/SQLite — never IAM host ticket rows.
+- `agentsam_autorag` stays registered for A* planning even while multi-level retrieval is incomplete.
+- Skill publish uniqueness: partial unique on `slash_trigger WHERE is_published = 1` is included.

package/migrations/sqlite/agentsam_skill_retrieval.portable.sql

@@ -0,0 +1,42 @@
+-- Portable local skill retrieval shape (NOT applied to IAM D1 as-is).
+-- strategy ≠ provider_id ≠ driver_id ≠ accelerator_ref ≠ embedding_profile_id
+-- Hyperdrive is accelerator_ref, never a provider.
+
+CREATE TABLE IF NOT EXISTS agentsam_skill_retrieval (
+  id                   TEXT PRIMARY KEY,
+  skill_id             TEXT NOT NULL,
+
+  strategy             TEXT NOT NULL CHECK (
+    strategy IN (
+      'relational',
+      'object_store',
+      'vector_index',
+      'filesystem'
+    )
+  ),
+
+  provider_id          TEXT NOT NULL,
+  driver_id            TEXT NOT NULL,
+
+  connection_ref       TEXT,
+  accelerator_ref      TEXT,
+
+  embedding_profile_id TEXT,
+
+  index_name           TEXT,
+  namespace            TEXT,
+
+  is_primary           INTEGER NOT NULL DEFAULT 0,
+
+  config_json          TEXT NOT NULL DEFAULT '{}',
+
+  last_synced_at       TEXT,
+  created_at           TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at           TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_skill_retrieval_skill
+  ON agentsam_skill_retrieval(skill_id);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_skill_retrieval_primary
+  ON agentsam_skill_retrieval(skill_id) WHERE is_primary = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "2.6.3",
+  "version": "2.6.4",
   "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",
@@ -19,6 +19,19 @@
     "./knowledge-service-grpc-client": "./src/knowledge/service/grpc-client.js",
     "./capabilities": "./src/capabilities/index.js",
     "./capability-manifest": "./protocol/capabilities/manifest.json",
+    "./sam": "./src/sam/index.js",
+    "./sam/operation-schema": "./protocol/sam/operation.schema.json",
+    "./sam/result-schema": "./protocol/sam/result.schema.json",
+    "./sam/registry-seed": "./protocol/sam/registry.seed.json",
+    "./sam/state-schema": "./protocol/sam/state.v1.schema.json",
+    "./sam/question-schema": "./protocol/sam/question.v1.schema.json",
+    "./sam/answer-schema": "./protocol/sam/answer.v1.schema.json",
+    "./sam/evaluation-schema": "./protocol/sam/evaluation.v1.schema.json",
+    "./sam/decision-receipt-schema": "./protocol/sam/decision-receipt.v1.schema.json",
+    "./sam/outcome-schema": "./protocol/sam/outcome.v1.schema.json",
+    "./sam/calibration-schema": "./protocol/sam/calibration.v1.schema.json",
+    "./sam/activity-schema": "./protocol/sam/activity.v1.schema.json",
+    "./errors/recovery-schema": "./protocol/errors/recovery.v1.schema.json",
     "./repository": "./src/repository/index.js",
     "./repository/contracts": "./packages/agentsam-repository/src/contracts.js",
     "./repository/identity-schema": "./protocol/repository/repository-identity.schema.json",
@@ -191,6 +204,7 @@
     "prepublishOnly": "npm run site:sync && npm run verify:release",
     "site:sync": "node scripts/sync-public-site.mjs",
     "site:learn": "node scripts/build-learn-site.mjs",
+    "site:sam-docs": "node scripts/build-sam-docs.mjs",
     "site:publish": "node scripts/publish-website-assets.mjs",
     "security:check": "node src/security/cli.mjs scan",
     "security:repair": "node src/security/cli.mjs repair",
@@ -204,7 +218,8 @@
     "cad:registry:check": "node scripts/cad-registry.mjs --check",
     "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",
-    "theme:harvest": "python3 scripts/theme-refinery/harvest.py"
+    "theme:harvest": "python3 scripts/theme-refinery/harvest.py",
+    "verify:go-distribution": "node scripts/verify-go-distribution.mjs"
   },
   "engines": {
     "node": ">=22 <25",
@@ -219,7 +234,7 @@
     "pg": "8.16.3",
     "picocolors": "^1.1.1",
     "typescript": "5.9.3",
-    "wrangler": "4.137.0",
+    "wrangler": "4.140.0",
     "ws": "^8.18.0"
   },
   "publishConfig": {
@@ -250,7 +265,7 @@
     "protobufjs@7.6.6": true,
     "esbuild@0.28.1": true,
     "fsevents@2.3.3": true,
-    "workerd@1.20260921.1": true
+    "workerd@1.20260923.1": true
   },
   "devDependencies": {
     "@changesets/changelog-github": "^1.0.1",

package/packages/agentsam-contracts/src/errors.ts

@@ -1,4 +1,5 @@
 // GENERATED by scripts/generate-error-contracts.mjs. Do not edit by hand.
+
 export const AGENTSAM_ERROR_SCHEMA_VERSION = 1 as const;
 
 export type AgentSamErrorCode = "OK" | "CANCELLED" | "UNKNOWN" | "INVALID_ARGUMENT" | "DEADLINE_EXCEEDED" | "NOT_FOUND" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "RESOURCE_EXHAUSTED" | "FAILED_PRECONDITION" | "ABORTED" | "OUT_OF_RANGE" | "UNIMPLEMENTED" | "INTERNAL" | "UNAVAILABLE" | "DATA_LOSS" | "UNAUTHENTICATED";
@@ -8,12 +9,19 @@ export type AgentSamErrorSourceKind = "user" | "agentsam" | "provider" | "depend
 export type AgentSamErrorResolutionOwner = "user" | "agentsam" | "provider" | "organization_admin" | "policy" | "unknown";
 export type AgentSamErrorDomain = "runtime" | "provider" | "auth" | "device" | "terminal" | "transport" | "repository" | "indexing" | "knowledge" | "cad" | "deployment" | "persistence" | "policy" | "tool";
 export type AgentSamRemediationAction = "none" | "retry" | "retry_later" | "reauthenticate" | "connect_provider" | "configure_provider_credential" | "refresh_provider_credential" | "request_permission" | "reenroll_device" | "reconnect_service" | "install_dependency" | "upgrade_dependency" | "configure_dependency" | "change_configuration" | "change_input" | "reduce_scope" | "increase_quota" | "add_budget" | "select_model" | "change_region" | "restart_runtime" | "inspect_platform" | "contact_provider" | "contact_agentsam" | "contact_organization_admin";
+export type AgentSamErrorSideEffectState = "none" | "not_started" | "confirmed_not_applied" | "confirmed_applied" | "partially_applied" | "unknown";
+export type AgentSamErrorOutcomeStatus = "success" | "partial" | "failure";
 
 export interface AgentSamErrorSource { kind: AgentSamErrorSourceKind; name: string; service: string | null; }
 export interface AgentSamErrorRemediation { action: AgentSamRemediationAction; message: string | null; automatic: boolean; command: string | null; url: string | null; }
 export interface AgentSamErrorResource { type: string; id: string | null; name: string | null; }
 export interface AgentSamNativeErrorEvidence { code: string | null; exception_type: string | null; exit_code: number | null; signal: string | null; stderr: string | null; stdout: string | null; stack: string | null; }
 export interface AgentSamEnvironmentEvidence { detected_version: string | null; required_version: string | null; component: string | null; runtime: string | null; platform: string | null; }
+export interface AgentSamErrorOperation { kind?: string | null; action?: string | null; resource_type?: string | null; resource_id?: string | null; read_only?: boolean; idempotent?: boolean; side_effect_state?: AgentSamErrorSideEffectState; }
+export interface AgentSamErrorRetry { allowed?: boolean; strategy?: string; retry_after_ms?: number | null; max_attempts?: number | null; requires_idempotency_key?: boolean; }
+export interface AgentSamErrorFallback { allowed?: boolean; strategy?: string | null; preserve_semantics?: boolean; target?: string | null; }
+export interface AgentSamErrorNotification { user?: string; operator?: string; agent?: string; }
+export interface AgentSamErrorPartialResult { completed?: number; failed?: number; failures?: unknown[]; }
 
 export interface AgentSamErrorEnvelope {
   ok: false;
@@ -43,4 +51,12 @@ export interface AgentSamErrorEnvelope {
   fingerprint: string;
   occurrence_count: number;
   details: unknown;
+  failure_class?: string;
+  operation?: AgentSamErrorOperation;
+  retry?: AgentSamErrorRetry;
+  fallback?: AgentSamErrorFallback;
+  notify?: AgentSamErrorNotification;
+  cause?: unknown;
+  status?: AgentSamErrorOutcomeStatus;
+  partial?: AgentSamErrorPartialResult;
 }