@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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

@@ -20,7 +20,29 @@ export class WorkGraph {
 }
 
 export class WorkItem {
-  constructor({ id, title, type = 'task', status = 'planned', owner = null, start = null, end = null, dependencies = [], artifacts = [], evidence = [] } = {}) {
+  constructor({
+    id,
+    title,
+    type = 'task',
+    status = 'planned',
+    owner = null,
+    start = null,
+    end = null,
+    baselineStart = null,
+    baselineEnd = null,
+    progress = null,
+    parentId = null,
+    dependencies = [],
+    blockedReason = null,
+    estimateMinutes = null,
+    actualMinutes = null,
+    executionRef = null,
+    goapRef = null,
+    version = 1,
+    metadata = {},
+    artifacts = [],
+    evidence = [],
+  } = {}) {
     this.id = id ?? randomUUID();
     this.title = title;
     this.type = type;
@@ -28,7 +50,18 @@ export class WorkItem {
     this.owner = owner;
     this.start = start;
     this.end = end;
+    this.baselineStart = baselineStart;
+    this.baselineEnd = baselineEnd;
+    this.progress = progress;
+    this.parentId = parentId;
     this.dependencies = dependencies;
+    this.blockedReason = blockedReason;
+    this.estimateMinutes = estimateMinutes;
+    this.actualMinutes = actualMinutes;
+    this.executionRef = executionRef;
+    this.goapRef = goapRef;
+    this.version = version;
+    this.metadata = metadata;
     this.artifacts = artifacts;
     this.evidence = evidence;
   }

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

@@ -1,11 +1,35 @@
+function projectOwner(owner, actorById) {
+  if (!owner) return null;
+  if (typeof owner === 'object') return owner;
+  const actor = actorById.get(owner);
+  return actor ? { id: actor.id, name: actor.name, role: actor.role } : owner;
+}
+
 export function createGanttModel(graph) {
   const items = graph?.items ?? graph?.workItems ?? [];
+  const actorById = new Map((graph?.actors ?? []).map((actor) => [actor.id, actor]));
 
   return items.map((item) => ({
     id: item.id,
     title: item.title,
+    kind: item.type ?? 'task',
     status: item.status,
+    owner: projectOwner(item.owner, actorById),
     start: item.start ?? null,
     end: item.end ?? null,
+    baselineStart: item.baselineStart ?? null,
+    baselineEnd: item.baselineEnd ?? null,
+    progress: typeof item.progress === 'number' ? item.progress : null,
+    parentId: item.parentId ?? null,
+    dependencies: [...(item.dependencies ?? [])],
+    blockedReason: item.blockedReason ?? null,
+    estimateMinutes: item.estimateMinutes ?? null,
+    actualMinutes: item.actualMinutes ?? null,
+    executionRef: item.executionRef ?? null,
+    goapRef: item.goapRef ?? null,
+    version: item.version ?? 1,
+    artifactCount: item.artifacts?.length ?? 0,
+    evidenceCount: item.evidence?.length ?? 0,
+    metadata: { ...(item.metadata ?? {}) },
   }));
 }

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

@@ -7,11 +7,25 @@ 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', () => {
+test('work graph projects one source of truth into timeline and rich 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 item = new WorkItem({
+    id: 'task-1',
+    title: 'Index repository',
+    owner: actor.id,
+    start: '2026-09-18',
+    end: '2026-09-19',
+    baselineStart: '2026-09-17',
+    baselineEnd: '2026-09-18',
+    progress: 0.5,
+    parentId: 'phase-index',
+    estimateMinutes: 120,
+    actualMinutes: 70,
+    dependencies: ['inventory'],
+    artifacts: [{ id: 'artifact-1' }],
+    evidence: ['receipt-1'],
+    metadata: { summary: 'Repository indexing' },
+  });
   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 }));
@@ -21,9 +35,15 @@ test('work graph projects one source of truth into timeline and Gantt views', ()
   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',
-  });
+
+  const gantt = createGanttModel(graph)[0];
+  assert.equal(gantt.id, 'task-1');
+  assert.equal(gantt.owner.name, 'Agent One');
+  assert.equal(gantt.progress, 0.5);
+  assert.equal(gantt.parentId, 'phase-index');
+  assert.equal(gantt.artifactCount, 1);
+  assert.equal(gantt.evidenceCount, 1);
+  assert.deepEqual(gantt.dependencies, ['inventory']);
 });
 
 test('adapters map source records without fetching or mutating them', () => {

package/protocol/README.md

@@ -20,10 +20,12 @@ Platform repositories may consume the SDK, provide host adapters, or incubate pr
 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)
+├── packages/                  # Reusable PACKAGE / SERVICE / THEME code
+├── apps/                      # Portable product APPs (when agentsam.app.json exists)
+│   └── */agentsam.app.json    # Canonical APP product definition (APP.id)
+│   └── */.agentsam/app.json   # Host/install state (app_id → APP.id)
 ├── protocol/                  # Shared SDK contracts and ownership rules
+│   ├── apps/                  # agentsam.app.v1 + host-install schemas
 │   └── features/              # agentsam.feature.v1 schema + catalog
 ├── templates/                 # Scaffold templates
 ├── examples/                  # Runnable examples/pointers
@@ -31,12 +33,18 @@ agentsam-sdk/
 └── test/ + python/tests/      # Node and Python verification
 ```
 
-### APP vs FEATURE
+### Artifact taxonomy
 
-| Unit | Manifest | Role |
+| Type | Manifest | Role |
 |------|----------|------|
-| APP | `.agentsam/app.json` | Runnable/mountable product composition |
-| FEATURE | `agentsam.feature.json` | Vertical capability (provider/UI/domain/composer) |
+| **APP** | `agentsam.app.json` | Portable installable product — sole `APP.id` authority |
+| **PACKAGE** | `agentsam.package.json` / package metadata | Reusable code/capability |
+| **SERVICE** | `agentsam.package.json` (`type: "service"`) | Runtime infrastructure |
+| **HOST install** | `.agentsam/app.json` | Installation/mount state; references `app_id` |
+| **THEME** | theme package / theme-site scaffold | Appearance/content kit — not an APP |
+| **FEATURE** | `agentsam.feature.json` | Vertical capability (provider/UI/domain) |
+
+SSOT: [`docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md`](../docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md) · `agentsam app validate`
 
 `npm install` is inert. AgentSam activates features after validation → plan → operator approval → receipt.
 

package/protocol/apps/agentsam.app.v1.schema.json

@@ -0,0 +1,133 @@
+{
+  "$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. Canonical identity is id (kebab-case). Package, Worker, route, desktop, and service names live in other namespaces.",
+  "type": "object",
+  "required": ["schema", "id", "name", "kind"],
+  "properties": {
+    "schema": { "const": "agentsam.app.v1" },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "minLength": 2,
+      "description": "Immutable APP.id — short kebab-case product identity (not Worker/npm/route name)"
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "kind": { "const": "app" },
+    "product_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Optional platform PRODUCT registry id when it differs from APP.id"
+    },
+    "package": {
+      "type": "string",
+      "description": "npm package name (PACKAGE namespace) — must not be used as APP.id"
+    },
+    "version": { "type": "string" },
+    "entrypoints": {
+      "type": "object",
+      "properties": {
+        "frontend": { "type": "string" },
+        "backend": { "type": "string" },
+        "cli": { "type": "string" }
+      },
+      "additionalProperties": { "type": "string" }
+    },
+    "capabilities": {
+      "description": "Capability tokens this APP provides (array) or legacy boolean map",
+      "oneOf": [
+        {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        {
+          "type": "object",
+          "additionalProperties": { "type": "boolean" }
+        }
+      ]
+    },
+    "provides": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "bin": { "type": "string" },
+    "commands": { "type": "object", "additionalProperties": { "type": "string" } },
+    "surfaces": {
+      "oneOf": [
+        { "type": "array", "items": { "type": "string" } },
+        { "type": "object" }
+      ]
+    },
+    "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)"
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "runtime": {
+      "type": "object",
+      "properties": {
+        "type": { "enum": ["spa", "ssr", "static"] },
+        "assetRoot": { "type": "string" },
+        "shell": { "type": "string" },
+        "browser": { "type": ["boolean", "string"] },
+        "local": { "type": ["boolean", "string"] },
+        "cloudflare": { "type": ["boolean", "string"] }
+      },
+      "additionalProperties": true
+    },
+    "preview": { "type": "object", "additionalProperties": true },
+    "install": { "type": "object", "additionalProperties": true },
+    "auth": { "type": "object", "additionalProperties": true },
+    "hosts": {
+      "type": "array",
+      "description": "HOST namespace — public origins this APP is served from. Separate from APP.id and from PLATFORM IAM_OAUTH_ISSUER.",
+      "items": {
+        "type": "object",
+        "required": ["host_id", "origin"],
+        "properties": {
+          "host_id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+            "description": "Canonical HOST.id for this origin"
+          },
+          "origin": {
+            "type": "string",
+            "format": "uri",
+            "description": "https://… origin (no path)"
+          },
+          "role": {
+            "type": "string",
+            "enum": ["production", "development", "preview", "staging"]
+          },
+          "notes": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "secrets": { "type": "object", "additionalProperties": true }
+  },
+  "additionalProperties": true
+}

package/protocol/apps/agentsam.host-install.v1.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/apps/agentsam.host-install.v1.schema.json",
+  "title": "agentsam.host-install.v1",
+  "description": "Host/installation state for an AgentSam APP. Lives under .agentsam/app.json. References APP.id; must not redefine product identity (enforced by agentsam app validate).",
+  "type": "object",
+  "required": ["schema", "app_id"],
+  "properties": {
+    "schema": { "const": "agentsam.host-install.v1" },
+    "app_id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Must resolve to a known agentsam.app.json id"
+    },
+    "config": { "type": "object", "additionalProperties": true },
+    "mounts": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "type": "string" },
+          {
+            "type": "object",
+            "additionalProperties": true
+          }
+        ]
+      }
+    },
+    "features": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Feature ids enabled for this installation"
+    },
+    "notes": { "type": "string" }
+  },
+  "additionalProperties": true
+}

package/protocol/assets/README.md

@@ -0,0 +1,9 @@
+# AgentSam Asset Core
+
+Canonical `ast_*` identity shared by **BrandPack** and **Content** (peer domains).
+
+- Schema: [`asset-record.v1.schema.json`](./asset-record.v1.schema.json)
+- Package: `@inneranimalmedia/agentsam-assets-core`
+- Authority: `docs/content-studio/REVISION_GATE_2026-09-27.md`
+
+Providers own representations/transport only. Knowledge indexes are derived.

package/protocol/assets/asset-record.v1.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/assets/asset-record.v1.schema.json",
+  "title": "AgentSamAssetRecord",
+  "description": "Shared Asset Core — canonical ast_* identity. BrandPack and Content are peer domains over this record. Providers hold representations only.",
+  "type": "object",
+  "required": ["schema", "id", "accountId", "kind", "representations", "provenance", "createdAt", "updatedAt"],
+  "properties": {
+    "schema": { "const": "agentsam.asset-record.v1" },
+    "id": {
+      "type": "string",
+      "pattern": "^ast_"
+    },
+    "accountId": { "type": "string", "minLength": 1 },
+    "kind": {
+      "type": "string",
+      "enum": ["image", "video", "model", "font", "document", "audio"]
+    },
+    "originalName": { "type": "string" },
+    "mime": { "type": "string" },
+    "bytes": { "type": "integer", "minimum": 0 },
+    "hashes": {
+      "type": "object",
+      "properties": {
+        "sha256": { "type": "string" },
+        "perceptual": { "type": "string" }
+      }
+    },
+    "machineFacts": { "type": "object" },
+    "representations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["provider", "ref", "role"],
+        "properties": {
+          "provider": { "type": "string" },
+          "ref": { "type": "string" },
+          "role": {
+            "type": "string",
+            "enum": ["original", "master", "derivative", "preview", "poster", "backup", "delivery", "source"]
+          },
+          "scope": { "type": "string" },
+          "bytes": { "type": "integer" },
+          "mime": { "type": "string" },
+          "url": { "type": "string" },
+          "verified": { "type": "boolean" },
+          "receipt": { "type": "object" }
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "required": ["history"],
+      "properties": {
+        "history": { "type": "array" },
+        "generation": { "type": "object" },
+        "import": { "type": "object" },
+        "derivedFrom": { "type": "string" }
+      }
+    },
+    "createdAt": { "type": "string" },
+    "updatedAt": { "type": "string" }
+  }
+}

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/credentials/issue.v1.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agentsam.inneranimalmedia.com/protocol/credentials/issue.v1.schema.json",
+  "title": "credentials.issue",
+  "description": "Mint an AgentSam API credential (aak_*). Host stores hash only; secret returned once.",
+  "type": "object",
+  "required": ["operation", "input", "output"],
+  "properties": {
+    "operation": { "const": "credentials.issue" },
+    "input": {
+      "type": "object",
+      "required": ["account_id", "name"],
+      "properties": {
+        "account_id": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "scopes": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Semantic capability scopes (e.g. repository:read, models:invoke)"
+        },
+        "environment": { "enum": ["development", "preview", "production"] },
+        "expires_at": { "type": ["string", "null"], "format": "date-time" },
+        "client_type": { "enum": ["cli", "ci", "agent", "integration"] }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["credential_id", "prefix", "secret_once", "created_at"],
+      "properties": {
+        "credential_id": { "type": "string" },
+        "prefix": { "type": "string" },
+        "secret_once": { "type": "string", "description": "Plaintext shown once; never stored by host" },
+        "scopes": { "type": "array", "items": { "type": "string" } },
+        "created_at": { "type": "string", "format": "date-time" }
+      }
+    }
+  }
+}

package/protocol/database/connection.v1.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentsam.database-connection.v1",
+  "title": "AgentSamDatabaseConnection",
+  "type": "object",
+  "required": ["id", "engine", "provider", "connection"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "agentsam.database-connection.v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "label": { "type": "string" },
+    "engine": { "enum": ["sqlite", "postgres", "mysql"] },
+    "provider": {
+      "enum": ["local", "cloudflare-d1", "supabase", "postgres", "mysql"]
+    },
+    "account_id": { "type": "string", "description": "Optional hosted owner. Never workspace_id." },
+    "connection": { "type": "object" },
+    "accelerator": {
+      "type": "object",
+      "required": ["driver", "configurationId"],
+      "properties": {
+        "driver": { "const": "hyperdrive" },
+        "configurationId": { "type": "string" },
+        "localConnectionStringRef": { "type": "string" }
+      }
+    },
+    "vectors": {
+      "type": "object",
+      "required": ["driver"],
+      "properties": {
+        "driver": {
+          "enum": ["none", "sqlite_exact", "sqlite_vector", "pgvector", "vectorize"]
+        },
+        "profileId": { "type": "string" },
+        "indexName": { "type": "string" },
+        "namespace": { "type": "string" }
+      }
+    },
+    "created_at": { "type": "string" }
+  }
+}

package/protocol/embeddings/embedding-profile.v1.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "agentsam.embedding-profile.v1",
+  "title": "AgentSamEmbeddingProfile",
+  "type": "object",
+  "required": ["schema", "id", "provider", "dimensions", "revision", "fingerprint"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": { "const": "agentsam.embedding-profile.v1" },
+    "id": { "type": "string" },
+    "provider": { "type": "string" },
+    "model": { "type": ["string", "null"] },
+    "dimensions": { "type": "integer", "minimum": 1 },
+    "revision": { "type": "string" },
+    "parameters": { "type": "object" },
+    "fingerprint": { "type": "string" },
+    "experimental": { "type": "boolean" },
+    "locality": { "enum": ["local", "remote", "none"] }
+  }
+}