@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/docs/REPO_FILE_MAP.txt

@@ -0,0 +1,132 @@
+AGENTSAM SDK - REPOSITORY FILE MAP
+=================================
+ASCII orientation map; logical map, not exhaustive per-file inventory.
+Scope: tracked layout. Generated, ignored, and machine-local content is omitted.
+Baseline evidence: repository audit on feat/public-package-graduation.
+Use git status / agentsam context for the current revision rather than treating
+this orientation map as revision authority.
+
+1. SYSTEM WIREFRAME
+-------------------
+
+  Consumer / developer
+       |
+       +--> README.md, DEVELOPMENT.md, docs/ -------- architecture, contracts, guidance
+       +--> bin/agentsam ------------------------------ CLI launcher
+       |      +--> src/cli + src/commands ----------- CLI composition
+       |      +--> src/index.* ----------------------- SDK public facade
+       |      +--> src/sam --------------------------- typed execution spine
+       |      `--> src/* ----------------------------- SDK domains and adapters
+       +--> package.json / package-lock.json --------- root npm product and lockfile
+              +--> packages/* ------------------------ reusable packages
+              +--> apps/* ---------------------------- product applications
+              `--> services/* ------------------------ service implementations
+
+  Shared vocabulary: protocol/* + contracts/* + packages/agentsam-contracts
+  Data schemas:      migrations/{runtime,sqlite,d1}
+  Provider seams:    src/providers, src/cloudflare, packages/connectors/*
+  Verification:      test/*, package-local tests, scripts/verify-* and npm gates
+
+2. TOP-LEVEL FILE MAP
+---------------------
+
+  /
+  |-- README.md, DEVELOPMENT.md, AGENTSAM.md, .agentsamrules
+  |      Product overview, contributor workflow, runtime/repo instructions.
+  |-- package.json, package-lock.json, tsconfig.base.json
+  |      Root package/workspaces, dependency lock, shared TypeScript settings.
+  |-- agentsam.yaml, .agentsam/config.json
+  |      Portable project config and host/install config (not run history).
+  |-- bin/                 CLI launchers
+  |-- src/                 ROOT SDK AND CLI IMPLEMENTATION
+  |   |-- index, cli, commands       Public facade and command composition
+  |   |-- sam, schemas, rpc, errors  Execution kernel and typed boundaries
+  |   |-- agent, models, providers   Agent/model/provider seams
+  |   |-- repository, context, indexing, knowledge
+  |   |-- security, local, local-fs, capabilities, tools
+  |   |-- cloudflare, plugins, features, skills, telemetry, eval
+  |   `-- lib/                      Legacy extraction zone (see SOURCE_ARCHITECTURE.md)
+  |-- packages/             REUSABLE PACKAGE BOUNDARIES
+  |   |-- contracts, errors, runtime-protocol
+  |   |-- identity, key-manager, vault, settings
+  |   |-- repository, knowledge, work-graph, work, workbench, queue-control, goap
+  |   |-- connectors/*, providers/*
+  |   |-- brand, content*, assets-core, cloudflare-images, scoring
+  |   |-- nav, shell-kit, desktop-shell, ide, database-editor
+  |   `-- theme-* / heuristic-theme / docs-theme
+  |       Examples/families, not an exhaustive package list.
+  |-- apps/                 PRODUCT APPLICATIONS
+  |   |-- local-studio, project-control, frontend, theme-gallery-preview
+  |   |-- cad-creator, client-cms-editor, ecommerce-cms-agentsam
+  |   |-- agentsam-go-worker, agentsamd
+  |   |-- church-site, companions-site, floors-site, fuelnfree-site,
+  |   |   handyman-site, insurance-site, shinshu-site
+  |   `-- _incoming/         Intake area
+  |       App-specific frontend/backend/shared code and deployment configs stay
+  |       with the app; see docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md.
+  |-- services/              Standalone service areas (cad, knowledge)
+  |-- protocol/              Cross-system protocol definitions (SAM, runtime,
+  |   |                      repository, database, apps, skills, etc.)
+  |   `-- README.md           Ownership and host-adapter boundaries
+  |-- contracts/             Root-level contract artifacts
+  |-- migrations/            d1, runtime, sqlite migration families
+  |-- test/                  Root unit, CLI, integration, terminal, live, Go tests
+  |-- scripts/               Generation, verification, release, site, tooling
+  |-- python/                Python SDK/tooling, tests, docs
+  |-- native/                Native machine/runtime component(s)
+  |-- docs/                  Architecture, product, tools, ops, plans
+  |   |-- architecture/      System boundaries and architecture contracts
+  |   |-- product/           Lifecycle and UX standards
+  |   |-- tools/             Capability/tool references
+  |   `-- plans/             Dated plans/handoffs; not implementation SSOT
+  |-- skills/                Portable skill definitions
+  |-- templates/             Scaffolding templates
+  |-- registry/              Tool and domain registries
+  |-- examples/, assets/     Examples and shared assets
+  |-- sites/                 Public-site source/content
+  |-- focus-timer/           Separate tracked top-level mini-app/site
+  |-- .github/, .changeset/  CI workflows and release metadata
+  `-- tags/                  Repository tag metadata
+
+3. AUDIT / NAVIGATION NOTES
+---------------------------
+
+  * docs/SOURCE_ARCHITECTURE.md defines root src as the SDK/package composition
+    layer and calls src/lib a legacy extraction zone. Put new reusable modules in
+    a coherent owned package instead of adding unrelated code to src/lib.
+  * package.json explicitly enumerates root npm workspaces. Not every directory
+    under packages/ is necessarily a configured workspace: check before using
+    workspace commands or assuming it is published.
+  * protocol/, packages/agentsam-contracts, and root contracts/ are distinct
+    locations. Follow their local ownership docs instead of conflating them.
+  * Select the correct migration family and owning app/service before changing data
+    schemas. App-specific seeds and bindings belong with the consuming app.
+  * APP identity/validation: docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md;
+    root gates are npm run app:validate / npm run guard:apps.
+  * Local filesystem discovery also surfaced folders such as generated/, .wrangler/,
+    level-1/, test2/, and agentsam-originalsetup-inspect/. They are omitted here:
+    this map describes tracked repository roots, not every local/ignored directory.
+  * Public package distribution is audited by agentsam package audit/status/verify/
+    publish-plan. A publishConfig alone is intent, not proof that a package is
+    consumer-ready.
+  * native/agentsam-machine is the Rust machine-perception workspace. Its CLI resolves
+    from PATH, a built repo binary, or a Cargo fallback; treat native distribution as
+    its own release lane rather than assuming the npm package publishes a native binary.
+  * This file is an orientation map, not implementation or release authority.
+
+4. QUICK TEST / RELEASE ENTRY POINTS
+------------------------------------
+
+  npm run test:standard       focused root test bundle
+  npm run test:workspaces     selected package tests/typechecks
+  npm run verify              broad SDK/package/app/boundary/package checks
+  npm run verify:release      verify + knowledge package + Python + release security
+  npm run app:validate        validate all product app manifests
+  agentsam package audit --public
+                            compare public intent with registry/quality state
+  agentsam package verify <name>
+                            run declared package gates + npm pack dry-run
+  agentsam package publish-plan
+                            dependency-ordered, read-only publication plan
+
+Use DEVELOPMENT.md and each package/app README for current, more detailed commands.

package/migrations/d1/0018_goap_control_plane_remaster.sql

@@ -0,0 +1,40 @@
+-- 0018_goap_control_plane_remaster.sql
+-- Additive ticket/event contract remaster only: no new GOAP table family.
+--
+-- This migration intentionally targets tables owned by the portable D1/SQLite
+-- control-plane baseline (0010) and equivalent legacy host tables.
+-- Blackboard/workspace state is a runtime concern and is evolved separately by
+-- migrations/runtime/0002_goap_blackboard_v1.sql.
+--
+-- NOTE: account_id/repository_id are intentionally NOT added to ticket_events here.
+-- Portable 0010 already has them, while the legacy platform table does not.
+-- The GOAP adapter supports eventOwnership=ticket_join for that host shape until a
+-- dedicated platform-only ownership repair is intentionally applied.
+
+ALTER TABLE agentsam_tickets
+  ADD COLUMN goal_schema TEXT;
+
+ALTER TABLE agentsam_tickets
+  ADD COLUMN goal_spec_json TEXT
+    CHECK (goal_spec_json IS NULL OR json_valid(goal_spec_json));
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN payload_json TEXT NOT NULL DEFAULT '{}'
+    CHECK (json_valid(payload_json));
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN workflow_run_id TEXT;
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN execution_step_id TEXT;
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN schema_version TEXT NOT NULL DEFAULT 'agentsam.event.v1';
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_ticket_events_workflow_run
+  ON agentsam_ticket_events(workflow_run_id, created_at)
+  WHERE workflow_run_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_ticket_events_execution_step
+  ON agentsam_ticket_events(execution_step_id, created_at)
+  WHERE execution_step_id IS NOT NULL;

package/migrations/d1/0019_agentsam_agent_run_plan_todo.sql

@@ -0,0 +1,14 @@
+-- 0019_agentsam_agent_run_plan_todo.sql
+-- Attribute remote AgentSam run attempts to the durable plan/TODO that caused them.
+-- This mirrors migrations/runtime/0004_agent_run_plan_linkage.sql for local SQLite.
+ALTER TABLE agentsam_agent_run
+  ADD COLUMN plan_id TEXT REFERENCES agentsam_plans(id) ON DELETE SET NULL;
+
+ALTER TABLE agentsam_agent_run
+  ADD COLUMN todo_id TEXT REFERENCES agentsam_todo(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_plan
+  ON agentsam_agent_run(account_id, plan_id, created_at_unix DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_todo
+  ON agentsam_agent_run(account_id, todo_id, created_at_unix DESC);

package/migrations/d1/README_PORTABLE_CONTROL_PLANE.md

@@ -1,16 +1,27 @@
-# Portable control-plane schemas (tickets · memory · skills · tools)
+# Portable control-plane schemas (tickets · memory · skills · tools · GOAP)
 
-Apply from the repo that owns the SQL (agentsam-sdk `migrations/d1/`).
+Apply schema families from the repo that owns them. Portable D1/ticket state and
+runtime blackboard state have different baselines and must not pretend to share
+one migration history.
 
 | 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`. |
+| 0010_portable_tickets_memory.sql | Account-owned agentsam_tickets + events + agentsam_memory + outbox. account_id + repository_id NOT NULL for portable installs. |
+| 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. |
+| 0018_goap_control_plane_remaster.sql | Additive ticket/event contract remaster: structured goal spec, structured event payloads, workflow/action linkage. No new GOAP table family and no dependency on runtime workspace tables. |
+| migrations/runtime/0002_goap_blackboard_v1.sql | Evolves agentsam_workspace_state after runtime/0001 with blackboard schema identity + CAS revision. |
 
 ## 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.
+- NULL repository_id on portable memory/ticket/event writes = broken implementation. Resolve repo identity from agentsam inspect / snapshot before insert.
+- Customer tickets and GOAP state use their D1/SQLite (or another adapter-owned store) — never IAM host ticket rows as an SDK requirement.
+- Logical GOAP contracts live in @inneranimalmedia/agentsam-goap; storage tables are adapter details.
+- GOAP errors use @inneranimalmedia/agentsam-errors and the shared error catalog. GOAP does not own a parallel error taxonomy.
+- Cross-store GOAP mutations use an atomic MutationPort. Do not sequence ticket/blackboard/event writes independently.
+- Existing workflow/execution/approval tables remain the plan/run/action/approval authorities. Do not create parallel GOAP graph tables.
+- Goal focus is not execution. Creating, selecting, or activating a goal must not fabricate an agentsam_agent_run. Link a run only after the execution subsystem actually creates one.
+- Portable ticket_events already has account_id + repository_id. Legacy platform event ownership is resolved through ticket_join until a host-only repair is intentionally applied.
+- Portable/account-owned runtime stores may scope blackboards by repository. Shared platform stores must verify repository ownership through their repository authority (for IAM D1: code_repositories.account_id).
+- 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/runtime/0002_goap_blackboard_v1.sql

@@ -0,0 +1,15 @@
+-- 0002_goap_blackboard_v1.sql
+-- Runtime blackboard contract evolution for D1/SQLite-compatible stores.
+-- agentsam_workspace_state is created by 0001_cli_runtime.sql.
+--
+-- The revision is the portable optimistic-concurrency/CAS fence.
+-- state_schema freezes the logical payload contract independently from storage.
+
+ALTER TABLE agentsam_workspace_state
+  ADD COLUMN state_schema TEXT NOT NULL DEFAULT 'agentsam.blackboard.v1';
+
+ALTER TABLE agentsam_workspace_state
+  ADD COLUMN revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_workspace_state_repo_revision
+  ON agentsam_workspace_state(repository_id, revision);

package/migrations/runtime/0004_agent_run_plan_linkage.sql

@@ -0,0 +1,8 @@
+-- Attribute every runtime attempt to the durable plan/TODO that caused it.
+ALTER TABLE agentsam_agent_run ADD COLUMN plan_id TEXT REFERENCES agentsam_plans(id) ON DELETE SET NULL;
+ALTER TABLE agentsam_agent_run ADD COLUMN todo_id TEXT REFERENCES agentsam_todo(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_plan
+  ON agentsam_agent_run(plan_id, created_at_unix DESC);
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_todo
+  ON agentsam_agent_run(todo_id, created_at_unix DESC);

package/native/agentsam-machine/cli/Cargo.toml

@@ -2,6 +2,13 @@
 name = "agentsam-machine-cli"
 version = "0.1.0"
 edition = "2021"
+description = "Deterministic native repository inspection CLI for AgentSam."
+license = "MIT"
+repository = "https://github.com/SamPrimeaux/agentsam-sdk"
+homepage = "https://github.com/SamPrimeaux/agentsam-sdk/tree/main/native/agentsam-machine"
+readme = "README.md"
+keywords = ["agents", "repository", "inspection", "cli", "deterministic"]
+categories = ["command-line-utilities", "development-tools"]
 
 [[bin]]
 name = "agentsam-machine"
@@ -11,4 +18,4 @@ path = "src/main.rs"
 anyhow = "1.0"
 clap = { version = "4.5", features = ["derive"] }
 serde_json = "1.0"
-agentsam-machine-core = { path = "../core" }
+agentsam-machine-core = { version = "0.1.0", path = "../core" }

package/native/agentsam-machine/cli/README.md

@@ -0,0 +1,21 @@
+# agentsam-machine-cli
+
+Command-line interface for AgentSam's deterministic native repository perception
+engine.
+
+Installing this crate from crates.io provides the `agentsam-machine` executable
+without requiring an AgentSam SDK source checkout:
+
+    cargo install agentsam-machine-cli
+    agentsam-machine --help
+
+Cargo installs binaries into `$CARGO_HOME/bin` (normally `~/.cargo/bin`).
+The standard Rust installer configures that directory on PATH. If you use a
+custom `cargo install --root <dir>`, add `<dir>/bin` to PATH yourself.
+
+The published CLI depends on the published `agentsam-machine-core` crate by
+version. The monorepo's local `path = "../core"` entry is only a development
+override; registry consumers resolve `agentsam-machine-core` from crates.io.
+
+The CLI is model-free. It delegates inspection and asset analysis to
+agentsam-machine-core.

package/native/agentsam-machine/core/Cargo.toml

@@ -2,6 +2,13 @@
 name = "agentsam-machine-core"
 version = "0.1.0"
 edition = "2021"
+description = "Deterministic repository and asset perception primitives for AgentSam."
+license = "MIT"
+repository = "https://github.com/SamPrimeaux/agentsam-sdk"
+homepage = "https://github.com/SamPrimeaux/agentsam-sdk/tree/main/native/agentsam-machine"
+readme = "README.md"
+keywords = ["agents", "repository", "inspection", "deterministic", "tooling"]
+categories = ["development-tools"]
 
 [lib]
 crate-type = ["rlib"]

package/native/agentsam-machine/core/README.md

@@ -0,0 +1,14 @@
+# agentsam-machine-core
+
+Deterministic repository and asset inspection primitives used by AgentSam's native
+agentsam-machine CLI.
+
+The crate is model-free and provider-free. It turns repository files and assets
+into bounded machine-readable facts used by higher-level AgentSam tooling.
+
+## Source-type contract
+
+The published crate includes a vendored copy of agentsam.source-types.v1 so it
+can compile independently from the AgentSam monorepo. While built inside the
+monorepo, build.rs verifies that vendored copy is byte-for-byte identical to
+the root contracts/source-types.v1.json authority.

package/native/agentsam-machine/core/build.rs

@@ -0,0 +1,33 @@
+use std::env;
+use std::fs;
+use std::path::PathBuf;
+
+fn main() {
+    println!("cargo:rerun-if-changed=contracts/source-types.v1.json");
+
+    let manifest_dir =
+        PathBuf::from(env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR must be set"));
+    let vendored = manifest_dir.join("contracts/source-types.v1.json");
+    let monorepo_authority = manifest_dir.join("../../../contracts/source-types.v1.json");
+
+    if !monorepo_authority.exists() {
+        return;
+    }
+
+    println!("cargo:rerun-if-changed={}", monorepo_authority.display());
+
+    let vendored_bytes = fs::read(&vendored)
+        .unwrap_or_else(|error| panic!("failed to read {}: {error}", vendored.display()));
+    let authority_bytes = fs::read(&monorepo_authority).unwrap_or_else(|error| {
+        panic!(
+            "failed to read source-type authority {}: {error}",
+            monorepo_authority.display()
+        )
+    });
+
+    if vendored_bytes != authority_bytes {
+        panic!(
+            "agentsam-machine-core vendored source-types contract is stale. Sync with: cp contracts/source-types.v1.json native/agentsam-machine/core/contracts/source-types.v1.json"
+        );
+    }
+}