@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

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/apps/agentsam.app.v1.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/apps/agentsam.app.v1.schema.json",
+  "title": "agentsam.app.v1",
+  "description": "Installable AgentSam product app. Owns its routes/runtime; identity never hardcodes product URLs.",
+  "type": "object",
+  "required": ["schema", "id", "name"],
+  "properties": {
+    "schema": { "const": "agentsam.app.v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "package": { "type": "string" },
+    "version": { "type": "string" },
+    "routes": {
+      "type": "object",
+      "properties": {
+        "entry": {
+          "type": "string",
+          "description": "Authenticated entry path after login when no return_to exists",
+          "pattern": "^/"
+        },
+        "mounts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path"],
+            "properties": {
+              "path": { "type": "string", "pattern": "^/" },
+              "auth": { "enum": ["required", "optional", "public"], "default": "public" },
+              "spa": { "type": "boolean" },
+              "shell": {
+                "type": "string",
+                "description": "Build artifact relative to assetRoot (must exist after build)"
+              }
+            }
+          }
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "properties": {
+        "type": { "enum": ["spa", "ssr", "static"] },
+        "assetRoot": { "type": "string" },
+        "shell": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/protocol/brand/brandpack.v1.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/brand/brandpack.v1.schema.json",
+  "title": "AgentSamBrandPack",
+  "type": "object",
+  "required": ["schema", "id"],
+  "properties": {
+    "schema": { "const": "agentsam.brandpack.v1" },
+    "id": { "type": "string" },
+    "label": { "type": "string" },
+    "source": {
+      "type": "object",
+      "properties": {
+        "repository_id": { "type": ["string", "null"] },
+        "snapshot_id": { "type": ["string", "null"] },
+        "materials": { "type": "array" }
+      }
+    },
+    "identity": { "type": "object" },
+    "tokens": {
+      "type": "object",
+      "properties": {
+        "palette": { "type": "object" },
+        "semantic": { "type": "object" },
+        "typography": { "type": "object" },
+        "spacing": { "type": "object" },
+        "geometry": { "type": "object" },
+        "effects": { "type": "object" }
+      }
+    },
+    "assets": { "type": "array" },
+    "components": { "type": "array" },
+    "sections": { "type": "array" },
+    "layouts": { "type": "array" },
+    "pages": { "type": "array" },
+    "theme_variants": { "type": "array" },
+    "content_refs": { "type": "array" },
+    "url_refs": { "type": "array" },
+    "evidence": { "type": "array" },
+    "conflicts": { "type": "array" },
+    "provenance": { "type": "array" }
+  }
+}

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"
+    }
+  }
+}