@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/packages/work-graph/src/adapters/engineering/git.js

@@ -0,0 +1,22 @@
+export function createGitAdapter(config = {}) {
+  return {
+    type: 'engineering.git',
+    config,
+    toWorkItems(commits = []) {
+      return commits.map((commit) => {
+        if (!commit.sha && !commit.id) throw new TypeError('git commit requires sha or id');
+        return {
+          id: String(commit.sha ?? commit.id),
+          title: String(commit.subject ?? commit.message ?? 'Commit').split('\n')[0],
+          type: 'commit',
+          status: 'complete',
+          owner: commit.author ?? null,
+          start: commit.date ?? null,
+          end: commit.date ?? null,
+          artifacts: commit.url ? [commit.url] : [],
+          evidence: [String(commit.sha ?? commit.id)],
+        };
+      });
+    },
+  };
+}

package/packages/work-graph/src/adapters/engineering/mcp.js

@@ -0,0 +1,22 @@
+export function createMcpAdapter(config = {}) {
+  return {
+    type: 'engineering.mcp',
+    config,
+    toWorkItems(calls = []) {
+      return calls.map((call) => {
+        if (!call.id && !call.tool_call_id) throw new TypeError('MCP call requires id or tool_call_id');
+        return {
+          id: String(call.id ?? call.tool_call_id),
+          title: String(call.tool_name ?? call.name ?? 'MCP call'),
+          type: 'tool_call',
+          status: call.status ?? 'complete',
+          owner: call.actor ?? null,
+          start: call.started_at ?? null,
+          end: call.completed_at ?? null,
+          artifacts: call.artifacts ?? [],
+          evidence: call.receipt_id ? [call.receipt_id] : [],
+        };
+      });
+    },
+  };
+}

package/packages/work-graph/src/index.js

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+
+export class WorkGraph {
+  constructor({ id, name, title, items, workItems, events, timelineEvents, actors = [] } = {}) {
+    this.id = id ?? randomUUID();
+    this.name = name ?? title ?? 'Untitled Work Graph';
+    this.items = items ?? workItems ?? [];
+    this.events = events ?? timelineEvents ?? [];
+    this.actors = actors;
+  }
+
+  add(item) {
+    this.items.push(item);
+    return item;
+  }
+
+  timeline() {
+    return [...this.events].sort((a, b) => new Date(a.at ?? a.timestamp) - new Date(b.at ?? b.timestamp));
+  }
+}
+
+export class WorkItem {
+  constructor({ id, title, type = 'task', status = 'planned', owner = null, start = null, end = null, dependencies = [], artifacts = [], evidence = [] } = {}) {
+    this.id = id ?? randomUUID();
+    this.title = title;
+    this.type = type;
+    this.status = status;
+    this.owner = owner;
+    this.start = start;
+    this.end = end;
+    this.dependencies = dependencies;
+    this.artifacts = artifacts;
+    this.evidence = evidence;
+  }
+}
+
+export class Dependency {
+  constructor({ from, to, relation = 'blocks' } = {}) {
+    this.from = from;
+    this.to = to;
+    this.relation = relation;
+  }
+}
+
+export class TimelineEvent {
+  constructor({ type, at = new Date(), workItemId, metadata = {} } = {}) {
+    this.type = type;
+    this.at = new Date(at);
+    this.workItemId = workItemId;
+    this.metadata = metadata;
+  }
+}
+
+export class Artifact {
+  constructor({ name, kind, uri = null } = {}) {
+    this.name = name;
+    this.kind = kind;
+    this.uri = uri;
+  }
+}
+
+export class Evidence {
+  constructor({ type, value, artifact = null } = {}) {
+    this.type = type;
+    this.value = value;
+    this.artifact = artifact;
+  }
+}
+
+export class Actor {
+  constructor({ id, name, role = 'worker' } = {}) {
+    this.id = id ?? randomUUID();
+    this.name = name;
+    this.role = role;
+  }
+}

package/packages/work-graph/src/renderers/gantt-model.js

@@ -0,0 +1,11 @@
+export function createGanttModel(graph) {
+  const items = graph?.items ?? graph?.workItems ?? [];
+
+  return items.map((item) => ({
+    id: item.id,
+    title: item.title,
+    status: item.status,
+    start: item.start ?? null,
+    end: item.end ?? null,
+  }));
+}

package/packages/work-graph/src/renderers/timeline.js

@@ -0,0 +1,16 @@
+export function createTimelineModel(graph) {
+  const items = graph?.items ?? graph?.workItems ?? [];
+  const events = graph?.events ?? graph?.timelineEvents ?? [];
+  const actors = graph?.actors ?? [];
+  return {
+    title: graph?.name ?? graph?.title ?? 'Untitled Work Graph',
+    lanes: actors.map((actor) => ({
+      id: actor.id,
+      name: actor.name,
+      type: actor.type ?? actor.role ?? 'worker',
+      items: items.filter((item) => item.owner === actor.id),
+    })),
+    items,
+    events: [...events].sort((a, b) => new Date(a.at ?? a.timestamp) - new Date(b.at ?? b.timestamp)),
+  };
+}

package/packages/work-graph/test/work-graph.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Actor, TimelineEvent, WorkGraph, WorkItem } from '../src/index.js';
+import { createGitAdapter } from '../src/adapters/engineering/git.js';
+import { createMcpAdapter } from '../src/adapters/engineering/mcp.js';
+import { createProjectsAdapter } from '../src/adapters/business/projects.js';
+import { createTimelineModel } from '../src/renderers/timeline.js';
+import { createGanttModel } from '../src/renderers/gantt-model.js';
+
+test('work graph projects one source of truth into timeline and Gantt views', () => {
+  const actor = new Actor({ id: 'agent-1', name: 'Agent One' });
+  const item = new WorkItem({ id: 'task-1', title: 'Index repository', owner: actor.id });
+  item.start = '2026-09-18';
+  item.end = '2026-09-19';
+  const graph = new WorkGraph({ name: 'Release', actors: [actor] });
+  graph.add(item);
+  graph.events.push(new TimelineEvent({ type: 'deploy', at: '2026-09-19T12:00:00Z', workItemId: item.id }));
+  graph.events.push(new TimelineEvent({ type: 'test', at: '2026-09-18T12:00:00Z', workItemId: item.id }));
+
+  const timeline = createTimelineModel(graph);
+  assert.equal(timeline.title, 'Release');
+  assert.equal(timeline.lanes[0].items[0], item);
+  assert.deepEqual(timeline.events.map((event) => event.type), ['test', 'deploy']);
+  assert.deepEqual(createGanttModel(graph)[0], {
+    id: 'task-1', title: 'Index repository', status: 'planned', start: '2026-09-18', end: '2026-09-19',
+  });
+});
+
+test('adapters map source records without fetching or mutating them', () => {
+  const commit = { sha: 'abc123', subject: 'Add search', author: 'sam', date: '2026-09-18' };
+  const call = { tool_call_id: 'call-1', tool_name: 'search', status: 'complete', receipt_id: 'receipt-1' };
+  const project = { id: 'project-1', name: 'CMS', status: 'running', client_id: 'client-1' };
+  assert.deepEqual(createGitAdapter().toWorkItems([commit]).map((item) => item.id), ['abc123']);
+  assert.deepEqual(createMcpAdapter().toWorkItems([call])[0].evidence, ['receipt-1']);
+  assert.equal(createProjectsAdapter().toWorkItems([project])[0].owner, 'client-1');
+  assert.deepEqual(commit, { sha: 'abc123', subject: 'Add search', author: 'sam', date: '2026-09-18' });
+});

package/protocol/README.md

@@ -21,11 +21,23 @@ agentsam-sdk/
 ├── src/                       # Node SDK + local/deploy CLI
 ├── python/agentsam_sdk/       # Python portable tools and TUI
 ├── packages/                  # Optional focused packages/workspaces
+├── apps/                      # Runnable + mountable APP compositions
+│   └── */.agentsam/app.json   # App contract (standalone | embedded)
 ├── protocol/                  # Shared SDK contracts and ownership rules
+│   └── features/              # agentsam.feature.v1 schema + catalog
 ├── templates/                 # Scaffold templates
 ├── examples/                  # Runnable examples/pointers
 ├── docs/                      # Product and developer documentation
 └── test/ + python/tests/      # Node and Python verification
 ```
 
+### APP vs FEATURE
+
+| Unit | Manifest | Role |
+|------|----------|------|
+| APP | `.agentsam/app.json` | Runnable/mountable product composition |
+| FEATURE | `agentsam.feature.json` | Vertical capability (provider/UI/domain/composer) |
+
+`npm install` is inert. AgentSam activates features after validation → plan → operator approval → receipt.
+
 The root npm identity remains `@inneranimalmedia/agentsam-sdk`. Package boundaries can evolve, but portable code should have one canonical owner and host applications should depend on it rather than mirror it.

package/protocol/capabilities/cloudflare-cpu-audit-input.schema.json

@@ -4,16 +4,40 @@
   "title": "cloudflare.cpu.audit input",
   "type": "object",
   "additionalProperties": false,
-  "required": ["file"],
+  "required": [
+    "cwd",
+    "file",
+    "sources",
+    "maxFrames",
+    "maxSourceChars"
+  ],
   "properties": {
-    "cwd": { "type": "string", "minLength": 1 },
-    "file": { "type": "string", "minLength": 1 },
+    "cwd": {
+      "type": "string",
+      "minLength": 1
+    },
+    "file": {
+      "type": "string",
+      "minLength": 1
+    },
     "sources": {
       "type": "array",
       "maxItems": 12,
-      "items": { "type": "string", "minLength": 1 }
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "maxFrames": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100
     },
-    "maxFrames": { "type": "integer", "minimum": 1, "maximum": 100 },
-    "maxSourceChars": { "type": "integer", "minimum": 1000, "maximum": 64000, "default": 24000 }
+    "maxSourceChars": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 64000,
+      "default": 24000
+    }
   }
 }

package/protocol/capabilities/cloudflare-cpu-profile-input.schema.json

@@ -4,10 +4,24 @@
   "title": "cloudflare.cpu.profile input",
   "type": "object",
   "additionalProperties": false,
-  "required": ["file"],
+  "required": [
+    "cwd",
+    "file",
+    "maxFrames"
+  ],
   "properties": {
-    "cwd": { "type": "string", "minLength": 1 },
-    "file": { "type": "string", "minLength": 1 },
-    "maxFrames": { "type": "integer", "minimum": 1, "maximum": 100 }
+    "cwd": {
+      "type": "string",
+      "minLength": 1
+    },
+    "file": {
+      "type": "string",
+      "minLength": 1
+    },
+    "maxFrames": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100
+    }
   }
 }

package/protocol/capabilities/cloudflare-wrangler-native-input.schema.json

@@ -4,16 +4,65 @@
   "title": "cloudflare.wrangler.native input",
   "type": "object",
   "additionalProperties": false,
-  "required": ["command"],
+  "required": [
+    "command",
+    "cwd",
+    "name",
+    "account",
+    "config",
+    "env",
+    "profile",
+    "path",
+    "page",
+    "version_id",
+    "tunnel"
+  ],
   "properties": {
-    "command": { "enum": ["whoami", "deployments.list", "versions.list", "types.check", "queues.list"] },
-    "cwd": { "type": "string", "minLength": 1 },
-    "name": { "type": "string" },
-    "account": { "type": "string" },
-    "config": { "type": "string" },
-    "env": { "type": "string" },
-    "profile": { "type": "string" },
-    "path": { "type": "string" },
-    "page": { "type": "integer", "minimum": 1 }
+    "command": {
+      "enum": [
+        "whoami",
+        "deployments.list",
+        "versions.list",
+        "versions.view",
+        "types.check",
+        "queues.list",
+        "tunnel.list",
+        "tunnel.info"
+      ]
+    },
+    "cwd": {
+      "type": "string",
+      "minLength": 1
+    },
+    "name": {
+      "type": "string"
+    },
+    "account": {
+      "type": "string"
+    },
+    "config": {
+      "type": "string"
+    },
+    "env": {
+      "type": "string"
+    },
+    "profile": {
+      "type": "string"
+    },
+    "path": {
+      "type": "string"
+    },
+    "page": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "version_id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tunnel": {
+      "type": "string",
+      "minLength": 1
+    }
   }
 }

package/protocol/capabilities/knowledge-search-input.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "text"
+  ],
+  "properties": {
+    "text": {
+      "type": "string",
+      "minLength": 1
+    },
+    "cwd": {
+      "type": "string",
+      "description": "Runtime-owned project root."
+    },
+    "semantic": {
+      "type": "boolean",
+      "default": false
+    },
+    "topK": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100
+    },
+    "tokenBudget": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 32000
+    },
+    "generationId": {
+      "type": "string"
+    }
+  }
+}

package/protocol/capabilities/manifest.json

@@ -75,7 +75,8 @@
       "deterministic": true,
       "model_required": false,
       "side_effects": "none",
-      "status": "stable"
+      "status": "stable",
+      "input_schema": "protocol/capabilities/knowledge-search-input.schema.json"
     },
     "merkle.snapshot": {
       "id": "merkle.snapshot",
@@ -119,6 +120,54 @@
       "side_effects": "network-optional",
       "status": "stable"
     },
+    "brand.scan": {
+      "id": "brand.scan",
+      "kind": "capability",
+      "version": 1,
+      "domain": "brand",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/brand",
+      "export": "brandScan",
+      "cli": "agentsam brand scan",
+      "description": "Deterministically extract brand/visual evidence from the same repository.snapshot file authority (colors, tokens, components, assets).",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "produces": ["brand.evidence"],
+      "status": "stable"
+    },
+    "brand.resolve": {
+      "id": "brand.resolve",
+      "kind": "capability",
+      "version": 1,
+      "domain": "brand",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/brand",
+      "export": "brandResolve",
+      "cli": "agentsam brand resolve",
+      "description": "Cluster observed brand evidence into inferred roles with confidence; never mutates the repository.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "produces": ["brand.resolved"],
+      "status": "stable"
+    },
+    "brand.plan": {
+      "id": "brand.plan",
+      "kind": "capability",
+      "version": 1,
+      "domain": "brand",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/brand",
+      "export": "brandPlan",
+      "cli": "agentsam plan brand",
+      "description": "Produce a preserve→normalize→migrate brand coherence plan; optional --goap sequencing.",
+      "deterministic": true,
+      "model_required": false,
+      "model_assisted_optional": true,
+      "side_effects": "none",
+      "status": "stable"
+    },
     "identity.init": {
       "id": "identity.init",
       "kind": "capability",
@@ -280,6 +329,21 @@
       "output_schema": "protocol/context/resolved-context-pack.schema.json",
       "status": "experimental"
     },
+    "terminal.exec": {
+      "id": "terminal.exec",
+      "kind": "capability",
+      "version": 1,
+      "domain": "terminal",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk",
+      "export": "terminalExec",
+      "description": "Run a real argv-safe CLI process inside the runtime-owned project, with bounded output, credential-stripped environment, and explicit execution approval.",
+      "deterministic": false,
+      "model_required": false,
+      "side_effects": "local-runtime",
+      "input_schema": "protocol/capabilities/terminal-exec-input.schema.json",
+      "status": "experimental"
+    },
     "cloudflare.wrangler.native": {
       "id": "cloudflare.wrangler.native",
       "kind": "capability",
@@ -326,6 +390,104 @@
       "side_effects": "none",
       "input_schema": "protocol/capabilities/cloudflare-cpu-audit-input.schema.json",
       "status": "experimental"
+    },
+    "workgraph.model": {
+      "id": "workgraph.model",
+      "kind": "capability",
+      "version": 1,
+      "domain": "workgraph",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/work-graph",
+      "export": "WorkGraph",
+      "description": "Core work-graph primitive (WorkItem, Dependency, TimelineEvent, Artifact, Evidence, Actor) that engineering and business adapters and timeline/Gantt renderers project onto. The graph is the source of truth; the timeline UI is a view over it, not its own state.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
+    },
+    "workgraph.adapter.engineering": {
+      "id": "workgraph.adapter.engineering",
+      "kind": "capability",
+      "version": 1,
+      "domain": "workgraph",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/work-graph/adapters/engineering/git",
+      "export": "createGitAdapter",
+      "description": "Maps supplied git commits to work items without network access.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
+    },
+    "workgraph.adapter.mcp": {
+      "id": "workgraph.adapter.mcp",
+      "kind": "capability",
+      "version": 1,
+      "domain": "workgraph",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/work-graph/adapters/engineering/mcp",
+      "export": "createMcpAdapter",
+      "description": "Maps supplied MCP tool call receipts to work items without network access.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
+    },
+    "workgraph.adapter.business": {
+      "id": "workgraph.adapter.business",
+      "kind": "capability",
+      "version": 1,
+      "domain": "workgraph",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/work-graph/adapters/business/projects",
+      "export": "createProjectsAdapter",
+      "description": "Maps supplied project records to work items without network access.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
+    },
+    "workgraph.render.timeline": {
+      "id": "workgraph.render.timeline",
+      "kind": "capability",
+      "version": 1,
+      "domain": "workgraph",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/work-graph/renderers/timeline",
+      "export": "createTimelineModel",
+      "description": "Renders a work graph into a timeline model (lanes by actor, work items per lane, timeline events) for a Gantt-style view. Pure projection \u2014 never a data source.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
+    },
+    "workgraph.render.gantt_model": {
+      "id": "workgraph.render.gantt_model",
+      "kind": "capability",
+      "version": 1,
+      "domain": "workgraph",
+      "runtime": "node",
+      "package": "@inneranimalmedia/agentsam-sdk/work-graph/renderers/gantt-model",
+      "export": "createGanttModel",
+      "description": "Projects work items to a Gantt model; a reference HTML prototype is included separately.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
+    },
+    "theme.storefront.shell": {
+      "id": "theme.storefront.shell",
+      "kind": "capability",
+      "version": 1,
+      "domain": "theme",
+      "runtime": "node",
+      "package": "@inneranimalmedia/heuristic-theme",
+      "export": "createStorefrontShellTheme",
+      "description": "Resolve the stock AgentSam CMS storefront shell theme contract.",
+      "deterministic": true,
+      "model_required": false,
+      "side_effects": "none",
+      "status": "experimental"
     }
   }
 }

package/protocol/capabilities/repository-audit-input.schema.json

@@ -5,10 +5,43 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "snapshot": { "type": "object" },
-    "focus": { "type": "array", "maxItems": 24, "items": { "type": "string" } },
-    "depth": { "enum": ["quick", "standard", "deep"], "default": "standard" },
-    "requestedSections": { "type": "array", "maxItems": 24, "items": { "type": "string" } },
-    "evidenceBudget": { "type": "integer", "minimum": 1000, "maximum": 64000, "default": 8000 }
-  }
+    "snapshot": {
+      "type": "object"
+    },
+    "focus": {
+      "type": "array",
+      "maxItems": 24,
+      "items": {
+        "type": "string"
+      }
+    },
+    "depth": {
+      "enum": [
+        "quick",
+        "standard",
+        "deep"
+      ],
+      "default": "standard"
+    },
+    "requestedSections": {
+      "type": "array",
+      "maxItems": 24,
+      "items": {
+        "type": "string"
+      }
+    },
+    "evidenceBudget": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 64000,
+      "default": 8000
+    }
+  },
+  "required": [
+    "snapshot",
+    "focus",
+    "depth",
+    "requestedSections",
+    "evidenceBudget"
+  ]
 }

package/protocol/capabilities/repository-snapshot-input.schema.json

@@ -5,7 +5,19 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "cwd": { "type": "string", "minLength": 1 },
-    "churnDays": { "type": "integer", "minimum": 1, "maximum": 3650, "default": 30 }
-  }
+    "cwd": {
+      "type": "string",
+      "minLength": 1
+    },
+    "churnDays": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 3650,
+      "default": 30
+    }
+  },
+  "required": [
+    "cwd",
+    "churnDays"
+  ]
 }