@inneranimalmedia/agentsam-sdk 2.6.7 → 2.6.9

package/packages/agentsam-goap/src/adapters/memory.js

@@ -0,0 +1,199 @@
+import {
+  goalStatusFromTicket,
+  normalizeBlackboard,
+  normalizeEvent,
+  normalizeGoal,
+  normalizeGoapScope,
+} from '../contracts.js';
+import {
+  goapStaleVersion,
+  goapTargetNotFound,
+} from '../errors.js';
+
+function clone(value) {
+  return value == null ? value : structuredClone(value);
+}
+
+function scopeKey(scopeInput) {
+  const scope = normalizeGoapScope(scopeInput);
+  return [scope.account_id, scope.repository_id, scope.workspace_id || 'default'].join('::');
+}
+
+function goalKey(scopeInput, id) {
+  const scope = normalizeGoapScope(scopeInput);
+  return [scope.account_id, scope.repository_id, id].join('::');
+}
+
+export class MemoryGoapAdapter {
+  constructor({ blackboards = [], goals = [], events = [] } = {}) {
+    this.blackboards = new Map();
+    this.goals = new Map();
+    this.events = new Map();
+    this.sequence = 0;
+
+    for (const row of blackboards) this.seedBlackboard(row);
+    for (const row of goals) this.seedGoal(row);
+    for (const row of events) this.seedEvent(row);
+  }
+
+  seedBlackboard(row) {
+    const normalized = normalizeBlackboard(row);
+    const scope = {
+      account_id: normalized.account_id,
+      repository_id: normalized.repository_id,
+      workspace_id: normalized.workspace_id,
+    };
+    this.blackboards.set(scopeKey(scope), normalized);
+    return clone(normalized);
+  }
+
+  seedGoal(row) {
+    const normalized = normalizeGoal(row);
+    this.goals.set(goalKey(normalized, normalized.id), normalized);
+    return clone(normalized);
+  }
+
+  seedEvent(row) {
+    const scope = normalizeGoapScope(row);
+    const key = scopeKey(scope);
+    const normalized = normalizeEvent(row.event ?? row);
+    this.sequence += 1;
+    normalized.cursor = 'memory:' + this.sequence;
+    if (!this.events.has(key)) this.events.set(key, []);
+    this.events.get(key).push(normalized);
+    return clone(normalized);
+  }
+
+  ports() {
+    const adapter = this;
+    return {
+      blackboardStore: {
+        get: async (scope) => clone(adapter.blackboards.get(scopeKey(scope)) ?? null),
+        compareAndSwap: async ({ scope, expectedRevision, patch = {} }) => {
+          const key = scopeKey(scope);
+          const current = adapter.blackboards.get(key);
+          if (!current) {
+            throw goapTargetNotFound('blackboard', key, {
+              stage: 'compare_and_swap',
+            });
+          }
+          if (current.revision !== expectedRevision) {
+            throw goapStaleVersion({
+              expectedRevision,
+              actualRevision: current.revision,
+              blackboardId: current.id,
+            });
+          }
+          const next = normalizeBlackboard({
+            ...current,
+            ...patch,
+            current_goal_id: Object.hasOwn(patch, 'current_goal_id')
+              ? patch.current_goal_id
+              : current.current_goal_id,
+            state: patch.state ?? current.state,
+            revision: current.revision + 1,
+          });
+          adapter.blackboards.set(key, next);
+          return clone(next);
+        },
+      },
+      goalStore: {
+        get: async ({ id, ...scope }) => clone(adapter.goals.get(goalKey(scope, id)) ?? null),
+        updateStatus: async ({ id, status, updated_at, ...scope }) => {
+          const key = goalKey(scope, id);
+          const current = adapter.goals.get(key);
+          if (!current) {
+            throw goapTargetNotFound('goal', id, {
+              stage: 'update_goal_status',
+            });
+          }
+          const next = {
+            ...current,
+            status: goalStatusFromTicket(status),
+            updated_at: updated_at ?? current.updated_at,
+          };
+          adapter.goals.set(key, next);
+          return clone(next);
+        },
+      },
+      eventStore: {
+        append: async ({ scope, event }) => {
+          const key = scopeKey(scope);
+          const normalized = normalizeEvent(event);
+          adapter.sequence += 1;
+          normalized.cursor = 'memory:' + adapter.sequence;
+          if (!adapter.events.has(key)) adapter.events.set(key, []);
+          adapter.events.get(key).push(normalized);
+          return clone(normalized);
+        },
+        list: async ({ cursor = null, limit = 50, goal_id = null, ...scope }) => {
+          const rows = adapter.events.get(scopeKey(scope)) ?? [];
+          const after = cursor ? Number(String(cursor).split(':').at(-1)) || 0 : 0;
+          return rows
+            .filter((row) => {
+              const seq = Number(String(row.cursor).split(':').at(-1)) || 0;
+              if (seq <= after) return false;
+              return !goal_id || row.goal_id === goal_id;
+            })
+            .slice(0, Math.max(0, Number(limit) || 50))
+            .map(clone);
+        },
+      },
+      mutationPort: {
+        activateGoal: async ({ scope, goal_id, expected_revision, event, updated_at }) => {
+          const bbKey = scopeKey(scope);
+          const gKey = goalKey(scope, goal_id);
+          const currentBlackboard = adapter.blackboards.get(bbKey);
+          const currentGoal = adapter.goals.get(gKey);
+
+          if (!currentBlackboard) {
+            throw goapTargetNotFound('blackboard', bbKey, {
+              stage: 'activate_goal',
+            });
+          }
+          if (!currentGoal) {
+            throw goapTargetNotFound('goal', goal_id, {
+              stage: 'activate_goal',
+            });
+          }
+          if (currentBlackboard.revision !== expected_revision) {
+            throw goapStaleVersion({
+              expectedRevision: expected_revision,
+              actualRevision: currentBlackboard.revision,
+              blackboardId: currentBlackboard.id,
+              stage: 'activate_goal',
+              action: 'activate_goal',
+            });
+          }
+
+          const nextBlackboard = normalizeBlackboard({
+            ...currentBlackboard,
+            current_goal_id: goal_id,
+            last_action: 'activated_goal',
+            updated_at,
+            revision: currentBlackboard.revision + 1,
+          });
+          const nextGoal = {
+            ...currentGoal,
+            status: 'active',
+            updated_at,
+          };
+          const normalizedEvent = normalizeEvent(event);
+          adapter.sequence += 1;
+          normalizedEvent.cursor = 'memory:' + adapter.sequence;
+
+          adapter.blackboards.set(bbKey, nextBlackboard);
+          adapter.goals.set(gKey, nextGoal);
+          if (!adapter.events.has(bbKey)) adapter.events.set(bbKey, []);
+          adapter.events.get(bbKey).push(normalizedEvent);
+
+          return {
+            blackboard: clone(nextBlackboard),
+            goal: clone(nextGoal),
+            event: clone(normalizedEvent),
+          };
+        },
+      },
+    };
+  }
+}

package/packages/agentsam-goap/src/contracts.js

@@ -0,0 +1,226 @@
+import {
+  goapAdapterError,
+  goapInputError,
+} from './errors.js';
+
+export const GOAP_SCHEMAS = Object.freeze({
+  blackboard: 'agentsam.blackboard.v1',
+  goal: 'agentsam.goal.v1',
+  action: 'agentsam.goap.action.v1',
+  plan: 'agentsam.goap.plan.v1',
+  world: 'agentsam.goap.world.v1',
+  event: 'agentsam.event.v1',
+});
+
+export const GOAL_STATUSES = Object.freeze([
+  'proposed',
+  'active',
+  'blocked',
+  'verifying',
+  'satisfied',
+  'cancelled',
+]);
+
+export const TICKET_TO_GOAL_STATUS = Object.freeze({
+  backlog: 'proposed',
+  active: 'active',
+  blocked: 'blocked',
+  in_review: 'verifying',
+  shipped: 'satisfied',
+  abandoned: 'cancelled',
+});
+
+export const GOAL_TO_TICKET_STATUS = Object.freeze(
+  Object.fromEntries(Object.entries(TICKET_TO_GOAL_STATUS).map(([ticket, goal]) => [goal, ticket])),
+);
+
+export const GOAP_PORT_METHODS = Object.freeze({
+  blackboardStore: ['get', 'compareAndSwap'],
+  goalStore: ['get', 'updateStatus'],
+  eventStore: ['append', 'list'],
+  mutationPort: ['activateGoal'],
+  planStore: ['get'],
+  planRunStore: ['get', 'heartbeat'],
+  actionRunStore: ['get', 'record'],
+  approvalPort: ['request', 'get'],
+  queuePort: ['dispatch'],
+  runtimePort: ['execute'],
+  evidencePort: ['attach'],
+});
+
+function clean(value) {
+  return value == null ? '' : String(value).trim();
+}
+
+function objectOrEmpty(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function normalizeGoapScope(input = {}) {
+  const accountId = clean(input.account_id ?? input.accountId);
+  const repositoryId = clean(input.repository_id ?? input.repositoryId);
+  const workspaceId = clean(input.workspace_id ?? input.workspaceId) || null;
+
+  if (!accountId) {
+    throw goapInputError('scope.account_id is required', {
+      stage: 'normalize_scope',
+      details: { field: 'account_id' },
+    });
+  }
+  if (!repositoryId) {
+    throw goapInputError('scope.repository_id is required', {
+      stage: 'normalize_scope',
+      details: { field: 'repository_id' },
+    });
+  }
+
+  return {
+    account_id: accountId,
+    repository_id: repositoryId,
+    workspace_id: workspaceId,
+  };
+}
+
+export function goalStatusFromTicket(status) {
+  const mapped = TICKET_TO_GOAL_STATUS[clean(status)];
+  if (!mapped) {
+    throw goapInputError('Unsupported ticket status: ' + status, {
+      stage: 'map_status',
+      details: { status },
+    });
+  }
+  return mapped;
+}
+
+export function ticketStatusFromGoal(status) {
+  const mapped = GOAL_TO_TICKET_STATUS[clean(status)];
+  if (!mapped) {
+    throw goapInputError('Unsupported GOAP goal status: ' + status, {
+      stage: 'map_status',
+      details: { status },
+    });
+  }
+  return mapped;
+}
+
+export function normalizeGoalSpec(input = {}) {
+  const source = objectOrEmpty(input);
+  const desired = Array.isArray(source.desired)
+    ? source.desired.map((fact) => ({ ...objectOrEmpty(fact) }))
+    : [];
+
+  return {
+    schema: GOAP_SCHEMAS.goal,
+    desired,
+    constraints: Array.isArray(source.constraints)
+      ? source.constraints.map((constraint) => ({ ...objectOrEmpty(constraint) }))
+      : [],
+    metadata: { ...objectOrEmpty(source.metadata) },
+  };
+}
+
+export function normalizeActionSpec(input = {}) {
+  const source = objectOrEmpty(input);
+  return {
+    schema: GOAP_SCHEMAS.action,
+    preconditions: Array.isArray(source.preconditions)
+      ? source.preconditions.map((fact) => ({ ...objectOrEmpty(fact) }))
+      : [],
+    effects: Array.isArray(source.effects)
+      ? source.effects.map((fact) => ({ ...objectOrEmpty(fact) }))
+      : [],
+    cost: Number.isFinite(Number(source.cost)) ? Number(source.cost) : 1,
+    metadata: { ...objectOrEmpty(source.metadata) },
+  };
+}
+
+export function normalizeBlackboard(input = {}) {
+  const revision = Number(input.revision ?? 1);
+  return {
+    schema: GOAP_SCHEMAS.blackboard,
+    id: clean(input.id) || null,
+    account_id: clean(input.account_id ?? input.accountId) || null,
+    repository_id: clean(input.repository_id ?? input.repositoryId) || null,
+    workspace_id: clean(input.workspace_id ?? input.workspaceId) || null,
+    current_goal_id: clean(input.current_goal_id ?? input.currentGoalId ?? input.current_task_id) || null,
+    state: { ...objectOrEmpty(input.state ?? input.state_json) },
+    revision: Number.isInteger(revision) && revision > 0 ? revision : 1,
+    locked_by: clean(input.locked_by ?? input.lockedBy) || null,
+    lock_expires_at: input.lock_expires_at ?? input.lockExpiresAt ?? null,
+    checkpoint_sha: clean(input.checkpoint_sha ?? input.checkpointSha) || null,
+    last_action: clean(input.last_action ?? input.lastAction ?? input.last_agent_action) || null,
+    updated_at: input.updated_at ?? input.updatedAt ?? null,
+  };
+}
+
+export function normalizeGoal(input = {}) {
+  const status = input.goal_status
+    ? clean(input.goal_status)
+    : goalStatusFromTicket(input.status ?? 'backlog');
+
+  if (!GOAL_STATUSES.includes(status)) {
+    throw goapInputError('Unsupported GOAP goal status: ' + status, {
+      stage: 'normalize_goal',
+      details: { status },
+    });
+  }
+
+  return {
+    schema: GOAP_SCHEMAS.goal,
+    id: clean(input.id),
+    account_id: clean(input.account_id ?? input.accountId),
+    repository_id: clean(input.repository_id ?? input.repositoryId),
+    title: clean(input.title),
+    status,
+    priority: clean(input.priority) || null,
+    spec: normalizeGoalSpec(input.spec ?? input.goal_spec_json ?? {}),
+    created_at: input.created_at ?? input.createdAt ?? null,
+    updated_at: input.updated_at ?? input.updatedAt ?? null,
+  };
+}
+
+export function normalizeEvent(input = {}) {
+  const type = clean(input.type ?? input.event_type);
+  if (!type) {
+    throw goapInputError('event.type is required', {
+      stage: 'normalize_event',
+      details: { field: 'type' },
+    });
+  }
+
+  return {
+    schema: GOAP_SCHEMAS.event,
+    id: clean(input.id) || null,
+    goal_id: clean(input.goal_id ?? input.goalId ?? input.ticket_id) || null,
+    type,
+    payload: { ...objectOrEmpty(input.payload ?? input.payload_json) },
+    actor_type: clean(input.actor_type ?? input.actorType) || null,
+    actor_id: clean(input.actor_id ?? input.actorId) || null,
+    workflow_run_id: clean(input.workflow_run_id ?? input.workflowRunId) || null,
+    execution_step_id: clean(input.execution_step_id ?? input.executionStepId) || null,
+    created_at: input.created_at ?? input.createdAt ?? null,
+    cursor: clean(input.cursor) || null,
+  };
+}
+
+export function assertGoapPorts(ports = {}, required = ['blackboardStore', 'goalStore', 'eventStore']) {
+  for (const portName of required) {
+    const port = ports[portName];
+    if (!port || typeof port !== 'object') {
+      throw goapAdapterError(portName + ' is required', {
+        stage: 'validate_ports',
+        adapter: portName,
+      });
+    }
+    for (const method of GOAP_PORT_METHODS[portName] || []) {
+      if (typeof port[method] !== 'function') {
+        throw goapAdapterError(portName + '.' + method + ' must be a function', {
+          stage: 'validate_ports',
+          adapter: portName,
+          details: { method },
+        });
+      }
+    }
+  }
+  return ports;
+}

package/packages/agentsam-goap/src/control-plane.js

@@ -0,0 +1,112 @@
+import {
+  GOAP_SCHEMAS,
+  assertGoapPorts,
+  normalizeEvent,
+  normalizeGoapScope,
+} from './contracts.js';
+import {
+  goapAdapterError,
+  goapInputError,
+} from './errors.js';
+
+function defaultId(prefix) {
+  return prefix + '_' + crypto.randomUUID().replaceAll('-', '');
+}
+
+export function createGoapControlPlane({
+  ports,
+  clock = () => Math.floor(Date.now() / 1000),
+  idFactory = defaultId,
+} = {}) {
+  assertGoapPorts(ports);
+
+  async function snapshot(scopeInput, { eventCursor = null, eventLimit = 50 } = {}) {
+    const scope = normalizeGoapScope(scopeInput);
+    const blackboard = await ports.blackboardStore.get(scope);
+    const goal = blackboard?.current_goal_id
+      ? await ports.goalStore.get({ ...scope, id: blackboard.current_goal_id })
+      : null;
+    const events = await ports.eventStore.list({
+      ...scope,
+      goal_id: blackboard?.current_goal_id ?? null,
+      cursor: eventCursor,
+      limit: eventLimit,
+    });
+
+    return {
+      schema: 'agentsam.goap.snapshot.v1',
+      scope,
+      blackboard,
+      goal,
+      events,
+    };
+  }
+
+  async function activateGoal({
+    scope: scopeInput,
+    goalId,
+    expectedRevision,
+    actor = {},
+    payload = {},
+  } = {}) {
+    const scope = normalizeGoapScope(scopeInput);
+    if (!goalId) {
+      throw goapInputError('goalId is required', {
+        stage: 'activate_goal',
+        details: { field: 'goalId' },
+      });
+    }
+    if (!Number.isInteger(expectedRevision) || expectedRevision < 1) {
+      throw goapInputError('expectedRevision must be a positive integer', {
+        stage: 'activate_goal',
+        details: { field: 'expectedRevision', value: expectedRevision ?? null },
+      });
+    }
+    if (typeof ports.mutationPort?.activateGoal !== 'function') {
+      throw goapAdapterError('mutationPort.activateGoal is required for durable goal activation', {
+        stage: 'activate_goal',
+        adapter: 'mutationPort',
+      });
+    }
+
+    const event = normalizeEvent({
+      id: idFactory('gevt'),
+      goal_id: goalId,
+      type: 'goal.activated',
+      payload: {
+        schema: GOAP_SCHEMAS.event,
+        ...payload,
+        blackboard_revision: expectedRevision + 1,
+      },
+      actor_type: actor.type ?? null,
+      actor_id: actor.id ?? null,
+      created_at: clock(),
+    });
+
+    await ports.mutationPort.activateGoal({
+      scope,
+      goal_id: goalId,
+      expected_revision: expectedRevision,
+      event,
+      updated_at: clock(),
+    });
+
+    return snapshot(scope);
+  }
+
+  async function appendEvent({ scope: scopeInput, event } = {}) {
+    const scope = normalizeGoapScope(scopeInput);
+    const normalized = normalizeEvent({
+      ...event,
+      id: event?.id || idFactory('gevt'),
+      created_at: event?.created_at ?? clock(),
+    });
+    return ports.eventStore.append({ scope, event: normalized });
+  }
+
+  return Object.freeze({
+    snapshot,
+    activateGoal,
+    appendEvent,
+  });
+}

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

@@ -0,0 +1,157 @@
+import {
+  AgentSamError,
+  ERROR_REASON,
+  createToolError,
+} from '@inneranimalmedia/agentsam-errors';
+
+const TOOL = 'goap';
+
+function resource(type, id = null, name = null) {
+  return { type, id, name };
+}
+
+export function goapInputError(message, {
+  stage = 'validate',
+  resource: target = null,
+  details = null,
+} = {}) {
+  return createToolError({
+    reason: ERROR_REASON.INPUT_INVALID,
+    message,
+    tool: TOOL,
+    stage,
+    resource: target,
+    details,
+    operation: {
+      kind: 'goap',
+      action: stage,
+      resource_type: target?.type || null,
+      resource_id: target?.id || null,
+      read_only: true,
+      idempotent: true,
+      side_effect_state: 'none',
+    },
+  });
+}
+
+export function goapTargetNotFound(type, id, {
+  stage = 'resolve',
+  message = null,
+  details = null,
+} = {}) {
+  return createToolError({
+    reason: ERROR_REASON.TARGET_NOT_FOUND,
+    message: message || `${type} was not found.`,
+    tool: TOOL,
+    stage,
+    resource: resource(type, id),
+    details,
+    operation: {
+      kind: 'goap',
+      action: stage,
+      resource_type: type,
+      resource_id: id,
+      read_only: true,
+      idempotent: true,
+      side_effect_state: 'none',
+    },
+  });
+}
+
+export function goapStaleVersion({
+  expectedRevision,
+  actualRevision,
+  blackboardId = null,
+  stage = 'compare_and_swap',
+  action = 'update_blackboard',
+} = {}) {
+  return createToolError({
+    reason: ERROR_REASON.STALE_VERSION,
+    message: 'GOAP state changed before this mutation could commit.',
+    tool: TOOL,
+    stage,
+    failure_class: 'conflict',
+    resource: resource('blackboard', blackboardId),
+    details: {
+      expected_revision: expectedRevision ?? null,
+      actual_revision: actualRevision ?? null,
+    },
+    operation: {
+      kind: 'mutation',
+      action,
+      resource_type: 'blackboard',
+      resource_id: blackboardId,
+      read_only: false,
+      idempotent: true,
+      side_effect_state: 'confirmed_not_applied',
+    },
+  });
+}
+
+export function goapAdapterError(message, {
+  stage = 'adapter',
+  adapter = null,
+  details = null,
+  cause = null,
+} = {}) {
+  return createToolError({
+    reason: ERROR_REASON.INTERNAL_ADAPTER_FAILED,
+    message,
+    tool: TOOL,
+    stage,
+    resource: resource('adapter', adapter),
+    details,
+  }, cause ? { cause } : {});
+}
+
+export function goapInvariantError(message, {
+  stage = 'execute',
+  resource: target = null,
+  details = null,
+  sideEffectState = 'unknown',
+} = {}) {
+  return createToolError({
+    reason: ERROR_REASON.INTERNAL_INVARIANT_VIOLATION,
+    message,
+    tool: TOOL,
+    stage,
+    resource: target,
+    details,
+    operation: {
+      kind: 'goap',
+      action: stage,
+      resource_type: target?.type || null,
+      resource_id: target?.id || null,
+      read_only: false,
+      idempotent: false,
+      side_effect_state: sideEffectState,
+    },
+  });
+}
+
+export function goapPersistenceError(cause, {
+  stage = 'persistence',
+  resource: target = null,
+  details = null,
+  operation = null,
+} = {}) {
+  if (cause instanceof AgentSamError) return cause;
+
+  return createToolError({
+    reason: ERROR_REASON.PERSISTENCE_FAILED,
+    message: 'GOAP persistence operation failed.',
+    tool: TOOL,
+    stage,
+    resource: target,
+    details,
+    operation: operation || {
+      kind: 'persistence',
+      action: stage,
+      resource_type: target?.type || null,
+      resource_id: target?.id || null,
+      read_only: false,
+      idempotent: false,
+      side_effect_state: 'unknown',
+    },
+  }, { cause });
+}

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

@@ -0,0 +1,5 @@
+export * from './contracts.js';
+export * from './control-plane.js';
+export * from './adapters/memory.js';
+export * from './adapters/d1-sqlite.js';
+export * from './world.js';