@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/packages/agentsam-contracts/tsconfig.build.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}

package/packages/agentsam-errors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inneranimalmedia/agentsam-errors",
-  "version": "2.6.7",
+  "version": "2.6.9",
   "description": "Canonical AgentSam runtime error normalization, classification, transport, remediation and rendering.",
   "type": "module",
   "main": "./src/index.js",
@@ -23,5 +23,6 @@
   },
   "files": [
     "src"
-  ]
+  ],
+  "license": "MIT"
 }

package/packages/agentsam-errors/src/index.js

@@ -1,6 +1,7 @@
 export * from './vocabulary.js';
 export * from './envelope.js';
 export * from './error.js';
+export * from './tool.js';
 export * from './normalize.js';
 export * from './redaction.js';
 export * from './fingerprint.js';

package/packages/agentsam-errors/src/tool.js

@@ -0,0 +1,56 @@
+import { createErrorEnvelope } from './envelope.js';
+import { AgentSamError } from './error.js';
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function nativeFromCause(cause) {
+  if (!cause || typeof cause !== 'object') return null;
+  return {
+    code: cause.code || null,
+    exception_type: cause.name || null,
+    exit_code: cause.exit_code ?? cause.exitCode ?? null,
+    signal: cause.signal || null,
+    stderr: cause.stderr || null,
+    stdout: cause.stdout || null,
+    stack: cause.stack || null,
+  };
+}
+
+/**
+ * Build the canonical AgentSam error envelope for any tool/capability.
+ *
+ * Tool implementations should supply an existing ERROR_REASON plus tool/stage
+ * context. Do not mint tool-specific error taxonomies when the shared
+ * vocabulary already describes the failure.
+ */
+export function createToolErrorEnvelope(input = {}, options = {}) {
+  const tool = clean(input.tool);
+  if (!tool) throw new TypeError('tool is required');
+
+  const cause = options.cause || input.cause || null;
+  const { cause: _ignoredCause, ...envelopeInput } = input;
+
+  return createErrorEnvelope({
+    ...envelopeInput,
+    domain: input.domain || 'tool',
+    tool,
+    stage: clean(input.stage) || 'execute',
+    source: input.source || {
+      kind: 'agentsam',
+      name: 'agentsam-sdk',
+      service: tool,
+    },
+    native: input.native || nativeFromCause(cause),
+  });
+}
+
+/**
+ * Throwable view over createToolErrorEnvelope().
+ */
+export function createToolError(input = {}, options = {}) {
+  const cause = options.cause || input.cause || null;
+  const envelope = createToolErrorEnvelope(input, { cause });
+  return new AgentSamError(envelope, cause ? { cause } : {});
+}

package/packages/agentsam-errors/test/tool.test.mjs

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  AgentSamError,
+  ERROR_CODE,
+  ERROR_REASON,
+  createToolError,
+  createToolErrorEnvelope,
+  planRecovery,
+} from '../src/index.js';
+
+test('tool errors reuse the canonical AgentSam vocabulary', () => {
+  const error = createToolError({
+    reason: ERROR_REASON.STALE_VERSION,
+    message: 'The resource changed before this mutation could commit.',
+    tool: 'goap',
+    stage: 'activate_goal',
+    failure_class: 'conflict',
+    resource: { type: 'blackboard', id: 'bb_1' },
+    details: { expected_revision: 4, actual_revision: 5 },
+    operation: {
+      kind: 'mutation',
+      action: 'activate_goal',
+      resource_type: 'blackboard',
+      resource_id: 'bb_1',
+      read_only: false,
+      idempotent: true,
+      side_effect_state: 'confirmed_not_applied',
+    },
+  });
+
+  assert.equal(error instanceof AgentSamError, true);
+  assert.equal(error.code, ERROR_CODE.ABORTED);
+  assert.equal(error.reason, ERROR_REASON.STALE_VERSION);
+  assert.equal(error.envelope.domain, 'tool');
+  assert.equal(error.envelope.tool, 'goap');
+  assert.equal(error.envelope.retryable, true);
+  assert.equal(error.envelope.details.expected_revision, 4);
+
+  const recovery = planRecovery(error.envelope);
+  assert.equal(recovery.disposition, 'retry');
+  assert.equal(recovery.reason, 'optimistic_concurrency');
+});
+
+test('tool envelope preserves generic internal adapter classification', () => {
+  const envelope = createToolErrorEnvelope({
+    reason: ERROR_REASON.INTERNAL_ADAPTER_FAILED,
+    message: 'The storage adapter cannot provide the required atomic primitive.',
+    tool: 'queue-control',
+    stage: 'dispatch',
+    resource: { type: 'adapter', id: 'sqlite' },
+  });
+
+  assert.equal(envelope.code, ERROR_CODE.INTERNAL);
+  assert.equal(envelope.domain, 'tool');
+  assert.equal(envelope.tool, 'queue-control');
+  assert.equal(envelope.resolution_owner, 'agentsam');
+});

package/packages/agentsam-goap/README.md

@@ -0,0 +1,52 @@
+# @inneranimalmedia/agentsam-goap
+
+Portable GOAP control-plane contracts for AgentSam.
+
+This package does not define a second GOAP database. It maps stable logical ports onto tables AgentSam already owns.
+
+| Logical port | Existing authority |
+| --- | --- |
+| BlackboardStore | agentsam_workspace_state |
+| GoalStore | agentsam_tickets |
+| EventStore | agentsam_ticket_events |
+| PlanStore | agentsam_workflows, agentsam_workflow_nodes, agentsam_workflow_edges |
+| PlanRunStore | agentsam_workflow_runs |
+| ActionRunStore | agentsam_executions, agentsam_execution_steps |
+| ApprovalPort | agentsam_approval_queue |
+| QueuePort | @inneranimalmedia/agentsam-queue-control |
+| RuntimePort | agentsam.runtime.v1 / terminal runtime adapters |
+| EvidencePort | evidence snapshots and execution receipts |
+
+The core package imports no Wrangler, Cloudflare, SQLite, Postgres, Tauri, filesystem, or terminal implementation. Those are adapters.
+
+`projectGoapWorld()` is the deterministic perception seam: callers supply repository facts, the active project-local plan/TODO, knowledge freshness, and bounded evidence. It emits `agentsam.goap.world.v1` plus canonical blackboard, goal, and action contracts without performing storage, network, filesystem, or model work.
+
+## Frozen v1 contracts
+
+- agentsam.blackboard.v1
+- agentsam.goal.v1
+- agentsam.goap.action.v1
+- agentsam.goap.plan.v1
+- agentsam.goap.world.v1
+- agentsam.event.v1
+
+Database ticket statuses stay unchanged. The package maps them to logical goal states:
+
+- backlog -> proposed
+- active -> active
+- blocked -> blocked
+- in_review -> verifying
+- shipped -> satisfied
+- abandoned -> cancelled
+
+## Realtime and durability rule
+
+Blackboard mutation is compare-and-swap on a monotonically increasing revision. Events are append-only and expose opaque string cursors. The adapter owns the physical cursor prefix, so callers do not depend on SQLite/D1 rowid, Postgres sequences, or a future stream backend.
+
+Cross-store state changes must go through MutationPort. Goal activation updates blackboard revision, ticket status, and the activation event as one adapter-owned atomic operation. The D1/SQLite adapter therefore requires db.batch() for mutation operations.
+
+The Memory adapter is the conformance/reference adapter. The D1/SQLite adapter targets the common prepare/bind/first/all/run binding shape. Local SQLite supplies a transactional batch shim; Cloudflare D1 supplies batch natively.
+
+Portable ticket_events rows carry account_id and repository_id directly. The older platform host table does not. Set eventOwnership to ticket_join for that legacy shape; it scopes events through their owning ticket without requiring a second event table or a duplicate-column migration.
+
+Blackboard ownership is adapter-specific. Use blackboardOwnership=repository for account-owned portable/local stores. Shared hosts must verify repository ownership instead of trusting caller scope; IAM D1 uses blackboardOwnership=repository_join, which checks code_repositories.account_id on blackboard reads and CAS writes.

package/packages/agentsam-goap/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@inneranimalmedia/agentsam-goap",
+  "version": "2.6.9",
+  "description": "Portable AgentSam GOAP control-plane contracts and adapters over existing blackboard, ticket, workflow, execution, approval, queue, runtime, and evidence stores.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./contracts": "./src/contracts.js",
+    "./control-plane": "./src/control-plane.js",
+    "./adapters/memory": "./src/adapters/memory.js",
+    "./adapters/d1-sqlite": "./src/adapters/d1-sqlite.js",
+    "./world": "./src/world.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@inneranimalmedia/agentsam-errors": "2.6.9"
+  },
+  "engines": {
+    "node": ">=22 <25"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SamPrimeaux/agentsam-sdk.git",
+    "directory": "packages/agentsam-goap"
+  }
+}