@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/protocol/features/README.md

@@ -0,0 +1,57 @@
+# AgentSam Feature Capsules (`agentsam.feature.v1`)
+
+`protocol/features/` holds only:
+
+1. **`agentsam.feature.v1.schema.json`** — generic capsule contract (including reusable `artifacts[]`)
+2. **`catalog.json`** — discovery index pointing at package-local manifests
+
+Detailed JSON lives in each integration’s own territory, e.g.:
+
+```
+packages/identity/.agentsam/features/oauth-login-portal/
+packages/providers/completeful/.agentsam/features/provider/   (target)
+fuelnfreetime/features/*                                      (proving ground)
+```
+
+## Selection vs package packet vs resolved
+
+```
+.agentsam/features.json                 # user/project selections only
+        ↓
+protocol/features/catalog.json          # discovery
+        ↓
+packages/<pkg>/.agentsam/features/<id>/ # compartment packet (providers, resources, routes, ui)
+        ↓
+generated/.agentsam/features-resolved.json
+```
+
+Example selection:
+
+```json
+{
+  "schema_version": 2,
+  "features": {
+    "auth": {
+      "selected": true,
+      "capabilities": ["identity.init"],
+      "provider_template": "inneranimalmedia",
+      "selected_at": "2026-09-24T04:25:12.860Z"
+    }
+  }
+}
+```
+
+## artifacts[]
+
+Generic reference mechanism on any feature capsule:
+
+```json
+"artifacts": [
+  { "kind": "provider-catalog", "path": "./providers.json" },
+  { "kind": "resources", "path": "./resources.json" },
+  { "kind": "routes", "path": "./routes.json" },
+  { "kind": "ui", "path": "./ui.json" }
+]
+```
+
+Not identity-specific — Completeful, Resend, nav, analytics, CMS, CAD use the same pattern.

package/protocol/features/agentsam.feature.v1.schema.json

@@ -0,0 +1,290 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.dev/protocol/features/agentsam.feature.v1.schema.json",
+  "title": "AgentSam Feature Capsule",
+  "description": "Vertical product capability that a host APP can activate. npm install is inert; AgentSam activates after plan + approval. Not a full APP \u2014 use agentsam.app.v1 / .agentsam/app.json for runnable compositions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "id",
+    "kind",
+    "package",
+    "provides"
+  ],
+  "properties": {
+    "schema": {
+      "const": "agentsam.feature.v1"
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9._-]*$",
+      "description": "Stable feature id, e.g. provider.resend, admin.shell-nav"
+    },
+    "name": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-readable title (alias of name for protocol-authored features)"
+    },
+    "kind": {
+      "type": "string",
+      "enum": [
+        "provider",
+        "ui",
+        "domain",
+        "composer",
+        "theme",
+        "analytics",
+        "integration"
+      ]
+    },
+    "package": {
+      "type": "object",
+      "required": [
+        "name",
+        "version"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "directory": {
+          "type": "string",
+          "description": "Repo-relative path to implementation (may be pre-extraction)"
+        }
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "incubating",
+        "extracted",
+        "published"
+      ],
+      "default": "incubating"
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Selection-facing capability ids recorded in .agentsam/features.json"
+    },
+    "provides": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "string"
+      },
+      "description": "Capability strings hosts can require, e.g. email.send"
+    },
+    "requires": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "optional": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "runtime": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "common",
+          "browser",
+          "node",
+          "worker",
+          "local-machine"
+        ]
+      },
+      "default": [
+        "common"
+      ]
+    },
+    "contracts": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Repo-relative contract module paths"
+    },
+    "contributes": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ui": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "routes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "tools": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "hooks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "jobs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "migrations": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "webhooks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "skills": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "secrets": {
+      "type": "object",
+      "properties": {
+        "server_only": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "optional": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "host_bindings": {
+      "type": "object",
+      "description": "What the host must inject \u2014 never hardcode account/tenant IDs in the feature",
+      "properties": {
+        "required": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "forbidden_in_feature": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Constants that must stay in the host adapter"
+        }
+      }
+    },
+    "source": {
+      "type": "object",
+      "properties": {
+        "proving_ground": {
+          "type": "string"
+        },
+        "implementation_paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "extracted_package": {
+          "type": "string"
+        },
+        "host_mirror_paths": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    },
+    "activation": {
+      "type": "object",
+      "description": "npm is inert; AgentSam runs this plan",
+      "properties": {
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "validate_manifest",
+              "check_runtime",
+              "resolve_requires",
+              "resolve_provider_template",
+              "resolve_schema_profile",
+              "map_host_secrets",
+              "plan_migrations",
+              "plan_routes",
+              "plan_webhooks",
+              "operator_approval",
+              "activate",
+              "verify",
+              "write_install_receipt"
+            ]
+          }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "description": "Package-local normalized artifact references owned by this feature compartment.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "kind",
+          "path"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9._-]*$"
+          },
+          "path": {
+            "type": "string",
+            "description": "Path relative to the feature manifest unless otherwise documented."
+          }
+        }
+      },
+      "default": []
+    }
+  }
+}

package/protocol/features/catalog.json

@@ -0,0 +1,65 @@
+{
+  "schema": "agentsam.feature.catalog.v1",
+  "updated": "2026-09-24",
+  "features": [
+    {
+      "id": "admin.shell-nav",
+      "kind": "ui",
+      "proving_ground": "fuelnfreetime",
+      "manifest": "fuelnfreetime/features/admin-shell-nav/agentsam.feature.json"
+    },
+    {
+      "id": "agentsam.mini-composer",
+      "kind": "composer",
+      "proving_ground": "fuelnfreetime",
+      "manifest": "fuelnfreetime/features/mini-agentsam-composer/agentsam.feature.json"
+    },
+    {
+      "id": "cms.hyperspace-runtime",
+      "kind": "ui",
+      "proving_ground": "inneranimalmedia",
+      "manifest": "inneranimalmedia/apps/client-cms-editor/.agentsam/features/hyperspace-runtime.feature.json"
+    },
+    {
+      "id": "cms.template-library",
+      "kind": "theme",
+      "proving_ground": "inneranimalmedia",
+      "manifest": "inneranimalmedia/packages/cms-cloudflare-template-library/.agentsam/feature.json"
+    },
+    {
+      "id": "commerce.product-studio",
+      "kind": "domain",
+      "proving_ground": "fuelnfreetime",
+      "manifest": "fuelnfreetime/features/product-studio/agentsam.feature.json",
+      "requires": [
+        "commerce.catalog"
+      ]
+    },
+    {
+      "id": "growth.campaigns",
+      "kind": "domain",
+      "proving_ground": "fuelnfreetime",
+      "manifest": "fuelnfreetime/features/growth-campaigns/agentsam.feature.json"
+    },
+    {
+      "id": "identity.oauth-login-portal",
+      "kind": "integration",
+      "proving_ground": "agentsam-sdk",
+      "manifest": "packages/identity/.agentsam/features/oauth-login-portal/agentsam.feature.json"
+    },
+    {
+      "id": "provider.completeful",
+      "kind": "provider",
+      "proving_ground": "fuelnfreetime",
+      "status": "extracted",
+      "package": "@inneranimalmedia/agentsam-provider-completeful",
+      "manifest": "fuelnfreetime/features/provider-completeful/agentsam.feature.json"
+    },
+    {
+      "id": "provider.resend",
+      "kind": "provider",
+      "proving_ground": "fuelnfreetime",
+      "manifest": "fuelnfreetime/features/provider-resend/agentsam.feature.json"
+    }
+  ]
+}

package/protocol/features/examples/provider-resend.feature.json

@@ -0,0 +1,17 @@
+{
+  "schema": "agentsam.feature.v1",
+  "id": "provider.resend",
+  "name": "Resend Email Provider",
+  "kind": "provider",
+  "status": "incubating",
+  "package": {
+    "name": "@inneranimalmedia/provider-resend",
+    "version": "0.0.0-incubating"
+  },
+  "provides": ["email.send", "email.webhook.receive"],
+  "runtime": ["worker", "node"],
+  "source": {
+    "proving_ground": "fuelnfreetime",
+    "notes": "See fuelnfreetime/features/provider-resend/agentsam.feature.json for full contribution map."
+  }
+}

package/protocol/go/agentsam-go-runtime.v1.json

@@ -0,0 +1,17 @@
+{
+  "$id": "agentsam.go-runtime.v1",
+  "title": "AgentSam Go Runtime Protocol",
+  "description": "Canonical schema id for Go runtime inventory responses and build receipts.",
+  "schemas": {
+    "runtime": "agentsam.go-runtime.v1",
+    "build_receipt": "agentsam.go-build-receipt.v1",
+    "deployment_receipt": "agentsam.deployment-receipt.v1",
+    "inspect": "agentsam.go-inspect.v1"
+  },
+  "default_product": "agentsam-go-worker",
+  "deployment_modes": [
+    "cloudflare-container",
+    "local",
+    "cloudflare-wasm"
+  ]
+}

package/protocol/knowledge/LIFECYCLE.md

@@ -0,0 +1,140 @@
+# Knowledge, current state, and provider context
+
+Status: design proposal grounded in the current SDK. This document does not
+claim a durable-claim store, D1 knowledge adapter, or automatic distillation
+pipeline has been implemented.
+
+## Existing authorities
+
+| Concern | Existing owner | Lifetime |
+| --- | --- | --- |
+| ProjectSession, plans, runs, approvals, receipts | `src/local/runtime-store.js`, `migrations/runtime/`, project `.agentsam/data/agentsam.sqlite` | session/work cycle; selected receipts persist |
+| Blackboard/current workspace state | `agentsam_workspace_state`; repository package workspace-state and GOAP adapters | current work cycle, versioned observations |
+| Hosted GOAP inspection | `packages/agentsam-repository/src/goap.js` currently reads D1 workspace state, tickets, runs, commits, checkpoints | live observation, refresh required |
+| Repository retrieval knowledge | `src/knowledge/engine.js`, existing SQLite/Postgres stores | published index generation; superseded generations are retrieval history |
+| Local repository index | `.agentsam/knowledge/index.sqlite`, configured by `.agentsam/knowledge.json` | rebuildable index/cache, distinct from runtime SQLite |
+| Provider continuation | provider response ID or pending exact compaction output in `agentsam_provider_continuations` | session; replaced on compaction, removed after successful continuation |
+| Application data | user's configured application storage | application-owned |
+
+This repository declares D1 `inneranimalmedia-business` as binding `DB` in
+`apps/local-studio/backend/wrangler.jsonc`, plus `HYPERDRIVE`, R2
+`WEBSITE_ASSETS`, AI and service bindings. These are configuration observations,
+not live connectivity proof. Local SQLite does not silently replace or mirror them.
+
+The runtime migration already supplies `agentsam_workspace_state`. Extend that
+owner and its adapters for portable blackboard behavior; do not introduce a
+second table named `agentsam_blackboard` just to express the same state.
+The current hosted `/goap` implementation is not yet a portable local-first
+blackboard adapter. Its configured D1 and query scoping need a separate audited
+adapter cutover before promising the same behavior to a new offline user.
+
+## Four independent contracts
+
+1. **Blackboard**: what the runtime currently knows about this task. Goal, plan,
+   blockers, observations, approvals and pending actions retain explicit owners.
+   Observations include source revision and observed time. Updating state uses
+   an expected revision; concurrent agents must not overwrite each other's work.
+2. **Knowledge claim**: reusable understanding, supported by attributable evidence.
+   Decisions can be superseded; observations expire. Claims never grant permissions.
+3. **Evidence**: source identity, revision/hash, observation time, and a bounded
+   range or payload reference. References do not imply the payload remains available.
+4. **Provider context**: opaque inference continuation. Pass it back unchanged.
+   It is neither a knowledge record nor the authority for the current goal.
+
+Provider context compaction, removal of stale blackboard observations, and
+knowledge distillation are separate operations with separate receipts. A provider
+compaction must still succeed when no knowledge candidates are accepted.
+`src/context/compact.js` remains bounded context-item truncation.
+
+## Proposed claim envelope
+
+Extend the existing `protocol/knowledge/` namespace; do not create a competing
+knowledge package or replace the current retrieval contracts in place.
+
+A versioned claim should contain:
+
+- `id`, `schema_version`, and an authority-issued namespace/scope reference;
+- `kind`: fact, decision, constraint, preference, procedure, relationship, observation;
+- `statement`, plus optional typed subject/predicate/object when known;
+- `assertion_basis`: observed, user_asserted, derived, inferred;
+- `evidence_refs`, including source revision/hash and observed time;
+- `valid_from`, optional `valid_until`, and `review_after` for drift-prone claims;
+- `lifecycle`: persistent, session, work_cycle, ttl, scratch;
+- `expires_at` when time-bounded, with an explicit cleanup owner;
+- `revision`, `supersedes_id`, and conflict status;
+- `sensitivity` and access-policy reference;
+- deterministic content hash, creation time and actor/source attribution.
+
+The runtime supplies account, repository, session and work-cycle identity.
+Do not accept model-supplied scope as authorization. Filter access and expiry
+before retrieval scoring or embedding lookup. Scope-specific policy beats a
+semantic match from a different account/project. Inferences remain labelled;
+an arbitrary model-generated confidence score is not proof.
+
+Evidence objects are separate from claim-to-evidence links. Store source metadata
+once, and use a link relation such as supports, contradicts or supersedes.
+Missing/stale evidence makes a claim unverified; it must not silently remain a
+confirmed current fact. Secret values belong in credential stores, never claims,
+embeddings, generic metadata or lifecycle receipts.
+
+## Promotion and forgetting
+
+Candidate extraction may run at a user checkpoint or completed work cycle over
+bounded explicit statements and tool evidence. Never extract hidden reasoning or
+interpret encrypted provider content. Admission is a runtime operation, not a
+model write directly to durable storage.
+
+| Candidate | Treatment |
+| --- | --- |
+| Explicit user architectural decision | Persistent, scoped, attributable, supersedable |
+| Verified provider constraint | Durable with review-after date and source revision |
+| Current failing test or unresolved blocker | Work-cycle blackboard observation |
+| Current branch, dirty files, temporary hypothesis | Refreshable working state |
+| Fixed typo, repeated stdout, intermediate speculation | Discard or bounded evidence TTL |
+| API key or session credential | Reject from generic knowledge |
+
+Require future usefulness and evidence for durable promotion. Reacquisition cost
+is a useful ranking signal, not an override of access, privacy, or correctness.
+A question or tentative suggestion is not a decision. Stable wording alone does
+not prove semantic identity: dedupe exact content deterministically; mark fuzzy
+matches as candidates. Contradictions create a conflict or explicit supersession,
+not a silent last-write-wins overwrite. Preserve tombstones through any explicit
+sync so deletion is not undone by an offline replica.
+
+A distillation receipt identifies source checkpoint and evidence references,
+candidate counts, admitted/rejected/superseded IDs, rejection reason codes,
+extractor/version, and idempotency key. Counts must reconcile. No raw transcript
+or hidden reasoning belongs in the receipt. Admission and its receipt commit
+atomically; retries must not create duplicate claims.
+
+## Storage and retrieval
+
+Use store roles rather than a universal database abstraction. Runtime relational
+state remains project-local SQLite. Knowledge may select the existing SQLite or
+Postgres adapter. D1 application bindings stay application-owned until a tested
+knowledge adapter with migrations, scoping, lifecycle and concurrency semantics
+is explicitly selected. Object evidence payloads and vector indexes retain their
+own capabilities. Do not copy an application's entire database into memory.
+
+`/db sources` reads bounded local configuration and reports candidates, role,
+selection and support. Discovery is not authorization or connectivity proof.
+`/db select knowledge sqlite` selects the local index.
+`/db select knowledge postgres MY_DATABASE_URL` selects an environment-variable
+reference; it stores no connection string. Existing include/exclude scope and
+repository identity are preserved. Selection does not migrate existing data,
+initialize remote tables, switch the runtime database, or enable synchronization.
+JSON/JSONC Wrangler configurations and named environment bindings are supported;
+TOML is reported for explicit inspection. Future connectors can extend discovery
+without being implicitly granted query/write access.
+
+A new user gets the existing runtime SQLite migrations immediately and builds
+the local repository index with `agentsam index run`. A durable-claim migration
+and promotion API are still future implementation, not a feature of the current
+index merely because it is named knowledge.
+
+Extend the existing context-pack protocol to reference admitted claims alongside
+source evidence. Retrieval first applies authority, scope, expiry, and freshness,
+then relevance and token budget. Return source references/hashes and a selection
+receipt with considered, selected, excluded and estimated-token counts. Rehydrate
+exact source evidence when a task needs details. The model receives a bounded
+pack for its objective, never the entire knowledge store.

package/protocol/knowledge/README.md

@@ -3,3 +3,7 @@
 Provider-neutral JSON Schema contracts shared by the JavaScript SDK, Python SDK, Inner Animal Media runtime, and MCP surface. Runtime-specific bindings and credentials do not belong in these schemas.
 
 `index-config.schema.json` describes the runnable local/backend indexing configuration. The other eight schemas are recovered remote-transport contracts; see `docs/knowledge-branch-recovery.md` for provenance. Repository descriptors in those remote contracts require a hosted repository name; local engine configuration instead supports repositories without a Git remote through an explicit persistent repository ID.
+
+See [Lifecycle and store roles](LIFECYCLE.md) for the proposed durable-knowledge
+contract and its relationship to the existing blackboard, retrieval engine,
+application databases, and provider continuation.