@inneranimalmedia/agentsam-sdk 2.1.0 → 2.2.1

package/protocol/knowledge/chunk.schema.json

@@ -4,79 +4,21 @@
   "type": "object",
   "additionalProperties": false,
   "title": "Chunk",
-  "required": [
-    "chunk_id",
-    "document_id",
-    "workspace_id",
-    "content",
-    "ordinal",
-    "content_hash"
-  ],
+  "required": ["chunk_id", "document_id", "content", "ordinal", "content_hash"],
   "properties": {
-    "chunk_id": {
-      "type": "string"
-    },
-    "document_id": {
-      "type": "string"
-    },
-    "workspace_id": {
-      "type": "string"
-    },
-    "content": {
-      "type": "string"
-    },
-    "ordinal": {
-      "type": "integer",
-      "minimum": 0
-    },
-    "content_hash": {
-      "type": "string"
-    },
-    "token_count": {
-      "type": [
-        "integer",
-        "null"
-      ],
-      "minimum": 0
-    },
-    "repository_full_name": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "ref": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "commit_sha": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "path": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "symbol": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "heading_path": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "metadata": {
-      "type": "object"
-    }
+    "chunk_id": { "type": "string" },
+    "document_id": { "type": "string" },
+    "workspace_id": { "type": "string", "deprecated": true, "description": "Legacy compatibility metadata only." },
+    "content": { "type": "string" },
+    "ordinal": { "type": "integer", "minimum": 0 },
+    "content_hash": { "type": "string" },
+    "token_count": { "type": ["integer", "null"], "minimum": 0 },
+    "repository_full_name": { "type": ["string", "null"] },
+    "ref": { "type": ["string", "null"] },
+    "commit_sha": { "type": ["string", "null"] },
+    "path": { "type": ["string", "null"] },
+    "symbol": { "type": ["string", "null"] },
+    "heading_path": { "type": "array", "items": { "type": "string" } },
+    "metadata": { "type": "object" }
   }
 }

package/protocol/knowledge/document.schema.json

@@ -4,54 +4,16 @@
   "type": "object",
   "additionalProperties": false,
   "title": "Document",
-  "required": [
-    "document_id",
-    "source_id",
-    "workspace_id",
-    "content_hash",
-    "media_type"
-  ],
+  "required": ["document_id", "source_id", "content_hash", "media_type"],
   "properties": {
-    "document_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "source_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "workspace_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "content_hash": {
-      "type": "string",
-      "minLength": 1
-    },
-    "media_type": {
-      "type": "string",
-      "minLength": 1
-    },
-    "title": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "path": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "text": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "metadata": {
-      "type": "object"
-    }
+    "document_id": { "type": "string", "minLength": 1 },
+    "source_id": { "type": "string", "minLength": 1 },
+    "workspace_id": { "type": "string", "minLength": 1, "deprecated": true, "description": "Legacy compatibility metadata only." },
+    "content_hash": { "type": "string", "minLength": 1 },
+    "media_type": { "type": "string", "minLength": 1 },
+    "title": { "type": ["string", "null"] },
+    "path": { "type": ["string", "null"] },
+    "text": { "type": ["string", "null"] },
+    "metadata": { "type": "object" }
   }
 }

package/protocol/knowledge/index-config.schema.json

@@ -4,11 +4,11 @@
   "title": "Portable index configuration v1",
   "type": "object",
   "additionalProperties": false,
-  "required": ["version", "repository_id", "workspace_id", "scope", "chunking", "embedding", "storage"],
+  "required": ["version", "repository_id", "scope", "chunking", "embedding", "storage"],
   "properties": {
     "version": { "const": 1 },
     "repository_id": { "type": "string", "minLength": 1 },
-    "workspace_id": { "type": "string", "minLength": 1 },
+    "workspace_id": { "type": "string", "minLength": 1, "deprecated": true, "description": "Legacy compatibility metadata. New portable configs are repository-scoped and must not require this field." },
     "scope": {
       "type": "object", "additionalProperties": false, "required": ["name", "include"],
       "properties": {

package/protocol/knowledge/repository.schema.json

@@ -4,58 +4,17 @@
   "type": "object",
   "additionalProperties": false,
   "title": "RepositoryDescriptor",
-  "required": [
-    "repository_id",
-    "full_name",
-    "workspace_id",
-    "default_branch"
-  ],
+  "required": ["repository_id", "full_name", "default_branch"],
   "properties": {
-    "repository_id": {
-      "type": "string"
-    },
-    "full_name": {
-      "type": "string",
-      "pattern": "^[^/]+/[^/]+$"
-    },
-    "workspace_id": {
-      "type": "string"
-    },
-    "default_branch": {
-      "type": "string"
-    },
-    "product_ids": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "indexed_refs": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "enabled_lanes": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "include": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "exclude": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "metadata": {
-      "type": "object"
-    }
+    "repository_id": { "type": "string" },
+    "full_name": { "type": "string", "pattern": "^[^/]+/[^/]+$" },
+    "workspace_id": { "type": "string", "deprecated": true, "description": "Legacy compatibility metadata only." },
+    "default_branch": { "type": "string" },
+    "product_ids": { "type": "array", "items": { "type": "string" } },
+    "indexed_refs": { "type": "array", "items": { "type": "string" } },
+    "enabled_lanes": { "type": "array", "items": { "type": "string" } },
+    "include": { "type": "array", "items": { "type": "string" } },
+    "exclude": { "type": "array", "items": { "type": "string" } },
+    "metadata": { "type": "object" }
   }
 }

package/protocol/knowledge/retrieval-query.schema.json

@@ -4,69 +4,19 @@
   "type": "object",
   "additionalProperties": false,
   "title": "RetrievalQuery",
-  "required": [
-    "text",
-    "workspace_id"
-  ],
+  "required": ["text"],
   "properties": {
-    "text": {
-      "type": "string",
-      "minLength": 1
-    },
-    "workspace_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "repositories": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "product_ids": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "refs": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "intent": {
-      "type": "string",
-      "default": "auto"
-    },
-    "lanes": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      }
-    },
-    "top_k": {
-      "type": "integer",
-      "minimum": 1,
-      "maximum": 100,
-      "default": 12
-    },
-    "token_budget": {
-      "type": "integer",
-      "minimum": 256,
-      "default": 8000
-    },
-    "require_current_ref": {
-      "type": "boolean",
-      "default": true
-    },
-    "include_archived": {
-      "type": "boolean",
-      "default": false
-    },
-    "explain": {
-      "type": "boolean",
-      "default": true
-    }
+    "text": { "type": "string", "minLength": 1 },
+    "workspace_id": { "type": "string", "minLength": 1, "deprecated": true, "description": "Legacy compatibility metadata only; repository selection is explicit through repository identity." },
+    "repositories": { "type": "array", "items": { "type": "string" } },
+    "product_ids": { "type": "array", "items": { "type": "string" } },
+    "refs": { "type": "array", "items": { "type": "string" } },
+    "intent": { "type": "string", "default": "auto" },
+    "lanes": { "type": "array", "items": { "type": "string" } },
+    "top_k": { "type": "integer", "minimum": 1, "maximum": 100, "default": 12 },
+    "token_budget": { "type": "integer", "minimum": 256, "default": 8000 },
+    "require_current_ref": { "type": "boolean", "default": true },
+    "include_archived": { "type": "boolean", "default": false },
+    "explain": { "type": "boolean", "default": true }
   }
 }

package/protocol/knowledge/source.schema.json

@@ -4,49 +4,15 @@
   "type": "object",
   "additionalProperties": false,
   "title": "Source",
-  "required": [
-    "source_id",
-    "source_type",
-    "workspace_id",
-    "uri"
-  ],
+  "required": ["source_id", "source_type", "uri"],
   "properties": {
-    "source_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "source_type": {
-      "type": "string",
-      "minLength": 1
-    },
-    "workspace_id": {
-      "type": "string",
-      "minLength": 1
-    },
-    "uri": {
-      "type": "string",
-      "minLength": 1
-    },
-    "repository_full_name": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "ref": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "commit_sha": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
-    "metadata": {
-      "type": "object"
-    }
+    "source_id": { "type": "string", "minLength": 1 },
+    "source_type": { "type": "string", "minLength": 1 },
+    "workspace_id": { "type": "string", "minLength": 1, "deprecated": true, "description": "Legacy compatibility metadata only." },
+    "uri": { "type": "string", "minLength": 1 },
+    "repository_full_name": { "type": ["string", "null"] },
+    "ref": { "type": ["string", "null"] },
+    "commit_sha": { "type": ["string", "null"] },
+    "metadata": { "type": "object" }
   }
 }

package/protocol/presets/catalog.json

@@ -0,0 +1,48 @@
+{
+  "schema_version": 1,
+  "presets": {
+    "fullstack": {
+      "id": "fullstack",
+      "version": 1,
+      "lane": "fullstack",
+      "description": "Local-first application with AgentSam runtime, repository primitives, knowledge, and delivery hooks.",
+      "features": ["agent", "knowledge"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "security.scan", "deploy.receipt"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    },
+    "cms": {
+      "id": "cms",
+      "version": 1,
+      "lane": "cms",
+      "description": "Content-oriented application starting from local CMS primitives with explicit auth/deploy opt-ins.",
+      "features": ["cms", "knowledge"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "site.scrape", "deploy.receipt"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    },
+    "prototype": {
+      "id": "prototype",
+      "version": 1,
+      "lane": "fullstack",
+      "description": "Small local prototype with the minimum deterministic AgentSam runtime.",
+      "features": ["agent"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "security.scan"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    },
+    "data": {
+      "id": "data",
+      "version": 1,
+      "lane": "data",
+      "description": "Data-oriented local application with repository knowledge and explicit production storage graduation.",
+      "features": ["knowledge"],
+      "capabilities": ["scaffold.create", "repository.snapshot", "knowledge.index", "knowledge.search", "security.scan"],
+      "defaults": { "database": "sqlite", "assets": "local", "deploy": "local" }
+    }
+  },
+  "addons": {
+    "agent": { "id": "agent", "capabilities": ["scaffold.create"], "description": "AgentSam local runtime selection." },
+    "auth": { "id": "auth", "capabilities": ["identity.init"], "description": "Identity package selection; use `agentsam identity init` when a standalone auth app scaffold is required." },
+    "cms": { "id": "cms", "capabilities": ["site.scrape"], "description": "CMS/content feature selection." },
+    "knowledge": { "id": "knowledge", "capabilities": ["knowledge.index", "knowledge.search"], "description": "Portable repository indexing and retrieval." },
+    "deploy-cloudflare": { "id": "deploy-cloudflare", "capabilities": ["deploy.receipt"], "description": "Select Cloudflare as the intended deploy target; provisioning remains explicit at deploy time." }
+  }
+}

package/python/agentsam_sdk/knowledge/models.py

@@ -1,40 +1,46 @@
-"""Provider-neutral contracts for indexing and retrieval."""
+"""Provider-neutral contracts for indexing and retrieval.
+
+Portable knowledge is repository-scoped. ``workspace_id`` remains optional compatibility
+metadata only; it is never required to identify repository knowledge.
+"""
 
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Mapping, Sequence
+from typing import Any, Mapping
 
 JsonMap = Mapping[str, Any]
 
+
 @dataclass(frozen=True, slots=True)
 class Source:
     source_id: str
     source_type: str
-    workspace_id: str
     uri: str
     repository_full_name: str | None = None
     ref: str | None = None
     commit_sha: str | None = None
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class Document:
     document_id: str
     source_id: str
-    workspace_id: str
     content_hash: str
     media_type: str
     title: str | None = None
     path: str | None = None
     text: str | None = None
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class Chunk:
     chunk_id: str
     document_id: str
-    workspace_id: str
     content: str
     ordinal: int
     content_hash: str
@@ -45,25 +51,27 @@ class Chunk:
     path: str | None = None
     symbol: str | None = None
     heading_path: tuple[str, ...] = ()
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class RepositoryDescriptor:
     repository_id: str
     full_name: str
-    workspace_id: str
     default_branch: str
     product_ids: tuple[str, ...] = ()
     indexed_refs: tuple[str, ...] = ()
     enabled_lanes: tuple[str, ...] = ("code", "docs")
     include: tuple[str, ...] = ()
     exclude: tuple[str, ...] = ()
+    workspace_id: str | None = None
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class RetrievalQuery:
     text: str
-    workspace_id: str
     repositories: tuple[str, ...] = ()
     product_ids: tuple[str, ...] = ()
     refs: tuple[str, ...] = ()
@@ -74,6 +82,8 @@ class RetrievalQuery:
     require_current_ref: bool = True
     include_archived: bool = False
     explain: bool = True
+    workspace_id: str | None = None
+
 
 @dataclass(frozen=True, slots=True)
 class RetrievalHit:
@@ -92,6 +102,7 @@ class RetrievalHit:
     stale: bool = False
     metadata: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class ContextPack:
     query_id: str
@@ -101,6 +112,7 @@ class ContextPack:
     confidence: str = "unknown"
     diagnostics: JsonMap = field(default_factory=dict)
 
+
 @dataclass(frozen=True, slots=True)
 class IngestReceipt:
     run_id: str

package/python/agentsam_sdk/repository/__main__.py

@@ -1,3 +1,3 @@
-from agentsam_sdk.repository.inventory import main
+from agentsam_sdk.repository.intelligence.cli import main_cli
 
-raise SystemExit(main())
+raise SystemExit(main_cli())

package/python/tests/test_knowledge_models.py

@@ -12,10 +12,14 @@ class KnowledgeContractsTest(unittest.TestCase):
                     return {"run_id": "run", "source_id": payload["source_id"], "status": "succeeded"}
                 return {"query_id": "query", "hits": [{"chunk_id": "chunk", "content": "code", "score": 1, "lane": "code"}]}
         client = KnowledgeClient(Transport())
-        query = RetrievalQuery(text="function", workspace_id="workspace")
+        query = RetrievalQuery(text="function")
         self.assertEqual(asyncio.run(client.retrieve(query)).hits[0].content, "code")
         self.assertEqual(asyncio.run(client.index("source")).status, "succeeded")
-        self.assertEqual(Source("s", "repository", "workspace", "file:///repo").source_id, "s")
+        self.assertEqual(Source("s", "repository", "file:///repo").source_id, "s")
+
+    def test_workspace_is_optional_compatibility_metadata(self):
+        query = RetrievalQuery(text="function", workspace_id="legacy-workspace")
+        self.assertEqual(query.workspace_id, "legacy-workspace")
 
 
 if __name__ == "__main__":

package/src/agent/capability-adapter.js

@@ -0,0 +1,50 @@
+import { getCapability, listCapabilities } from '../capabilities/manifest.js';
+import { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+import { runRepositoryAudit } from './repository-audit.js';
+
+export function createCapabilityAdapter({ handlers = {}, reasoner } = {}) {
+  const executable = new Map([
+    ['repository.snapshot', (input) => repositorySnapshot(input)],
+    ...Object.entries(handlers),
+  ]);
+  if (typeof reasoner === 'function') {
+    executable.set('repository.audit', (input = {}) => runRepositoryAudit({ ...input, reasoner }));
+  }
+
+  function describe(id) {
+    const capability = getCapability(id);
+    if (!capability) throw new Error(`unknown_capability:${id}`);
+    return capability;
+  }
+
+  return Object.freeze({
+    list(options = {}) {
+      return listCapabilities(options);
+    },
+    describe,
+    toolDescriptors({ domain, kind, includeUnavailable = false } = {}) {
+      return listCapabilities({ domain, kind }).filter((row) => includeUnavailable || executable.has(row.id)).map((row) => ({
+        name: row.id,
+        description: row.description,
+        input_schema: row.input_schema || null,
+        side_effects: row.side_effects,
+        deterministic: row.deterministic,
+        model_required: row.model_required,
+      }));
+    },
+    canInvoke(id) {
+      return executable.has(String(id || '').trim());
+    },
+    async invoke(id, input = {}) {
+      const capability = describe(id);
+      const handler = executable.get(capability.id);
+      if (!handler) throw new Error(`capability_handler_unavailable:${capability.id}`);
+      const value = await handler(input);
+      return {
+        capability_id: capability.id,
+        capability_version: capability.version,
+        result: value,
+      };
+    },
+  });
+}

package/src/agent/index.js

@@ -0,0 +1,2 @@
+export { createCapabilityAdapter } from './capability-adapter.js';
+export { buildRepositoryAuditPacket, renderRepositoryAuditMarkdown, runRepositoryAudit } from './repository-audit.js';