@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/packages/agentsam-hooks/test/runtime.test.mjs

@@ -0,0 +1,258 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  HOOK_PROTOCOL_SCHEMA,
+  AgentSamHooks,
+  HookPermissionError,
+  createCallbackHookAdapter,
+  createCommandHookAdapter,
+  createHookRuntime,
+  createHookedCapabilityAdapter,
+  createHookedProviderAdapter,
+  createHttpHookAdapter,
+  normalizeHookEvent,
+  normalizeHookOutput,
+} from '../src/index.js';
+
+const cwd = process.cwd();
+
+test('contract accepts ergonomic event/output aliases but emits canonical fields', () => {
+  assert.equal(HOOK_PROTOCOL_SCHEMA, 'agentsam.hook.v1');
+  assert.equal(new AgentSamHooks().list().length, 0);
+  assert.equal(normalizeHookEvent('onPreToolUse'), 'pre_tool_use');
+  assert.deepEqual(normalizeHookOutput('session_start', { modifiedConfig: { auto_compact: false } }), { modified_config: { auto_compact: false } });
+  assert.deepEqual(normalizeHookOutput('pre_tool_use', {
+    permissionDecision: 'allow',
+    modifiedArgs: { timeout: 30 },
+    additionalContext: 'bounded context',
+  }), {
+    permission_decision: 'allow',
+    modified_args: { timeout: 30 },
+    additional_context: 'bounded context',
+  });
+  assert.throws(() => normalizeHookOutput('post_tool_use', { permission_decision: 'deny' }), /not_supported/);
+  assert.throws(() => normalizeHookOutput('pre_tool_use', { permissionDecison: 'allow' }), /unsupported_hook_output_field/);
+});
+
+test('runtime composes modifications in priority order and receipts exclude values', async () => {
+  const observed = [];
+  const hooks = createHookRuntime({
+    onReceipt: (receipt) => observed.push(receipt),
+    hooks: {
+      pre_tool_use: [
+        {
+          id: 'second', priority: 20,
+          handler: ({ input }) => ({
+            permission_decision: 'allow',
+            modified_args: { ...input.tool_args, second: true },
+            additional_context: 'second context',
+          }),
+        },
+        {
+          id: 'first', priority: 10,
+          handler: ({ input }) => ({
+            permission_decision: 'allow',
+            modified_args: { ...input.tool_args, secret: 'not-in-receipt' },
+            additional_context: 'first context',
+          }),
+        },
+      ],
+    },
+  });
+  const result = await hooks.dispatch('pre_tool_use', {
+    tool_name: 'example.read', tool_args: { value: 1 },
+  }, { session_id: 'session-test' }, { cwd });
+  assert.deepEqual(result.input.tool_args, { value: 1, secret: 'not-in-receipt', second: true });
+  assert.equal(result.output.additional_context, 'first context\n\nsecond context');
+  assert.deepEqual(result.receipts.map((row) => row.hook_id), ['first', 'second']);
+  assert.equal(JSON.stringify(observed).includes('not-in-receipt'), false);
+});
+
+test('session-start config patches compose without discarding prior or base keys', async () => {
+  const hooks = createHookRuntime({ hooks: {
+    session_start: [
+      { id: 'model', priority: 10, handler: () => ({ modified_config: { model_key: 'xai:grok-4' } }) },
+      { id: 'effort', priority: 20, handler: () => ({ modified_config: { reasoning_effort: 'high' } }) },
+    ],
+  } });
+  const result = await hooks.dispatch('session_start', { config: { auto_compact: true } });
+  assert.deepEqual(result.input.config, {
+    auto_compact: true,
+    model_key: 'xai:grok-4',
+    reasoning_effort: 'high',
+  });
+  assert.deepEqual(result.output.modified_config, {
+    model_key: 'xai:grok-4',
+    reasoning_effort: 'high',
+  });
+});
+
+test('pre hooks fail closed by default while observers fail open', async () => {
+  const pre = createHookRuntime({ hooks: { pre_tool_use: { id: 'policy', handler: () => { throw new Error('offline api_key=do-not-record'); } } } });
+  const denied = await pre.dispatch('pre_tool_use', { tool_name: 'x', tool_args: {} });
+  assert.equal(denied.output.permission_decision, 'deny');
+  assert.match(denied.output.permission_decision_reason, /failed closed/);
+  assert.doesNotMatch(JSON.stringify(denied), /do-not-record/);
+  assert.deepEqual({
+    code: denied.receipts[0].error.error_code,
+    reason: denied.receipts[0].error.reason,
+    domain: denied.receipts[0].error.domain,
+    behavior: denied.receipts[0].error.failure_behavior,
+    sideEffect: denied.receipts[0].error.side_effect_state,
+    retryable: denied.receipts[0].error.retryable,
+  }, {
+    code: 'INTERNAL', reason: 'hook_handler_failed', domain: 'hook', behavior: 'fail_closed',
+    sideEffect: 'not_started', retryable: false,
+  });
+  assert.match(denied.receipts[0].error.fingerprint, /^err_[a-f0-9]{16}$/);
+  assert.equal(denied.receipts[0].native_evidence.message.includes('do-not-record'), false);
+
+  const post = createHookRuntime({ hooks: { post_tool_use: { id: 'audit', handler: () => { throw new Error('hook_http_timeout:1000'); } } } });
+  const allowed = await post.dispatch('post_tool_use', { tool_name: 'x', tool_result: { ok: true } });
+  assert.deepEqual(allowed.input.tool_result, { ok: true });
+  assert.equal(allowed.errors.length, 1);
+  assert.equal(allowed.receipts[0].error.reason, 'hook_http_timeout');
+  assert.equal(allowed.receipts[0].error.error_code, 'DEADLINE_EXCEEDED');
+  assert.equal(allowed.receipts[0].error.failure_behavior, 'fail_open');
+  assert.equal(allowed.receipts[0].error.side_effect_state, 'confirmed_applied');
+  assert.equal(allowed.receipts[0].error.retryable, false);
+});
+
+test('callback adapter exposes input and invocation without changing wire envelope', async () => {
+  const handler = createCallbackHookAdapter((input, invocation, envelope) => ({
+    permission_decision: input.tool_name === 'read' ? 'allow' : 'deny',
+    metadata: { session: invocation.session_id, schema: envelope.schema },
+  }));
+  const hooks = createHookRuntime({ hooks: { pre_tool_use: handler } });
+  const result = await hooks.dispatch('pre_tool_use', { tool_name: 'read', tool_args: {} }, { session_id: 's1' });
+  assert.equal(result.output.permission_decision, 'allow');
+  assert.deepEqual(result.output.metadata, { session: 's1', schema: 'agentsam.hook.v1' });
+});
+
+test('command adapter uses JSON stdin/stdout without a shell', async () => {
+  const script = [
+    "let data='';",
+    "process.stdin.on('data', c => data += c);",
+    "process.stdin.on('end', () => { const row=JSON.parse(data); console.error('diagnostic'); console.log(JSON.stringify({permission_decision: row.input.tool_name === 'safe' ? 'allow' : 'deny'})); });",
+  ].join('');
+  const adapter = createCommandHookAdapter({ command: process.execPath, args: ['-e', script], cwd, timeout_ms: 2_000 });
+  const hooks = createHookRuntime({ hooks: { pre_tool_use: { id: 'external', handler: adapter } } });
+  const result = await hooks.dispatch('pre_tool_use', { tool_name: 'safe', tool_args: {} }, {}, { cwd });
+  assert.equal(result.output.permission_decision, 'allow');
+});
+
+test('HTTP adapter exchanges the canonical envelope with a portable service', async (t) => {
+  const server = http.createServer((request, response) => {
+    let body = '';
+    request.on('data', chunk => { body += chunk; });
+    request.on('end', () => {
+      const envelope = JSON.parse(body);
+      response.setHeader('content-type', 'application/json');
+      response.end(JSON.stringify({
+        permission_decision: envelope.schema === 'agentsam.hook.v1' ? 'allow' : 'deny',
+      }));
+    });
+  });
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  t.after(() => server.close());
+  const address = server.address();
+  const handler = createHttpHookAdapter({ url: `http://127.0.0.1:${address.port}/hook`, timeout_ms: 2_000 });
+  const hooks = createHookRuntime({ hooks: { pre_tool_use: handler } });
+  const result = await hooks.dispatch('pre_tool_use', { tool_name: 'read', tool_args: {} });
+  assert.equal(result.output.permission_decision, 'allow');
+});
+
+test('capability wrapper enforces ask, argument modification, post transformation, and bounded retry', async () => {
+  let attempts = 0;
+  const hooks = createHookRuntime({ hooks: {
+    pre_tool_use: ({ input }) => ({
+      permission_decision: 'ask',
+      modified_args: { ...input.tool_args, approved: true },
+    }),
+    post_tool_use: ({ input }) => ({ modified_result: { ...input.tool_result, transformed: true } }),
+    error_occurred: ({ input }) => input.error_context === 'tool_execution'
+      ? { error_handling: 'retry', retry_count: 1 }
+      : null,
+  } });
+  const base = {
+    toolDescriptors: () => [{ name: 'example.write', input_schema: { type: 'object' } }],
+    async invoke(_id, input) {
+      attempts += 1;
+      if (attempts === 1) throw new Error('temporary');
+      return { input };
+    },
+  };
+  const adapter = createHookedCapabilityAdapter(base, {
+    hookRuntime: hooks,
+    requestPermission: async () => true,
+    maxRetries: 1,
+  });
+  const result = await adapter.invoke('example.write', { value: 1 });
+  assert.equal(attempts, 2);
+  assert.deepEqual(result, { input: { value: 1, approved: true }, transformed: true });
+
+  const noApproval = createHookedCapabilityAdapter(base, { hookRuntime: hooks, requestPermission: async () => false });
+  await assert.rejects(noApproval.invoke('example.write', {}), HookPermissionError);
+});
+
+test('provider wrapper modifies a provider-neutral request and result', async () => {
+  const hooks = createHookRuntime({ hooks: {
+    pre_model_use: ({ input }) => ({
+      permission_decision: 'allow',
+      modified_request: { ...input.request, model: 'portable-model', temperature: 0 },
+    }),
+    post_model_use: ({ input }) => ({ modified_result: { ...input.model_result, output_text: 'redacted' } }),
+  } });
+  let request;
+  const provider = createHookedProviderAdapter({
+    provider: 'fixture',
+    async create(value) { request = value; return { output_text: 'raw', tool_calls: [] }; },
+    async continueWithToolOutputs(value) { return this.create(value); },
+  }, { hookRuntime: hooks });
+  const result = await provider.create({ model: 'initial', input: 'hello' });
+  assert.equal(request.model, 'portable-model');
+  assert.equal(request.temperature, 0);
+  assert.equal(result.output_text, 'redacted');
+});
+
+test('post-hook failures never replay a completed side effect or paid model request', async () => {
+  const receipts = [];
+  const hooks = createHookRuntime({ onReceipt: (receipt) => receipts.push(receipt), hooks: {
+    post_tool_use: { id: 'tool-post', failure_mode: 'error', handler: () => { throw new Error('observer failed'); } },
+    post_model_use: { id: 'model-post', failure_mode: 'error', handler: () => { throw new Error('observer failed'); } },
+    error_occurred: () => ({ error_handling: 'retry', retry_count: 3 }),
+  } });
+  let toolCalls = 0;
+  const capability = createHookedCapabilityAdapter({
+    toolDescriptors: () => [{ name: 'write' }],
+    async invoke() { toolCalls += 1; return { ok: true }; },
+  }, { hookRuntime: hooks });
+  await assert.rejects(capability.invoke('write'), /hook_execution_failed:tool-post/);
+  assert.equal(toolCalls, 1);
+
+  let modelCalls = 0;
+  const provider = createHookedProviderAdapter({
+    provider: 'fixture',
+    async create() { modelCalls += 1; return { output_text: 'paid result', tool_calls: [] }; },
+    async continueWithToolOutputs() { throw new Error('unused'); },
+  }, { hookRuntime: hooks });
+  await assert.rejects(provider.create({ model: 'fixture' }), /hook_execution_failed:model-post/);
+  assert.equal(modelCalls, 1);
+  const failures = receipts.filter((receipt) => receipt.status === 'failed');
+  assert.equal(failures.length, 2);
+  for (const receipt of failures) {
+    assert.equal(receipt.error.failure_behavior, 'no_replay');
+    assert.equal(receipt.error.side_effect_state, 'confirmed_applied');
+    assert.equal(receipt.error.retryable, false);
+  }
+});
+
+test('runtime rejects duplicate hook ids', () => {
+  const runtime = createHookRuntime();
+  runtime.register('session_start', { id: 'same', handler: () => null });
+  assert.throws(() => runtime.register('session_start', { id: 'same', handler: () => null }), /duplicate_hook_id/);
+});

package/packages/agentsam-knowledge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-knowledge",
-  "version": "2.6.9",
+  "version": "2.6.11",
   "description": "Portable AutoRAG discovery, adapter registries, probes, and company routing contracts for AgentSam.",
   "type": "module",
   "exports": {

package/packages/agentsam-knowledge/src/backends/index.js

@@ -1,4 +1,4 @@
-import { vectorizeDelete, vectorizeGetByIds, vectorizeHealth, vectorizeQuery, vectorizeUpsert } from '../../../connectors/cloudflare/src/families/vectorize.js';
+import { vectorizeDelete, vectorizeGetByIds, vectorizeHealth, vectorizeQuery, vectorizeUpsert } from '../../../connectors/cfoa/src/families/vectorize.js';
 
 const clean = value => String(value || '').trim();
 function profileGuard(profile, supported) {

package/packages/agentsam-merch/README.md

@@ -0,0 +1,62 @@
+# @inneranimalmedia/agentsam-merch
+
+Portable manufacturing preflight and merch planning for AgentSam applications.
+
+The package separates manufacturing profile **data** from execution code, provider adapters from the media engine, preserved source masters from manufacturing/storefront derivatives, and deterministic preflight from human/process-specific handoffs.
+
+## Profile contract
+
+Profiles are JSON under `profiles/<manufacturer>/`. Provider requirements do not belong in application conditionals.
+
+The engine returns:
+
+- `ready`
+- `ready_with_transform`
+- `needs_variant`
+- `prepared_for_digitization`
+- `unsupported`
+
+A low-resolution raster is never called production-ready. An embroidery source is never represented as a finished stitch file.
+
+## Derivative authority
+
+```text
+original/master
+  ├─ manufacturing
+  ├─ storefront/gallery
+  ├─ thumbnail
+  ├─ social
+  └─ mockup
+```
+
+The manufacturing plan is marked `mustNotUseStorefrontDerivative`.
+
+## Collection Lab
+
+Portable candidate states:
+
+```text
+concept
+approved-art
+production-ready
+sample-ordered
+sample-approved
+published
+retired
+```
+
+## Provider adapters
+
+Adapters only translate provider catalog metadata into a neutral selection context. The Completeful adapter knows field names such as `print_type` and `file_width`; manufacturing rules remain profile data.
+
+## CLI kernel
+
+The standalone proof is:
+
+```text
+agentsam-merch build <manifest.json> --all-compatible
+```
+
+The distributed AgentSam CLI can delegate `agentsam merch build ...` to the same `buildMerchPlan()` kernel.
+
+Seed Completeful profiles are marked `operator-defined` until verified against provider documentation.

package/packages/agentsam-merch/bin/agentsam-merch.mjs

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { runMerchCli } from "../src/cli.js";
+
+export { runMerchCli };
+
+const isMain =
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isMain) {
+  runMerchCli(process.argv.slice(2)).catch((error) => {
+    console.error(error?.message || String(error));
+    process.exitCode = 1;
+  });
+}

package/packages/agentsam-merch/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@inneranimalmedia/agentsam-merch",
+  "version": "2.6.11",
+  "description": "Provider-neutral manufacturing profiles, preflight, derivative planning, and collection-lab primitives for AgentSam.",
+  "type": "module",
+  "files": [
+    "src",
+    "profiles",
+    "bin",
+    "README.md",
+    "schemas"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./profiles": "./src/profile.js",
+    "./registry": "./src/profile-registry.js",
+    "./compatibility": "./src/compatibility.js",
+    "./derivatives": "./src/derivatives.js",
+    "./collection-lab": "./src/collection-lab.js",
+    "./adapters/completeful": "./src/adapters-completeful.js",
+    "./profiles/*": "./profiles/*",
+    "./transforms": {
+      "types": "./src/index.d.ts",
+      "import": "./src/transforms.js"
+    },
+    "./node": {
+      "types": "./src/node/index.d.ts",
+      "import": "./src/node/index.js"
+    }
+  },
+  "bin": {
+    "agentsam-merch": "./bin/agentsam-merch.mjs"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/agentsam-merch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "sharp": ">=0.33.0",
+    "svgo": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    },
+    "svgo": {
+      "optional": true
+    }
+  }
+}

package/packages/agentsam-merch/profiles/completeful/dtg-back-large.json

@@ -0,0 +1,42 @@
+{
+  "schemaVersion": "agentsam.manufacturing-profile.v1",
+  "id": "completeful.dtg.back-large",
+  "manufacturer": "completeful",
+  "process": "dtg",
+  "format": "png",
+  "colorSpace": "srgb",
+  "alpha": true,
+  "ppi": 300,
+  "maxBytes": 20000000,
+  "preferredPrintWidthIn": 13,
+  "allowRaster": true,
+  "allowVector": false,
+  "match": {
+    "manufacturer": "completeful",
+    "process": "dtg",
+    "locationName": "back",
+    "minWidthIn": 10
+  },
+  "source": {
+    "kind": "provider-documentation",
+    "verified": true,
+    "verifiedAt": "2026-10-03",
+    "notes": [
+      "PNG recommended for transparent artwork",
+      "RGB/sRGB color mode",
+      "300 DPI minimum at final print size",
+      "20 MB PNG upload limit"
+    ]
+  },
+  "$schema": "https://schemas.inneranimalmedia.com/agentsam/schemas/agentsam.manufacturing-profile.v1.json",
+  "resolution": {
+    "readyPpi": 300,
+    "minimumPpi": 300
+  },
+  "autoNormalize": {
+    "trimAlpha": true,
+    "colorSpace": true,
+    "svgOptimize": false,
+    "outlineText": false
+  }
+}

package/packages/agentsam-merch/profiles/completeful/laser-engraving.json

@@ -0,0 +1,39 @@
+{
+  "schemaVersion": "agentsam.manufacturing-profile.v1",
+  "id": "completeful.laser-engraving",
+  "manufacturer": "completeful",
+  "process": "engraving",
+  "preferredFormat": "svg",
+  "colorMode": "monochrome",
+  "allowRaster": false,
+  "allowVector": true,
+  "allowGradients": false,
+  "requireClosedPaths": true,
+  "outlineText": true,
+  "match": {
+    "manufacturer": "completeful",
+    "process": [
+      "engraving",
+      "etching"
+    ]
+  },
+  "source": {
+    "kind": "operator-defined",
+    "verified": false
+  },
+  "$schema": "https://schemas.inneranimalmedia.com/agentsam/schemas/agentsam.manufacturing-profile.v1.json",
+  "requireViewBox": true,
+  "autoNormalize": {
+    "trimAlpha": false,
+    "colorSpace": false,
+    "svgOptimize": true,
+    "outlineText": true
+  },
+  "vectorization": {
+    "enabled": true,
+    "preferredTracer": "auto",
+    "maxAspectDrift": 0.02,
+    "minBoundaryIntegrity": 0.98,
+    "outputFormat": "svg"
+  }
+}

package/packages/agentsam-merch/profiles/generic/embroidery-digitization.json

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "agentsam.manufacturing-profile.v1",
+  "id": "generic.embroidery.pre-digitization",
+  "manufacturer": "generic",
+  "process": "embroidery",
+  "preferredFormat": "svg",
+  "colorMode": "spot",
+  "allowRaster": false,
+  "allowVector": true,
+  "allowGradients": false,
+  "requireClosedPaths": true,
+  "outlineText": true,
+  "handoff": {
+    "status": "prepared_for_digitization",
+    "reason": "Stitch direction, density, underlay, pull compensation, thread sequencing, and machine format require embroidery-specific digitization."
+  },
+  "source": {
+    "kind": "process-safety-default",
+    "verified": true
+  },
+  "$schema": "https://schemas.inneranimalmedia.com/agentsam/schemas/agentsam.manufacturing-profile.v1.json"
+}

package/packages/agentsam-merch/schemas/collection-candidate.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/schemas/agentsam.collection-candidate.v1.json",
+  "title": "AgentSam Collection Lab Candidate",
+  "type": "object",
+  "required": [
+    "id",
+    "designId",
+    "state"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "designId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "collectionPath": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "state": {
+      "enum": [
+        "concept",
+        "approved-art",
+        "production-ready",
+        "sample-ordered",
+        "sample-approved",
+        "published",
+        "retired"
+      ]
+    },
+    "products": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "approvals": {
+      "type": "object",
+      "properties": {
+        "artwork": {
+          "type": "boolean"
+        },
+        "wording": {
+          "type": "boolean"
+        },
+        "palette": {
+          "type": "boolean"
+        },
+        "visualIdentity": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "metadata": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}