@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/docs/tools/filesystem-and-code.md

@@ -0,0 +1,55 @@
+# Filesystem & Code
+
+Reading/writing/searching files, AST-level codebase retrieval, code index builds, Merkle diffing, and knowledge ingestion.
+
+**20 tools** in this domain.
+
+## `code` (1)
+
+- **`agentsam_codebase_retrieve`** (Codebase AST Retrieve) — Query-type-routed codebase retrieval: exact name/calls/exports resolve from D1 AST without embeddings; fuzzy natural-language questions use OpenAI embeddings → pgvector AST symbols, then optional one-hop graph expand. mode is a HARD override: structural=D1 only, semantic=pgvector ANN, auto=classify first. Empty structural lookups escalate to semantic unless escalate=false. Do NOT use agentsam_d1_query for source code. _★ heavily used (327 calls)_
+
+## `code.index` (1)
+
+- **`agentsam_code_index_build`** (Code Index Build) — Start or observe the existing account/repository-scoped index pipeline. Does not implement parsing/embedding/activation itself. _never used_
+
+## `code.search` (2)
+
+- **`agentsam_github_grep`** (GitHub Grep (live tree)) — GitHub Code Search API alias of agentsam_github_search (repo-scoped via OAuth). Not local disk, not PTY ripgrep — use fs_search_files or agentsam_grep for those.
+- **`agentsam_grep`** (Grep (github | filesystem | terminal rg)) — Ripgrep over the workspace checkout. Default lane: MY_CONTAINER (works when Mac PTY is down). Optional fast lane: local PTY working tree.
+
+## `filesystem` (10)
+
+- **`agentsam_filesystem_git_status`** (Filesystem Git Status) — Structured staged/unstaged/untracked via git status --porcelain under workspace_root.
+- **`agentsam_filesystem_hash_many`** (Filesystem Hash Many) — Batch content hashes. content_mode raw_bytes|git_blob. _never used_
+- **`agentsam_filesystem_stat_many`** (Filesystem Stat Many) — Batch stat metadata under approved workspace_root. _never used_
+- **`agentsam_filesystem_walk`** (Filesystem Walk) — Walk approved workspace_root with containment limits. Prefer over terminal find for tree inspection.
+- **`agentsam_merkle_build`** (Merkle Build) — Construct + persist content-addressed fs-merkle-v1 snapshot (github|execos|entries).
+- **`agentsam_merkle_compare`** (Merkle Compare) — Domain-checked Merkle diff. Refuses mismatched leaf_hash_domain.
+- **`agentsam_merkle_delete`** (Merkle Delete) — Delete snapshot R2 body + thin D1 index row. _never used_
+- **`agentsam_merkle_explain`** (Merkle Explain) — Explain why a folder changed (V1 honest subset — no pure-rename claim).
+- **`agentsam_merkle_get`** (Merkle Get) — Fetch snapshot path/children by snapshot_id from R2+D1 index.
+- **`fs_list_dir`** (List directory) — List entries on the active Files plane: Local FSA when connected; else host path on the caller tunnel. When files_source=r2, lists the selected R2 bucket/prefix. Not a terminal tool, not GitHub.
+
+## `filesystem.edit` (1)
+
+- **`fs_edit_file`** (FS Edit File) — Patch a file in the connected local filesystem only. GitHub edits must use agentsam_github_patch with explicit repo and branch. _risk: high_
+
+## `filesystem.read` (1)
+
+- **`fs_read_file`** (FS Read File) — Read a workspace file (Local folder / PTY / GitHub committed tip). Default max_bytes=32768 with byte_offset pagination. Prefer line_start/line_end from agentsam_codebase_retrieve over whole-file reads. _★ heavily used (546 calls)_
+
+## `filesystem.search` (1)
+
+- **`fs_search_files`** (Search Files (rg)) — Ripgrep over the workspace checkout. Required: query. Optional: path. Never call with {}. _★ heavily used (530 calls)_
+
+## `filesystem.write` (1)
+
+- **`fs_write_file`** (FS Write File) — Write a file to the connected local filesystem only. GitHub writes must use agentsam_github_write with explicit repo and branch. _risk: high, ★ heavily used (101 calls)_
+
+## `knowledge` (1)
+
+- **`agentsam_knowledge_ingest_segment`** (Knowledge ingest segment) — Canonical atomic knowledge write (ingest_segment). Pass a full ingest_segment payload, or markdown + file_name for the docs topic adapter. _never used_
+
+## `repository.evidence` (1)
+
+- **`agentsam_repository_snapshot`** (Repository Snapshot) — Capture the canonical agentsam.snapshot.v1 repository evidence packet. Deterministic filesystem inspection delegated to the SDK on an authorized host. _**inactive**, never used_

package/docs/tools/github.md

@@ -0,0 +1,56 @@
+# GitHub
+
+Every GitHub read (repos, branches, commits, PRs, issues, workflow runs) and write (commit, patch, branch, PR, comment) operation.
+
+**36 tools** in this domain.
+
+## `gh.pr` (1)
+
+- **`agentsam_gh_pr_list`** (GitHub CLI PR List) — List pull requests via gh pr list (JSON). Complements agentsam_github_pr_list REST tool. _never used_
+
+## `github.issue` (1)
+
+- **`agentsam_github_issue`** (GitHub Issue) — Create or manage GitHub issues using your connected GitHub account. Requires explicit owner/repo.
+
+## `github.pr` (1)
+
+- **`agentsam_github_pr`** (GitHub PR) — Open a pull request using your connected GitHub account. Requires explicit owner/repo, title, head, and base. _risk: high_
+
+## `github.read` (21)
+
+- **`agentsam_github_check_permission`** (GitHub Check Permission) — READ ONLY — return your effective permission level (admin/write/read/none) on a repository. _never used_
+- **`agentsam_github_commit_get`** (GitHub Commit Get) — READ ONLY — get a single commit's full details (repo + sha required). Use agentsam_github_list_commits for bulk. _never used_
+- **`agentsam_github_commit_status_get`** (GitHub Commit Status Get) — READ ONLY — get the combined commit status/CI checks for a commit (repo + sha required). _never used_
+- **`agentsam_github_compare`** (GitHub Compare Commits) — READ ONLY — compare two refs/commits (base...head): ahead_by, behind_by, changed files. _never used_
+- **`agentsam_github_job_logs_get`** (GitHub Job Logs Get) — READ ONLY — fetch raw log output for a single Actions job (repo + job_id required). Call agentsam_github_workflow_jobs_list first to find job_id. _never used_
+- **`agentsam_github_list_branches`** (GitHub List Branches) — READ ONLY — list branches for a repository (paginated, up to 300). Use to discover a real base ref before agentsam_github_create_branch. Never invent main.
+- **`agentsam_github_list_commits`** (GitHub List Commits) — READ ONLY — list recent commits for a branch/ref. _★ heavily used (107 calls)_
+- **`agentsam_github_pr_diff`** (GitHub PR Diff) — READ ONLY — fetch the full unified diff for a pull request. _never used_
+- **`agentsam_github_pr_files`** (GitHub PR Changed Files) — READ ONLY — list filenames changed in a pull request. Call before fetching a single-file patch.
+- **`agentsam_github_pr_get`** (GitHub PR Get) — READ ONLY — fetch a single pull request's metadata (title, state, head/base refs, body).
+- **`agentsam_github_pr_list`** (GitHub PR List) — READ ONLY — list pull requests for a repo, optionally filtered by state/base/head.
+- **`agentsam_github_read`** (GitHub Read) — Read a file from GitHub using your connected GitHub account. Requires explicit owner/repo and path. _★ heavily used (310 calls)_
+- **`agentsam_github_read_many`** (GitHub Batch File Read) — When you need several files at once, batch-read paths; pass metadata_only:true for sha/size without content.
+- **`agentsam_github_repo_get`** (GitHub Repo Get) — READ ONLY — repository snapshot: full_name, default_branch, private, archived, your permission level. Call before create_branch/compare/create_pr when default_branch is unknown.
+- **`agentsam_github_repo_list`** (List GitHub Repos) — READ ONLY — list repositories for the connected GitHub account. Not a file reader — use agentsam_github_read/tree/search for contents.
+- **`agentsam_github_search`** (GitHub Code Search) — READ ONLY — GitHub code search scoped to one repo. Rate-limited (~10/min). Prefer agentsam_github_tree for browsing. _★ heavily used (332 calls)_
+- **`agentsam_github_search_issues_prs`** (GitHub Search Issues/PRs) — READ ONLY — search issues and pull requests using search syntax. Distinct from agentsam_github_search which searches code.
+- **`agentsam_github_tree`** (GitHub Repo Tree) — Read GitHub data for the explicit owner/repo. Never use a catalog repo default. _★ heavily used (265 calls)_
+- **`agentsam_github_workflow_jobs_list`** (GitHub Workflow Jobs List) — READ ONLY — list jobs within a workflow run. Use to find job_id before pulling logs. _never used_
+- **`agentsam_github_workflow_run_get`** (GitHub Workflow Run Get) — READ ONLY — get a single Actions workflow run's status/details. _never used_
+- **`agentsam_github_workflow_runs_list`** (GitHub Workflow Runs List) — READ ONLY — list Actions workflow runs, optionally filtered by branch/workflow_id/status/event. _never used_
+
+## `github.write` (12)
+
+- **`agentsam_github_comment_create`** (GitHub Comment Create) — Create a comment on an issue or pull request. PRs use issue_number for comments. _risk: high, never used_
+- **`agentsam_github_commit_status_set`** (GitHub Commit Status Set) — Set a commit status/CI check. state must be error|failure|pending|success. _risk: high, never used_
+- **`agentsam_github_commit_tree`** (GitHub Commit Tree) — Commit multiple files in one GitHub tree. Requires explicit owner/repo, message, files, and branch.
+- **`agentsam_github_create_branch`** (GitHub Create Branch) — Create a remote branch from a base ref or SHA. Does not create a local checkout. Call before patch/commit_tree/write when the target branch doesn't exist yet. Discover base via agentsam_github_list_branches. _risk: high_
+- **`agentsam_github_create_repo`** (GitHub Create Repo) — Create a new GitHub repository. Greenfield scaffold path. Defaults private=true, auto_init=true. _risk: high_
+- **`agentsam_github_delete`** (GitHub Delete File) — Delete a file via Contents API. Resolves current blob sha automatically if omitted. _risk: high, never used_
+- **`agentsam_github_delete_branch`** (GitHub Delete Branch) — Delete a remote branch ref. Irreversible unless SHA recovered elsewhere. _risk: high, never used_
+- **`agentsam_github_patch`** (GitHub Patch File) — Surgical find/replace on an existing GitHub branch (exact unique match or fail). Branch must already exist — create it first. Never default to main. _risk: high_
+- **`agentsam_github_pr_create`** (GitHub PR Create) — Open PR after branch is pushed (terminal git push first). Do not use Contents API to simulate multi-file PRs. _never used_
+- **`agentsam_github_pr_merge`** (GitHub PR Merge) — Merge an existing, already-open pull request. Does not create or approve. _risk: high, never used_
+- **`agentsam_github_pr_update`** (GitHub PR Update) — Update an already-open pull request's title/body/state/base. Does not create or merge. _risk: high, never used_
+- **`agentsam_github_write`** (GitHub Write) — Write a file to GitHub. Requires explicit owner/repo, path, content, message, and branch. _risk: high_

package/docs/tools/integrations-and-misc.md

@@ -0,0 +1,16 @@
+# Integrations & Misc
+
+Google Drive, Resend (inactive), and raw HTTP fetch (inactive).
+
+**5 tools** in this domain.
+
+## `integrations.execute` (4)
+
+- **`agentsam_gdrive`** (Google Drive) — Reads files and folders from Google Drive via IAM gdrive proxy tools. _never used_
+- **`gdrive_list`** (Google Drive List) — List files in Google Drive with optional query filter. _**inactive**, never used_
+- **`resend_send_broadcast`** (Resend Broadcast) — Send a broadcast email to an audience via Resend. Requires approval. _**inactive**, risk: high, never used_
+- **`resend_send_email`** (Resend Send Email) — Send a transactional email via Resend API. Requires from/to/subject/html. _**inactive**, never used_
+
+## `network` (1)
+
+- **`http_fetch`** (HTTP Fetch) — Fetch a URL via HTTP GET. Returns response body as text. Use for external APIs without auth. _**inactive**, never used_

package/docs/tools/memory.md

@@ -0,0 +1,21 @@
+# Memory
+
+Agent Sam's own memory commit/search/save/manager surface — semantic memory, not to be confused with this assistant's own memory system.
+
+**4 tools** in this domain.
+
+## `memory` (1)
+
+- **`agentsam_memory_commit`** (Memory Commit) — Canonical Agent Sam memory commit (D1 SSOT + projection outbox). Returns memory_id, revision, content_hash, semantic_ready, and projection receipts. Use dry_run to validate. Prefer this over agentsam_memory_manager.
+
+## `memory.manager` (1)
+
+- **`agentsam_memory_manager`** (Memory Manager (compat)) — COMPATIBILITY adapter only. Prefer agentsam_memory_commit / agentsam_memory_search. Routes through IAM_MAIN canonical hybrid/commit — not the legacy standalone Supabase vector lane.
+
+## `memory.search` (1)
+
+- **`agentsam_memory_search`** (Memory Search) — Hybrid semantic memory search via IAM_MAIN (exact → Vectorize → pgvector → lexical → D1 hydrate). Returns memory_id/revision/content_hash and suppresses low-score noise.
+
+## `memory.write` (1)
+
+- **`agentsam_memory_save`** (Memory Save) — Canonical memory save (same commit path as agentsam_memory_commit with eager=false). Still enqueues outbox; projections retry on hourly cron.

package/docs/tools/terminal-and-execution.md

@@ -0,0 +1,29 @@
+# Terminal & Execution
+
+Running shell/Python/Node commands — on the user's own Mac, the always-on cloud desk, or an isolated sandbox — plus container batch exec and Code Mode.
+
+**6 tools** in this domain.
+
+## `container.exec` (1)
+
+- **`agentsam_container_exec`** (Container Batch Exec) — Execute a non-interactive shell command in the explicitly selected Cloudflare MY_CONTAINER sandbox. _risk: high_
+
+## `runtime.codemode` (1)
+
+- **`codemode`** (Code Mode) — Run JavaScript that orchestrates IAM catalog tools inside an isolated Worker sandbox (env.LOADER).
+
+## `terminal` (1)
+
+- **`agentsam_code_interpreter`** (Code interpreter (Python crunch)) — Execute Python for calculations, data transformation, analysis, and generated files on the current local execution host. _never used_
+
+## `terminal.execute` (1)
+
+- **`agentsam_terminal_sandbox`** (Terminal Sandbox) — Isolated cloud shell in a CF Container sandbox (MY_CONTAINER). Use for experiment zones (zone_slug: engineer, architect, cms, specialist) and disposable builds. For persistent operator repo state on the cloud desk prefer agentsam_terminal_remote; for your own machine use agentsam_terminal_local. _risk: high_
+
+## `terminal.local` (1)
+
+- **`agentsam_terminal_local`** (Terminal Local) — Run a shell command on the signed-in user's own machine via their provisioned device tunnel. Requires Settings → Terminal device setup. Not for cloud VM — use agentsam_terminal_remote when away from desk, or agentsam_terminal_sandbox for an isolated cloud shell. Do not use shell for file edits when fs_edit_file / agentsam_github_patch can do it — shell bypasses exact-match and diff guarantees. _risk: high, ★ heavily used (311 calls)_
+
+## `terminal.remote` (1)
+
+- **`agentsam_terminal_remote`** (Terminal Remote) — Run a shell command on the platform cloud desk (always-on VM). Primary lane for ChatGPT/Claude connectors and phone when the desk machine is asleep — git, wrangler worker-only, sparse repo clones. Prefer this over sandbox for persistent operator repo state. _risk: high, ★ heavily used (129 calls)_

package/docs/tools/tickets-and-platform.md

@@ -0,0 +1,30 @@
+# Tickets & Platform
+
+The ticket lifecycle (create/get/list/set-status/add-note), plus platform-level admin: MCP audit log, ship-check, checkout-root pin/get/clear, ping.
+
+**13 tools** in this domain.
+
+## `platform` (4)
+
+- **`agentsam_checkout_root_clear`** (Checkout root clear) — Clear the sticky checkout_root pin for this MCP session. _never used_
+- **`agentsam_checkout_root_get`** (Checkout root get) — Return the sticky checkout_root for this MCP session (if pinned). _never used_
+- **`agentsam_checkout_root_pin`** (Checkout root pin) — Pin absolute checkout_root for this MCP session (sticky). Dual-agent worktrees: pass absolute worktree path once so relative fs/terminal paths resolve there — never silent operator main. _never used_
+- **`agentsam_ping`** (Ping) — Liveness ping. Returns MCP server version and whether D1 is bound. No workspace or tenant identity. No side effects.
+
+## `platform.audit` (1)
+
+- **`agentsam_mcp_audit`** (MCP Audit Log) — Read recent MCP tool calls for your connected account. Scoped by auth user, not workspace. _never used_
+
+## `platform.ship` (2)
+
+- **`agentsam_d1_validate_migration`** (D1 Validate Migration (dry-run)) — When editing or reviewing a migration SQL file, statically validate it (memory_id, destructive DDL, conflict targets) before apply. Pass sql, files[], or GitHub paths[]. _never used_
+- **`agentsam_ship_check`** (Ship Check (dual-repo migrations)) — When preparing deploy:full or ship:remote, run preflight across BOTH monorepo and MCP migrations trees vs d1_migrations ledger, with static SQL validation on pending files. _never used_
+
+## `tickets` (6)
+
+- **`agentsam_ticket`** (Ticket) — Platform tickets — one tool for list/get/create/set_status/add_note. Pass operation. Reads need ticket.read; create/add_note need ticket.write; set_status needs ticket.status. _never used_
+- **`agentsam_ticket_add_note`** (Ticket Add Note) — Append a note and/or attach visual proof to a platform ticket. Note optional when attachment fields present. _never used_
+- **`agentsam_ticket_create`** (Ticket Create) — Create a platform engineering ticket. Pass dedup_key to avoid double-create on retry. _never used_
+- **`agentsam_ticket_get`** (Ticket Get) — Get one platform ticket by id. _never used_
+- **`agentsam_ticket_list`** (Ticket List) — List platform engineering tickets (agentsam_tickets). Filters: status, project, subsystem, priority. _never used_
+- **`agentsam_ticket_set_status`** (Ticket Set Status) — Set ticket status (server enforces status_reason for blocked/abandoned). _never used_

package/migrations/d1/0001_agentsam_plugin_runtime.sql

@@ -0,0 +1,177 @@
+-- Canonical portable plugin/tool registry for AgentSam applications.
+-- OAuth ciphertext remains in provider-owned connection tables encrypted by
+-- the application's own vault key; these rows contain metadata and evidence.
+
+CREATE TABLE IF NOT EXISTS agentsam_plugins (
+  id TEXT PRIMARY KEY DEFAULT ('plg_' || lower(hex(randomblob(8)))),
+  account_id TEXT NOT NULL,
+  plugin_key TEXT NOT NULL,
+  provider_key TEXT NOT NULL,
+  installation_key TEXT NOT NULL DEFAULT 'default',
+  environment TEXT NOT NULL DEFAULT 'production' CHECK (environment IN ('development','preview','staging','production')),
+  plugin_kind TEXT NOT NULL CHECK (plugin_kind IN ('mcp','api','oauth','native','webhook','database','storage','ai')),
+  category TEXT NOT NULL DEFAULT 'integration',
+  display_name TEXT NOT NULL,
+  short_name TEXT,
+  description TEXT,
+  mention_aliases_json TEXT NOT NULL DEFAULT '[]',
+  endpoint_url TEXT,
+  transport TEXT NOT NULL CHECK (transport IN ('remote_jsonrpc','iam_mcp_catalog','http_rest','http_graphql','webhook','workers_binding','native','none')),
+  auth_type TEXT NOT NULL DEFAULT 'none' CHECK (auth_type IN ('none','bridge','oauth','oauth_via_iam','bearer_secret','api_key_secret','workers_binding')),
+  secret_ref TEXT,
+  oauth_connect_url TEXT,
+  capabilities_json TEXT NOT NULL DEFAULT '[]',
+  tool_lanes_json TEXT NOT NULL DEFAULT '[]',
+  resource_scope_json TEXT NOT NULL DEFAULT '{}',
+  config_json TEXT NOT NULL DEFAULT '{}',
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  icon_url TEXT,
+  icon_dark_url TEXT,
+  icon_alt TEXT,
+  icon_fit TEXT NOT NULL DEFAULT 'contain' CHECK (icon_fit IN ('contain','cover')),
+  composer_visible INTEGER NOT NULL DEFAULT 1 CHECK (composer_visible IN (0,1)),
+  settings_visible INTEGER NOT NULL DEFAULT 1 CHECK (settings_visible IN (0,1)),
+  sort_priority INTEGER NOT NULL DEFAULT 50,
+  is_enabled INTEGER NOT NULL DEFAULT 1 CHECK (is_enabled IN (0,1)),
+  setup_status TEXT NOT NULL DEFAULT 'unconfigured' CHECK (setup_status IN ('unconfigured','configured','connected','disabled')),
+  health_strategy TEXT NOT NULL DEFAULT 'adapter' CHECK (health_strategy IN ('none','adapter','mcp_ping','oauth_probe','provider_probe')),
+  health_status TEXT NOT NULL DEFAULT 'unknown' CHECK (health_status IN ('unknown','healthy','degraded','unhealthy','unreachable','auth_error','disabled')),
+  last_health_at INTEGER,
+  last_healthy_at INTEGER,
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
+  avg_latency_ms REAL,
+  error_rate_24h REAL NOT NULL DEFAULT 0,
+  last_error_code TEXT,
+  last_error_message TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  UNIQUE (account_id, environment, plugin_key, installation_key)
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_plugin_health_checks (
+  id TEXT PRIMARY KEY DEFAULT ('plgh_' || lower(hex(randomblob(8)))),
+  plugin_id TEXT NOT NULL REFERENCES agentsam_plugins(id) ON DELETE CASCADE,
+  plugin_key TEXT NOT NULL,
+  account_id TEXT NOT NULL,
+  environment TEXT NOT NULL,
+  check_kind TEXT NOT NULL,
+  check_source TEXT NOT NULL DEFAULT 'scheduled' CHECK (check_source IN ('scheduled','manual','page_load','tool_call','deploy','startup')),
+  status TEXT NOT NULL CHECK (status IN ('healthy','degraded','unhealthy','unreachable','auth_error')),
+  started_at INTEGER NOT NULL,
+  completed_at INTEGER NOT NULL,
+  latency_ms INTEGER,
+  http_status INTEGER,
+  provider_request_id TEXT,
+  error_code TEXT,
+  error_message TEXT,
+  details_json TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_capabilities (
+  capability_key TEXT PRIMARY KEY,
+  domain TEXT NOT NULL,
+  verb TEXT NOT NULL,
+  description TEXT NOT NULL,
+  is_mutating INTEGER NOT NULL DEFAULT 0 CHECK (is_mutating IN (0,1)),
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0,1)),
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_tools (
+  id TEXT PRIMARY KEY DEFAULT ('ast_' || lower(hex(randomblob(8)))),
+  tool_name TEXT NOT NULL UNIQUE,
+  display_name TEXT NOT NULL,
+  tool_category TEXT NOT NULL,
+  handler_type TEXT NOT NULL DEFAULT 'mcp' CHECK (handler_type IN ('mcp','r2','github','terminal','http','proxy','ai','d1','hyperdrive','supabase','kv','durable_object','filesystem','browser_agentic','mybrowser','websearch','telemetry','eval','task.planner','task.organizer','task.manager','workspace.reader','cf','deploy','git','memory','notify','workflow','agent','browser','media','canvas','integrations','cms','completeful','vectorize')),
+  description TEXT,
+  input_schema TEXT,
+  output_schema TEXT,
+  linked_mcp_tool_id TEXT,
+  mcp_service_url TEXT,
+  handler_config TEXT DEFAULT '{}',
+  intent_tags TEXT DEFAULT '[]',
+  intent_category_tags TEXT,
+  modes_json TEXT DEFAULT '["agent","plan","debug","multitask","ask"]',
+  risk_level TEXT NOT NULL DEFAULT 'low' CHECK (risk_level IN ('low','medium','high','critical')),
+  requires_approval INTEGER NOT NULL DEFAULT 0,
+  requires_confirmation INTEGER NOT NULL DEFAULT 0,
+  token_budget_per_call INTEGER,
+  max_calls_per_session INTEGER,
+  cost_per_call_usd REAL DEFAULT 0.0,
+  is_active INTEGER NOT NULL DEFAULT 1,
+  is_degraded INTEGER NOT NULL DEFAULT 0,
+  failure_rate REAL DEFAULT 0.0,
+  avg_latency_ms REAL,
+  use_count INTEGER NOT NULL DEFAULT 0,
+  last_used_at INTEGER,
+  last_health_check INTEGER,
+  sort_priority INTEGER DEFAULT 50,
+  workspace_scope TEXT NOT NULL DEFAULT '["*"]',
+  subagent_profile_id TEXT,
+  schema_hint TEXT,
+  notes TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  is_global INTEGER DEFAULT 1,
+  tool_key TEXT,
+  capability_key TEXT,
+  handler_key TEXT,
+  route_key TEXT,
+  workflow_key TEXT,
+  task_type TEXT DEFAULT 'tool_use',
+  domain TEXT DEFAULT 'general',
+  capability_tier TEXT DEFAULT 'common',
+  internal_seo TEXT DEFAULT '',
+  tool_code TEXT,
+  oauth_visible INTEGER NOT NULL DEFAULT 0,
+  dispatch_target TEXT NOT NULL DEFAULT 'internal',
+  result_policy_json TEXT,
+  caller_policy TEXT,
+  cache_policy_json TEXT,
+  updated_at_unix INTEGER,
+  connector_visible INTEGER NOT NULL DEFAULT 0 CHECK (connector_visible IN (0,1)),
+  connector_priority INTEGER,
+  connector_access_class TEXT NOT NULL DEFAULT 'read' CHECK (connector_access_class IN ('read','write')),
+  account_id TEXT,
+  plugin_key TEXT,
+  plugin_id TEXT REFERENCES agentsam_plugins(id) ON DELETE SET NULL
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_tool_capabilities (
+  tool_id TEXT NOT NULL REFERENCES agentsam_tools(id) ON DELETE CASCADE,
+  capability_key TEXT NOT NULL REFERENCES agentsam_capabilities(capability_key),
+  requirement_type TEXT NOT NULL DEFAULT 'required' CHECK (requirement_type='required'),
+  is_primary INTEGER NOT NULL DEFAULT 0 CHECK (is_primary IN (0,1)),
+  operations_json TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  PRIMARY KEY (tool_id, capability_key)
+);
+
+CREATE TABLE IF NOT EXISTS agentsam_tool_call_log (
+  id TEXT PRIMARY KEY DEFAULT ('atcl_' || lower(hex(randomblob(8)))),
+  account_id TEXT NOT NULL,
+  agent_run_id TEXT,
+  conversation_id TEXT,
+  call_index INTEGER,
+  tool_key TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('success','error','blocked','timeout','cancelled')),
+  duration_ms INTEGER NOT NULL DEFAULT 0,
+  error_code TEXT NOT NULL DEFAULT '',
+  failure_origin TEXT CHECK (failure_origin IS NULL OR failure_origin IN ('model','tool','provider','platform','policy','user')),
+  cost_usd REAL NOT NULL DEFAULT 0,
+  input_tokens INTEGER NOT NULL DEFAULT 0,
+  output_tokens INTEGER NOT NULL DEFAULT 0,
+  cost_basis TEXT NOT NULL DEFAULT 'unknown' CHECK (cost_basis IN ('api_metered','external_subscription','platform_included','unknown')),
+  source_client TEXT NOT NULL DEFAULT 'unknown',
+  cache_hit INTEGER NOT NULL DEFAULT 0,
+  external_execution INTEGER NOT NULL DEFAULT 1,
+  result_source TEXT CHECK (result_source IS NULL OR result_source IN ('live','tool_cache')),
+  created_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  cache_eligible INTEGER NOT NULL DEFAULT 0 CHECK (cache_eligible IN (0,1)),
+  cache_lookup_reason TEXT,
+  cache_lookup_ms INTEGER,
+  cache_key_hash TEXT,
+  cache_input_hash TEXT
+);

package/migrations/d1/0002_agentsam_ticket_ownership.sql

@@ -0,0 +1,8 @@
+-- Add explicit account/repository ownership to pre-existing GOAP tickets.
+-- Existing rows remain nullable because their historical owner cannot be
+-- inferred safely; new AgentSam-created goals always populate both fields.
+ALTER TABLE agentsam_tickets ADD COLUMN account_id TEXT;
+ALTER TABLE agentsam_tickets ADD COLUMN repository_id TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_tickets_account_repository
+  ON agentsam_tickets(account_id, repository_id, updated_at DESC);

package/migrations/d1/0002_dynamic_model_policies.sql

@@ -0,0 +1,23 @@
+-- Provider/model working-set policy is runtime configuration, not prompt text.
+-- Apps may seed this from their provider catalog; the SDK remains provider-neutral.
+CREATE TABLE IF NOT EXISTS agentsam_model_policies (
+  provider TEXT NOT NULL,
+  model_key TEXT NOT NULL,
+  target_input_tokens INTEGER,
+  compact_at_tokens INTEGER,
+  intervene_at_tokens INTEGER,
+  max_normal_input_tokens INTEGER,
+  pricing_threshold_tokens INTEGER,
+  max_cumulative_input_tokens INTEGER,
+  safety_margin_tokens INTEGER,
+  compaction_strategy TEXT NOT NULL DEFAULT 'provider_or_runtime'
+    CHECK (compaction_strategy IN ('provider_or_runtime','provider_native','runtime_summary','none')),
+  policy_source TEXT NOT NULL DEFAULT 'application'
+    CHECK (policy_source IN ('application','provider','catalog','operator')),
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0,1)),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  PRIMARY KEY (provider, model_key)
+);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_model_policies_active
+  ON agentsam_model_policies(provider, is_active);

package/migrations/d1/0003_expand_tool_handler_families.sql

@@ -0,0 +1,18 @@
+-- Native provider families are carried by handler_key so this migration is
+-- safe for the existing agentsam_tools CHECK constraint (`cms` is the
+-- ecommerce native family). This registry lets dispatchers discover provider
+-- identity without rebuilding a table referenced by legacy views.
+CREATE TABLE IF NOT EXISTS agentsam_tool_handler_families (
+  handler_family TEXT PRIMARY KEY,
+  handler_type TEXT NOT NULL,
+  dispatch_target TEXT NOT NULL,
+  description TEXT NOT NULL,
+  is_active INTEGER NOT NULL DEFAULT 1 CHECK (is_active IN (0,1)),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+INSERT OR REPLACE INTO agentsam_tool_handler_families
+  (handler_family, handler_type, dispatch_target, description, updated_at)
+VALUES
+  ('ecommerce-cms-agentsam.completeful', 'cms', 'native', 'Completeful curated ecommerce capabilities.', unixepoch()),
+  ('project.vectorize', 'vectorize', 'native', 'Project-declared Vectorize binding/index/model lane.', unixepoch());

package/migrations/d1/0004_project_aware_retrieval_lanes.sql

@@ -0,0 +1,24 @@
+-- Retrieval lanes are provider-neutral. A lane may live in pgvector,
+-- Vectorize, Hyperdrive, D1, or another store; the project row names the
+-- actual database/resource used at runtime.
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN account_id TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN repository_id TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN database_id TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN backend_kind TEXT NOT NULL DEFAULT 'pgvector';
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN provider_key TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN resource_id TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN binding_name TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN index_name TEXT;
+ALTER TABLE agentsam_pgvector_lane_registry ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}';
+
+ALTER TABLE agentsam_rag_intent_routes ADD COLUMN account_id TEXT;
+ALTER TABLE agentsam_rag_intent_routes ADD COLUMN repository_id TEXT;
+ALTER TABLE agentsam_rag_intent_routes ADD COLUMN database_id TEXT;
+ALTER TABLE agentsam_rag_intent_routes ADD COLUMN resource_scope_json TEXT NOT NULL DEFAULT '{}';
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_lane_project
+  ON agentsam_pgvector_lane_registry(account_id, repository_id, is_active);
+CREATE INDEX IF NOT EXISTS idx_agentsam_lane_database
+  ON agentsam_pgvector_lane_registry(database_id, backend_kind, is_active);
+CREATE INDEX IF NOT EXISTS idx_agentsam_rag_route_project
+  ON agentsam_rag_intent_routes(account_id, repository_id, is_active);

package/migrations/d1/0005_portable_knowledge_identity.sql

@@ -0,0 +1,104 @@
+-- AutoRAG uses the existing knowledge lifecycle. This migration refines its
+-- identity scope; it deliberately creates no parallel autorag run/chunk tables.
+PRAGMA foreign_keys = OFF;
+
+-- This pre-existing view is currently invalid because agentsam_agent_run was
+-- already normalized to account authority. Drop/recreate it around the table
+-- rebuild so D1 can revalidate schema atomically.
+DROP VIEW IF EXISTS v_agentsam_ops_trail;
+
+ALTER TABLE agentsam_knowledge_runs ADD COLUMN account_id TEXT;
+ALTER TABLE agentsam_knowledge_runs ADD COLUMN repository_id TEXT;
+ALTER TABLE agentsam_knowledge_runs ADD COLUMN project_key TEXT;
+ALTER TABLE agentsam_knowledge_runs ADD COLUMN lane_id TEXT;
+
+-- Legacy rows remain addressable through workspace_id, but new code must use
+-- authenticated account + repository/project/lane ownership.
+UPDATE agentsam_knowledge_runs
+SET account_id = COALESCE(account_id, 'legacy:' || COALESCE(NULLIF(tenant_id, ''), NULLIF((SELECT tenant_id FROM agentsam_knowledge_generation WHERE workspace_id = agentsam_knowledge_runs.workspace_id), ''), 'unknown')),
+    repository_id = COALESCE(repository_id, 'legacy:workspace:' || workspace_id),
+    project_key = COALESCE(project_key, workspace_id),
+    lane_id = COALESCE(lane_id, 'default');
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_knowledge_runs_portable_scope
+  ON agentsam_knowledge_runs(account_id, repository_id, project_key, lane_id, updated_at);
+
+-- The historical workspace primary key prevented one account from maintaining
+-- independent repository/lane generations. Rebuild the same table safely and
+-- retain a legacy_workspace_id read path for old callers.
+ALTER TABLE agentsam_knowledge_generation RENAME TO agentsam_knowledge_generation_legacy;
+CREATE TABLE agentsam_knowledge_generation (
+  account_id TEXT NOT NULL,
+  repository_id TEXT NOT NULL,
+  project_key TEXT NOT NULL,
+  lane_id TEXT NOT NULL,
+  generation INTEGER NOT NULL DEFAULT 1,
+  legacy_workspace_id TEXT UNIQUE,
+  tenant_id TEXT,
+  updated_at_unix INTEGER NOT NULL DEFAULT (unixepoch()),
+  PRIMARY KEY (account_id, repository_id, project_key, lane_id)
+);
+INSERT INTO agentsam_knowledge_generation (
+  account_id, repository_id, project_key, lane_id, generation,
+  legacy_workspace_id, tenant_id, updated_at_unix
+)
+SELECT
+  'legacy:' || COALESCE(NULLIF(tenant_id, ''), 'unknown'),
+  'legacy:workspace:' || workspace_id,
+  workspace_id,
+  'default',
+  generation,
+  workspace_id,
+  tenant_id,
+  updated_at_unix
+FROM agentsam_knowledge_generation_legacy;
+DROP TABLE agentsam_knowledge_generation_legacy;
+CREATE INDEX IF NOT EXISTS idx_agentsam_knowledge_generation_legacy_workspace
+  ON agentsam_knowledge_generation(legacy_workspace_id);
+
+-- intent_key was globally unique, which made a repository-specific override
+-- impossible. Preserve all records while making the effective lookup order
+-- repository -> account -> portable default possible.
+ALTER TABLE agentsam_rag_intent_routes RENAME TO agentsam_rag_intent_routes_legacy;
+CREATE TABLE agentsam_rag_intent_routes (
+  id TEXT PRIMARY KEY,
+  intent_key TEXT NOT NULL,
+  lane_order_json TEXT NOT NULL,
+  description TEXT,
+  is_active INTEGER NOT NULL DEFAULT 1,
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch()),
+  account_id TEXT,
+  repository_id TEXT,
+  database_id TEXT,
+  resource_scope_json TEXT NOT NULL DEFAULT '{}',
+  UNIQUE(account_id, repository_id, intent_key)
+);
+INSERT INTO agentsam_rag_intent_routes (
+  id, intent_key, lane_order_json, description, is_active, updated_at,
+  account_id, repository_id, database_id, resource_scope_json
+)
+SELECT id, intent_key, lane_order_json, description, is_active, updated_at,
+  account_id, repository_id, database_id, resource_scope_json
+FROM agentsam_rag_intent_routes_legacy;
+DROP TABLE agentsam_rag_intent_routes_legacy;
+CREATE INDEX IF NOT EXISTS idx_agentsam_rag_route_effective_lookup
+  ON agentsam_rag_intent_routes(intent_key, account_id, repository_id, is_active);
+
+-- The compatibility lane registry remains the single physical lane registry.
+-- New writes must name backend/resource/binding/index explicitly in the host
+-- adapter; legacy pgvector rows remain readable until their host is migrated.
+CREATE INDEX IF NOT EXISTS idx_agentsam_lane_explicit_resource
+  ON agentsam_pgvector_lane_registry(backend_kind, database_id, resource_id, binding_name, index_name, dimensions, is_active);
+
+CREATE VIEW v_agentsam_ops_trail AS
+SELECT 'agent_run' AS source_table,id AS event_id,created_at_unix AS ts_unix,COALESCE(status,'unknown') AS event_kind,'' AS workspace_id,COALESCE(account_id,'') AS user_id,COALESCE(conversation_id,'') AS conversation_id,COALESCE(model_key,'') AS detail,CAST(NULL AS TEXT) AS error_message FROM agentsam_agent_run WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'tool_call_log',id,created_at_unix,COALESCE(status,'unknown'),'',COALESCE(account_id,''),COALESCE(conversation_id,''),COALESCE(tool_key,''),error_code FROM agentsam_tool_call_log WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'error_log',id,created_at,COALESCE(error_type,'error'),'',COALESCE(account_id,''),COALESCE(session_id,''),COALESCE(source,''),error_message FROM agentsam_error_log WHERE created_at IS NOT NULL
+UNION ALL
+SELECT 'mcp_tool_execution',CAST(id AS TEXT),created_at_unix,CASE WHEN success=1 THEN 'success' ELSE 'error' END,'',COALESCE(user_id,''),'',COALESCE(tool_key,tool_name,''),error_message FROM agentsam_mcp_tool_execution WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'deployment_health',id,COALESCE(checked_at_unix,last_checked_at),COALESCE(status,'health'),'',COALESCE(account_id,''),'',COALESCE(worker_name,''),error_message FROM agentsam_deployment_health WHERE COALESCE(checked_at_unix,last_checked_at) IS NOT NULL;
+
+PRAGMA foreign_keys = ON;

package/migrations/d1/0006_repair_ops_trail_account_scope.sql

@@ -0,0 +1,14 @@
+-- 0005 exposed a pre-existing stale workspace column in the operations view.
+-- Operations telemetry is account-owned now; retain the legacy output column
+-- as an empty compatibility field rather than inventing a workspace mapping.
+DROP VIEW IF EXISTS v_agentsam_ops_trail;
+CREATE VIEW v_agentsam_ops_trail AS
+SELECT 'agent_run' AS source_table,id AS event_id,created_at_unix AS ts_unix,COALESCE(status,'unknown') AS event_kind,'' AS workspace_id,COALESCE(account_id,'') AS user_id,COALESCE(conversation_id,'') AS conversation_id,COALESCE(model_key,'') AS detail,CAST(NULL AS TEXT) AS error_message FROM agentsam_agent_run WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'tool_call_log',id,created_at_unix,COALESCE(status,'unknown'),'',COALESCE(account_id,''),COALESCE(conversation_id,''),COALESCE(tool_key,''),error_code FROM agentsam_tool_call_log WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'error_log',id,created_at,COALESCE(error_type,'error'),'',COALESCE(account_id,''),COALESCE(session_id,''),COALESCE(source,''),error_message FROM agentsam_error_log WHERE created_at IS NOT NULL
+UNION ALL
+SELECT 'mcp_tool_execution',CAST(id AS TEXT),created_at_unix,CASE WHEN success=1 THEN 'success' ELSE 'error' END,'',COALESCE(user_id,''),'',COALESCE(tool_key,tool_name,''),error_message FROM agentsam_mcp_tool_execution WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'deployment_health',id,COALESCE(checked_at_unix,last_checked_at),COALESCE(status,'health'),'',COALESCE(account_id,''),'',COALESCE(worker_name,''),error_message FROM agentsam_deployment_health WHERE COALESCE(checked_at_unix,last_checked_at) IS NOT NULL;

package/migrations/d1/0007_repair_ops_trail_agent_run_account.sql

@@ -0,0 +1,13 @@
+-- SQLite resolves every COALESCE argument at prepare time. The old view kept
+-- a removed user_id fallback even though account_id is now authoritative.
+DROP VIEW IF EXISTS v_agentsam_ops_trail;
+CREATE VIEW v_agentsam_ops_trail AS
+SELECT 'agent_run' AS source_table,id AS event_id,created_at_unix AS ts_unix,COALESCE(status,'unknown') AS event_kind,'' AS workspace_id,COALESCE(account_id,'') AS user_id,COALESCE(conversation_id,'') AS conversation_id,COALESCE(model_key,'') AS detail,CAST(NULL AS TEXT) AS error_message FROM agentsam_agent_run WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'tool_call_log',id,created_at_unix,COALESCE(status,'unknown'),'',COALESCE(account_id,''),COALESCE(conversation_id,''),COALESCE(tool_key,''),error_code FROM agentsam_tool_call_log WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'error_log',id,created_at,COALESCE(error_type,'error'),'',COALESCE(account_id,''),COALESCE(session_id,''),COALESCE(source,''),error_message FROM agentsam_error_log WHERE created_at IS NOT NULL
+UNION ALL
+SELECT 'mcp_tool_execution',CAST(id AS TEXT),created_at_unix,CASE WHEN success=1 THEN 'success' ELSE 'error' END,'',COALESCE(user_id,''),'',COALESCE(tool_key,tool_name,''),error_message FROM agentsam_mcp_tool_execution WHERE created_at_unix IS NOT NULL
+UNION ALL
+SELECT 'deployment_health',id,COALESCE(checked_at_unix,last_checked_at),COALESCE(status,'health'),'',COALESCE(account_id,''),'',COALESCE(worker_name,''),error_message FROM agentsam_deployment_health WHERE COALESCE(checked_at_unix,last_checked_at) IS NOT NULL;

package/migrations/d1/0008_backfill_knowledge_run_legacy_tenant.sql

@@ -0,0 +1,14 @@
+-- Complete the portable identity backfill for runs whose historical row did
+-- not carry tenant_id but whose legacy active generation did.
+UPDATE agentsam_knowledge_runs
+SET account_id = 'legacy:' || (
+  SELECT tenant_id FROM agentsam_knowledge_generation generation
+  WHERE generation.legacy_workspace_id = agentsam_knowledge_runs.workspace_id
+)
+WHERE account_id = 'legacy:unknown'
+  AND EXISTS (
+    SELECT 1 FROM agentsam_knowledge_generation generation
+    WHERE generation.legacy_workspace_id = agentsam_knowledge_runs.workspace_id
+      AND generation.tenant_id IS NOT NULL
+      AND generation.tenant_id <> ''
+  );