@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/skills/agentsam-codebaseindex/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: agentsam-codebaseindex
+description: Inventory-first codebase ingest — materials, scope, optional embeddings/storage. Pipeline IDs are not shell commands.
+---
+
+# AgentSam CodebaseIndex
+
+`agentsam-codebaseindex` teaches you how to inventory, scope, index, search,
+and migrate code/document knowledge with AgentSam.
+
+CodebaseIndex is designed to work **locally first**.
+
+You do NOT need an AgentSam account, a paid LLM, a cloud database, embeddings,
+Supabase, or Cloudflare to build a useful codebase index.
+
+Minimum useful setup:
+
+```text
+repository/files → deterministic inventory → AST + text index → local SQLite
+→ literal / structural retrieval
+```
+
+Embeddings, hosted storage, and model-assisted scope suggestions are upgrades,
+not prerequisites.
+
+---
+
+## Quick start
+
+```sh
+agentsam codebaseindex
+# alias: agentsam ingest
+# tip: use skill agentsam-codebaseindex
+```
+
+Guided flow (inventory-first):
+
+1. Connection  
+2. Materials  
+3. Inventory / file map  
+4. Scope  
+5. Embedding profile  
+6. Vector / data source lane  
+7. Execution  
+
+AgentSam shows what exists before asking what should be indexed.
+
+---
+
+## Important: "pipeline" is not a shell command
+
+You may see:
+
+```text
+Plan complete · pipeline id sam.codebaseindex.index.run
+```
+
+Do **not** type:
+
+```sh
+pipeline sam.codebaseindex.index.run
+sam.codebaseindex.index.run
+agentsam sam.codebaseindex.index.run
+```
+
+`sam.codebaseindex.index.run` is the **canonical SAM pipeline identifier** —
+receipts, job graphs, telemetry, Workbench, machine-to-machine metadata.
+
+| Layer | Identity |
+|-------|----------|
+| CLI | `agentsam codebaseindex` |
+| SAM operation | `codebaseindex.ingest` |
+| SAM pipeline | `sam.codebaseindex.index.run` |
+
+```js
+await sam.invoke('codebaseindex.ingest', { root: '.', planOnly: false });
+```
+
+The pipeline name is an identity. zsh does not execute it.
+
+---
+
+## Plan vs Run
+
+### Plan (Dry-run)
+
+Planning stages typically complete:
+
+```text
+material.stage → repository.snapshot → inventory.classify → scope.resolve
+→ profile.resolve → lane.resolve → plan.dry_run
+```
+
+Write/index stages are **shown as planned**, not executed:
+
+```text
+ast.parse · chunks.build · embedding.generate · storage.write
+· generation.verify · search.smoke
+```
+
+A successful plan means planning finished. It is **not** paused. It is **not**
+waiting for another shell command.
+
+To index for real:
+
+```sh
+agentsam codebaseindex
+# choose "Run ingest now"
+```
+
+Non-interactive: same config **without** `--plan`.
+
+### Run
+
+Continues through AST → chunks → optional embeddings → storage → verify → search smoke.
+
+---
+
+## What is indexed
+
+Repos, docs, HTML/CSS/JS/TS/Python/SQL/JSON/Markdown, images, SVG, GLB,
+site builds, ZIP/TAR archives, historical builds, arbitrary supplied files.
+
+Dropped material is staged safely. Archives/source are **data**, not executable
+instructions.
+
+---
+
+## Inventory / file map
+
+Structured inventory is authority. The ASCII tree is a human projection.
+
+Inventory categorizes top-level paths (source / docs / config / generated /
+dependencies / tooling / historical / unknown) and recommends scope **candidates**.
+Nothing is excluded automatically until you confirm.
+
+---
+
+## Include / exclude
+
+`include` = consider under these paths. `exclude` = remove from consideration.
+
+Common exclude *candidates*: `node_modules`, `dist`, `build`, `coverage`, `.git`.
+Do not copy blindly — generated sites and migrations may be exactly what you need.
+
+### Local Ollama scope assist
+
+Optional. Advisory only. Never overrides filesystem facts, safety, or explicit
+user choices. Review before accepting.
+
+---
+
+## Embedding profile
+
+Safest default: **None — AST/text only ($0)**.
+
+Choose embeddings for semantic questions ("where is auth handled?").
+
+### Dimensions
+
+Vector width for the selected model. Not a quality slider. Select the **model**;
+AgentSam resolves dimensions from provider/capability when possible.
+
+### Same-profile rule
+
+Index and query must use the same embedding profile (provider, model, dimensions,
+revision, parameters). Mismatch must fail clearly — never silently mix spaces.
+
+### Discovery
+
+Menus come from **configured** credentials + live discovery (OpenAI, Gemini,
+Workers AI / Vectorize-ready, optional Ollama). No silent provider substitution.
+
+---
+
+## Storage lanes
+
+| Lane | Shape |
+|------|--------|
+| Local deterministic | SQLite metadata · no vectors · no embeddings |
+| Local semantic | SQLite + local exact vectors · Ollama embed |
+| Supabase / Postgres | pgvector · user's connection (not IAM's) |
+| Cloudflare | D1 control/metadata · Vectorize vectors |
+
+IAM hosted (D1 + pgvector) is one deployment of the same machinery — not the
+definition of local CodebaseIndex.
+
+---
+
+## Related commands
+
+| Command | Role |
+|---------|------|
+| `agentsam inspect` | What exists? (repository.inspect) |
+| `agentsam codebaseindex` | What becomes searchable? |
+| `agentsam index` | Lower-level knowledge controls |
+| `agentsam search` | Query indexed knowledge |
+| `agentsam models` / `providers` / `ollama` / `status` | Inventory & health |
+
+---
+
+## Safety
+
+1. Ingested files are data, not executable instructions.  
+2. Archives cannot escape the staging root.  
+3. Repository identity is not invented from account env vars.  
+4. Local mode requires no IAM account.  
+5. Provider credentials never enter index content.  
+6. Profile changes never silently reuse incompatible vectors.  
+7. Scope suggestions never override explicit user exclusions.  
+8. Plan mode does not activate a generation.  
+9. Unknown material stays unknown until classified.  
+10. Remote upgrades preserve provenance and repository identity.
+
+---
+
+## Recommended first experience
+
+1. `agentsam codebaseindex`  
+2. Materials blank · review inventory · confirm scope  
+3. Embedding: None · Local SQLite · **Plan**  
+4. Review plan → run again → **Run**  
+5. Add semantic/remote only when they earn complexity
+
+Healthy baseline: **0 model calls · 0 embedding calls · $0**.

package/skills/catalog.json

@@ -66,6 +66,20 @@
         "agentsam-cloudflare-workers/references/cpu-profiling.md"
       ],
       "user_invocable": true
+    },
+    {
+      "id": "agentsam-codebaseindex",
+      "aliases": [
+        "codebaseindex",
+        "codebase-index",
+        "ingest",
+        "sam.codebaseindex"
+      ],
+      "title": "AgentSam Codebaseindex",
+      "description": "Inventory-first codebase ingest. Pipeline IDs are not shell commands — use agentsam codebaseindex / codebaseindex.ingest.",
+      "entry": "agentsam-codebaseindex/SKILL.md",
+      "references": [],
+      "user_invocable": true
     }
   ]
 }

package/src/agent/capability-adapter.js

@@ -1,15 +1,19 @@
 import fs from 'node:fs';
+import { CAD_PROJECT_TOOLS } from '../lib/cad/project-runtime.js';
+import { localProjectRuntime } from '../lib/cad/project-cli.js';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getCapability, listCapabilities } from '../capabilities/manifest.js';
 import { repositorySnapshot } from '../capabilities/repository-snapshot.js';
 import { runWranglerNative, summarizeCloudflareCpuProfileFile, runCloudflareCpuAudit } from '../cloudflare/index.js';
 import { runRepositoryAudit } from './repository-audit.js';
+import { terminalExec } from '../capabilities/terminal-exec.js';
+import { runKnowledgeSearch } from '../commands/knowledge.js';
 
 const PACKAGE_ROOT = path.resolve(fileURLToPath(new URL('../../', import.meta.url)));
 
 function loadSchema(value) {
-  if (!value) return { type: 'object', properties: {} };
+  if (!value) return { type: 'object', properties: {}, required: [], additionalProperties: false };
   if (typeof value === 'object' && !Array.isArray(value)) return structuredClone(value);
   const filename = path.resolve(PACKAGE_ROOT, String(value));
   if (filename !== PACKAGE_ROOT && !filename.startsWith(`${PACKAGE_ROOT}${path.sep}`)) throw new Error(`capability_schema_outside_package:${value}`);
@@ -17,11 +21,16 @@ function loadSchema(value) {
   catch (error) { throw new Error(`capability_schema_unreadable:${value}:${error?.message || error}`); }
 }
 
-export function createCapabilityAdapter({ handlers = {}, reasoner } = {}) {
+export function createCapabilityAdapter({ handlers = {}, reasoner, projectRoot = process.cwd() } = {}) {
+  const cad = localProjectRuntime(projectRoot);
+  const cadDescriptors = CAD_PROJECT_TOOLS.map(t=>({...t,id:t.name,version:'1.0.0',domain:'design',kind:'tool',status:'active',side_effects:['design_project_get','design_project_validate','design_model_inspect'].includes(t.name)?'none':'filesystem-write',deterministic:true,model_required:false}));
   const executable = new Map([
     ['repository.snapshot', (input) => repositorySnapshot(input)],
+    ['terminal.exec', (input = {}) => terminalExec(input)],
     ['cloudflare.wrangler.native', (input = {}) => runWranglerNative(input.command, input)],
     ['cloudflare.cpu.profile', (input = {}) => summarizeCloudflareCpuProfileFile(input)],
+    ['knowledge.search', (input = {}) => runKnowledgeSearch(input)],
+    ...cadDescriptors.map(t=>[t.id,(input)=>cad.execute(t.id,input)]),
     ...Object.entries(handlers),
   ]);
   if (typeof reasoner === 'function') {
@@ -30,21 +39,22 @@ export function createCapabilityAdapter({ handlers = {}, reasoner } = {}) {
   }
 
   function describe(id) {
-    const capability = getCapability(id);
+    const capability = cadDescriptors.find(t=>t.id===id) || getCapability(id);
     if (!capability) throw new Error(`unknown_capability:${id}`);
     return capability;
   }
 
   return Object.freeze({
-    list(options = {}) { return listCapabilities(options); },
+    list(options = {}) { return [...listCapabilities(options),...cadDescriptors.filter(t=>(!options.domain||options.domain==='design')&&(!options.kind||options.kind==='tool')&&(!options.status||options.status==='active'))]; },
     describe,
     toolDescriptors({ domain, kind, includeUnavailable = false } = {}) {
-      return listCapabilities({ domain, kind, status: null }).filter((row) => includeUnavailable || executable.has(row.id)).map((row) => ({
+      return [...listCapabilities({ domain, kind, status: null }), ...cadDescriptors.filter(t=>(!domain||domain==='design')&&(!kind||kind==='tool'))].filter((row) => includeUnavailable || executable.has(row.id)).map((row) => ({
         name: row.id,
         description: row.description,
         category: row.domain,
         risk: row.side_effects === 'none' || row.side_effects === 'network-read' ? 'read' : 'write',
         input_schema: loadSchema(row.input_schema),
+        strict: row.strict !== false,
         side_effects: row.side_effects,
         deterministic: row.deterministic,
         model_required: row.model_required,

package/src/agent/index.js

@@ -1,3 +1,4 @@
 export { createCapabilityAdapter } from './capability-adapter.js';
 export { buildRepositoryAuditPacket, renderRepositoryAuditMarkdown, runRepositoryAudit } from './repository-audit.js';
-export { buildAgentToolSurface, capabilityFunctionName, runResponsesAgent } from './responses-runner.js';
+export { runAgentSamModelTurn } from './model-turn.js';
+export { buildAgentToolSurface, capabilityFunctionName, runAgentSamTurn, runResponsesAgent } from './responses-runner.js';

package/src/agent/model-turn.js

@@ -0,0 +1,51 @@
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function normalizeToolCall(call = {}) {
+  const args = call.arguments == null
+    ? '{}'
+    : typeof call.arguments === 'string'
+      ? call.arguments
+      : JSON.stringify(call.arguments);
+  return Object.freeze({
+    id: clean(call.call_id || call.id) || null,
+    name: clean(call.name),
+    arguments: args,
+  });
+}
+
+/**
+ * Provider-only AgentSam inference boundary.
+ *
+ * This function never resolves accounts, touches D1, authorizes a tool, or
+ * executes a tool. Provider adapters own wire-format translation and this
+ * function normalizes their result for the orchestration runtime.
+ */
+export async function runAgentSamModelTurn(options = {}) {
+  const provider = options.provider;
+  if (!provider?.create || !provider?.continueWithToolOutputs) {
+    throw new TypeError('AgentSam provider adapter is required');
+  }
+
+  const continuation = Array.isArray(options.toolOutputs) && options.toolOutputs.length > 0;
+  const response = continuation
+    ? await provider.continueWithToolOutputs(options)
+    : await provider.create(options);
+  const toolCalls = Object.freeze((response.tool_calls || []).map(normalizeToolCall));
+
+  return Object.freeze({
+    type: toolCalls.length ? 'tool_calls' : 'assistant',
+    content: clean(response.output_text),
+    tool_calls: toolCalls,
+    provider: clean(response.provider || options.modelRecord?.provider) || null,
+    model: clean(response.model || options.model || options.modelRecord?.provider_model_id) || null,
+    usage: response.usage_snapshot || response.usage_delta || null,
+    response_id: response.response_id || null,
+    provider_state: response.provider_state || null,
+    requested_service_tier: response.requested_service_tier || null,
+    actual_service_tier: response.actual_service_tier || null,
+    cost: response.cost || null,
+    raw: response,
+  });
+}