@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/test/integration/sam-planning-astar.test.mjs

@@ -0,0 +1,279 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import {
+  planAStar,
+  planGoap,
+  ASTAR_ENGINE,
+  GOAP_ENGINE,
+  stableStateKey,
+} from '../../src/sam/planning/index.js';
+import {
+  brandGoapActions,
+  brandWorldFromPlan,
+  brandGoalFromPlan,
+} from '../../packages/agentsam-brand/src/index.js';
+
+describe('SAM A* planner', () => {
+  it('finds cheapest multi-step path over expensive direct edge', () => {
+    // Graph: start --1--> a --1--> goal  (cost 2)
+    //         start --10--> goal         (cost 10)
+    // Greedy-on-first-step with wrong heuristic could still pick expensive if we only looked local;
+    // A* with h=0 must pick the cheap two-step path.
+    const edges = {
+      start: [
+        { action: 'via_a', nextState: 'a', cost: 1 },
+        { action: 'direct', nextState: 'goal', cost: 10 },
+      ],
+      a: [{ action: 'finish', nextState: 'goal', cost: 1 }],
+      goal: [],
+    };
+
+    const result = planAStar({
+      initialState: 'start',
+      isGoal: (s) => s === 'goal',
+      expand: (s) => edges[s] || [],
+      stateKey: (s) => String(s),
+    });
+
+    assert.equal(result.status, 'found');
+    assert.equal(result.ok, true);
+    assert.equal(result.engine, ASTAR_ENGINE);
+    assert.equal(result.total_cost, 2);
+    assert.deepEqual(result.plan.map((p) => p.action), ['via_a', 'finish']);
+  });
+
+  it('does not get fooled by a cheap first action leading to an expensive future', () => {
+    // start --1--> trap --100--> goal
+    // start --5--> good --1--> goal
+    // Greedy "cheapest applicable" would take trap first (cost 1).
+    // Optimal is good path (cost 6).
+    const edges = {
+      start: [
+        { action: 'trap', nextState: 'trap', cost: 1 },
+        { action: 'good', nextState: 'good', cost: 5 },
+      ],
+      trap: [{ action: 'escape', nextState: 'goal', cost: 100 }],
+      good: [{ action: 'arrive', nextState: 'goal', cost: 1 }],
+      goal: [],
+    };
+
+    const greedy = (() => {
+      const sequence = [];
+      let state = 'start';
+      for (let i = 0; i < 10; i += 1) {
+        if (state === 'goal') break;
+        const candidates = (edges[state] || []).slice().sort((a, b) => a.cost - b.cost);
+        if (!candidates.length) break;
+        sequence.push(candidates[0].action);
+        state = candidates[0].nextState;
+      }
+      return sequence;
+    })();
+    assert.deepEqual(greedy, ['trap', 'escape'], 'sanity: greedy would pick trap');
+
+    const result = planAStar({
+      initialState: 'start',
+      isGoal: (s) => s === 'goal',
+      expand: (s) => edges[s] || [],
+      stateKey: (s) => String(s),
+    });
+
+    assert.equal(result.status, 'found');
+    assert.equal(result.total_cost, 6);
+    assert.deepEqual(result.plan.map((p) => p.action), ['good', 'arrive']);
+  });
+
+  it('terminates with cycles without looping forever', () => {
+    const edges = {
+      a: [
+        { action: 'loop', nextState: 'a', cost: 1 },
+        { action: 'to_b', nextState: 'b', cost: 2 },
+      ],
+      b: [{ action: 'to_goal', nextState: 'goal', cost: 1 }],
+      goal: [],
+    };
+    const result = planAStar({
+      initialState: 'a',
+      isGoal: (s) => s === 'goal',
+      expand: (s) => edges[s] || [],
+      stateKey: (s) => String(s),
+      maxExpansions: 100,
+    });
+    assert.equal(result.status, 'found');
+    assert.ok(result.expanded_states < 50);
+    assert.deepEqual(result.plan.map((p) => p.action), ['to_b', 'to_goal']);
+  });
+
+  it('replaces worse paths when a better g-score is found', () => {
+    // start --5--> mid --1--> goal  (total 6, discovered first via mid)
+    // start --1--> side --1--> mid  (reaches mid with g=2, should replace)
+    const edges = {
+      start: [
+        { action: 'long_to_mid', nextState: 'mid', cost: 5 },
+        { action: 'to_side', nextState: 'side', cost: 1 },
+      ],
+      side: [{ action: 'side_to_mid', nextState: 'mid', cost: 1 }],
+      mid: [{ action: 'mid_to_goal', nextState: 'goal', cost: 1 }],
+      goal: [],
+    };
+    const result = planAStar({
+      initialState: 'start',
+      isGoal: (s) => s === 'goal',
+      expand: (s) => edges[s] || [],
+      stateKey: (s) => String(s),
+    });
+    assert.equal(result.status, 'found');
+    assert.equal(result.total_cost, 3);
+    assert.deepEqual(result.plan.map((p) => p.action), ['to_side', 'side_to_mid', 'mid_to_goal']);
+  });
+
+  it('returns no_plan for unsatisfiable goals', () => {
+    const result = planAStar({
+      initialState: 'a',
+      isGoal: (s) => s === 'z',
+      expand: (s) => (s === 'a' ? [{ action: 'to_b', nextState: 'b', cost: 1 }] : []),
+      stateKey: (s) => String(s),
+    });
+    assert.equal(result.status, 'no_plan');
+    assert.equal(result.ok, false);
+    assert.deepEqual(result.plan, []);
+  });
+
+  it('returns budget_exhausted when maxExpansions is hit', () => {
+    const result = planAStar({
+      initialState: 0,
+      isGoal: (s) => s === 1000,
+      expand: (s) => [{ action: 'inc', nextState: Number(s) + 1, cost: 1 }],
+      stateKey: (s) => String(s),
+      maxExpansions: 3,
+    });
+    assert.equal(result.status, 'budget_exhausted');
+    assert.equal(result.ok, false);
+    assert.equal(result.expanded_states, 3);
+  });
+
+  it('returns cancelled when AbortSignal aborts', () => {
+    const controller = new AbortController();
+    controller.abort();
+    const result = planAStar({
+      initialState: 'a',
+      isGoal: () => false,
+      expand: () => [{ action: 'x', nextState: 'b', cost: 1 }],
+      signal: controller.signal,
+    });
+    assert.equal(result.status, 'cancelled');
+    assert.equal(result.ok, false);
+  });
+
+  it('tie-breaks deterministically', () => {
+    // Two equal-cost paths to goal; order of expansion must be stable across runs.
+    const edges = {
+      start: [
+        { action: 'b_first_listed', nextState: 'b', cost: 1 },
+        { action: 'a_second_listed', nextState: 'a', cost: 1 },
+      ],
+      a: [{ action: 'a_goal', nextState: 'goal', cost: 1 }],
+      b: [{ action: 'b_goal', nextState: 'goal', cost: 1 }],
+      goal: [],
+    };
+    const run = () => planAStar({
+      initialState: 'start',
+      isGoal: (s) => s === 'goal',
+      expand: (s) => edges[s] || [],
+      stateKey: (s) => String(s),
+    });
+    const first = run();
+    const second = run();
+    assert.equal(first.status, 'found');
+    assert.deepEqual(first.plan.map((p) => p.action), second.plan.map((p) => p.action));
+    assert.equal(first.total_cost, 2);
+  });
+
+  it('does not mutate input states during search', () => {
+    const initial = { x: 1 };
+    const frozen = JSON.stringify(initial);
+    planAStar({
+      initialState: initial,
+      isGoal: (s) => s.x === 3,
+      expand: (s) => [{ action: 'bump', nextState: { x: s.x + 1 }, cost: 1 }],
+      stateKey: stableStateKey,
+    });
+    assert.equal(JSON.stringify(initial), frozen);
+  });
+});
+
+describe('SAM GOAP adapter', () => {
+  it('plans with preconditions and effects', () => {
+    const actions = [
+      {
+        id: 'gather_wood',
+        cost: 2,
+        preconditions: { has_wood: false },
+        effects: { has_wood: true },
+      },
+      {
+        id: 'build_fire',
+        cost: 3,
+        preconditions: { has_wood: true, fire: false },
+        effects: { fire: true },
+      },
+      {
+        id: 'magic_fire',
+        cost: 50,
+        preconditions: { fire: false },
+        effects: { fire: true, has_wood: true },
+      },
+    ];
+    const result = planGoap({
+      initialState: { has_wood: false, fire: false },
+      goal: { fire: true },
+      actions,
+    });
+    assert.equal(result.status, 'found');
+    assert.equal(result.engine, GOAP_ENGINE);
+    assert.deepEqual(result.plan, ['gather_wood', 'build_fire']);
+    assert.equal(result.total_cost, 5);
+  });
+
+  it('does not mutate action catalog or world during search', () => {
+    const actions = [
+      {
+        id: 'step',
+        cost: 1,
+        preconditions: { done: false },
+        effects: { done: true },
+      },
+    ];
+    const world = { done: false };
+    const actionsSnap = JSON.stringify(actions);
+    const worldSnap = JSON.stringify(world);
+    planGoap({ initialState: world, goal: { done: true }, actions });
+    assert.equal(JSON.stringify(actions), actionsSnap);
+    assert.equal(JSON.stringify(world), worldSnap);
+  });
+
+  it('brand GOAP actions plan through A* engine', () => {
+    const plan = {
+      current_state: {
+        brand_scan_complete: true,
+        canonical_color_tokens: false,
+        duplicate_color_count: 8,
+        canonical_typography: false,
+        shared_button_component: false,
+        header_consistency: false,
+      },
+    };
+    const result = planGoap({
+      initialState: brandWorldFromPlan(plan),
+      goal: brandGoalFromPlan(plan),
+      actions: brandGoapActions(),
+    });
+    assert.equal(result.engine, GOAP_ENGINE);
+    assert.equal(result.status, 'found');
+    assert.ok(result.plan.includes('establish-color-token-map'));
+    assert.ok(result.plan.includes('verify-brand-surfaces'));
+    assert.ok(result.plan.includes('establish-type-roles'));
+    assert.ok(result.total_cost > 0);
+    assert.equal(result.final_state.brand_verified, true);
+  });
+});

package/test/integration/skill-runtime.test.mjs

@@ -0,0 +1,240 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import {
+  parseSlashInvocation,
+  canonicalizeSlashTrigger,
+  SkillRegistry,
+  SkillRuntime,
+  SkillContentResolver,
+  createFilesystemObjectStore,
+  createMemoryDatabaseContent,
+  createUserSkill,
+  installSkillFromPath,
+  aliasSkill,
+  computeSkillContentMetrics,
+} from '../../src/skills/index.js';
+
+function tmpHome() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'agentsam-skill-'));
+}
+
+test('prose never parses as slash invocation', () => {
+  assert.equal(parseSlashInvocation('Hello /deploy please'), null);
+  assert.equal(parseSlashInvocation('deploy this'), null);
+  assert.equal(parseSlashInvocation(''), null);
+});
+
+test('canonical slash parser lowercases and rejects underscores in match path via canonicalize', () => {
+  assert.deepEqual(parseSlashInvocation('/CodeBaseIndex .'), {
+    trigger: '/codebaseindex',
+    args: '.',
+  });
+  assert.deepEqual(parseSlashInvocation('/cad-export assembly.step'), {
+    trigger: '/cad-export',
+    args: 'assembly.step',
+  });
+  assert.equal(canonicalizeSlashTrigger('/Foo_Bar'), '/foo-bar');
+});
+
+test('local user skill resolves with zero cloud resources', async () => {
+  const home = tmpHome();
+  const created = createUserSkill('release-check', { home });
+  fs.writeFileSync(
+    path.join(created.root, 'SKILL.md'),
+    '# Release check\n\nVerify preview then production.\n',
+  );
+
+  const runtime = new SkillRuntime({
+    registry: new SkillRegistry({ home, builtins: false }),
+    contentResolver: new SkillContentResolver(),
+  });
+
+  const prose = await runtime.invoke({ input: 'please release check main' });
+  assert.equal(prose.matched, false);
+
+  const hit = await runtime.invoke({ input: '/release-check main' });
+  assert.equal(hit.matched, true);
+  assert.equal(hit.invocation.trigger, '/release-check');
+  assert.equal(hit.invocation.args, 'main');
+  assert.equal(hit.skill.id, 'release-check');
+  assert.equal(hit.interaction.status, 'ready');
+  assert.match(hit.modelInstructions.content, /Release check/);
+  assert.match(hit.receipt.checksum, /^sha256:/);
+  assert.equal(hit.receipt.contentSource, 'local_file');
+  assert.equal(hit.receipt.source, 'user');
+});
+
+test('slash collision requires alias resolution', () => {
+  const home = tmpHome();
+  const dirA = path.join(home, 'pkg-a');
+  const dirB = path.join(home, 'pkg-b');
+  fs.mkdirSync(dirA, { recursive: true });
+  fs.mkdirSync(dirB, { recursive: true });
+  for (const [dir, id] of [
+    [dirA, 'deploy-a'],
+    [dirB, 'deploy-b'],
+  ]) {
+    fs.writeFileSync(
+      path.join(dir, 'agentsam.skill.json'),
+      JSON.stringify({
+        schema: 'agentsam.skill.v1',
+        id,
+        name: id,
+        slash: { suggested: '/deploy' },
+        instructions: { source: 'inline', inline: `# ${id}` },
+        execution: { mode: 'turn', tools: [], operations: [] },
+      }),
+    );
+  }
+
+  installSkillFromPath(dirA, { home });
+  assert.throws(() => installSkillFromPath(dirB, { home }), (err) => err.code === 'SLASH_COLLISION');
+  const second = installSkillFromPath(dirB, { home, aliasOnCollision: '/deploy-b' });
+  assert.equal(second.trigger, '/deploy-b');
+
+  const registry = new SkillRegistry({ home, builtins: false });
+  assert.equal(registry.getByTrigger('/deploy')?.id, 'deploy-a');
+  assert.equal(registry.getByTrigger('/deploy-b')?.id, 'deploy-b');
+});
+
+test('unknown slash returns suggestions without model', async () => {
+  const home = tmpHome();
+  createUserSkill('deploy', { home });
+  createUserSkill('deploy-check', { home });
+  const runtime = new SkillRuntime({
+    registry: new SkillRegistry({ home, builtins: false }),
+  });
+  const miss = await runtime.invoke({ input: '/deply' });
+  assert.equal(miss.matched, true);
+  assert.equal(miss.interaction.status, 'blocked');
+  assert.equal(miss.interaction.prompt.code, 'SKILL_NOT_FOUND');
+  assert.match(miss.interaction.prompt.message, /Did you mean/);
+  assert.match(miss.interaction.prompt.message, /\/deploy/);
+});
+
+test('package_file and object_store adapters resolve without R2 coupling', async () => {
+  const home = tmpHome();
+  const pkg = path.join(home, 'pkg');
+  fs.mkdirSync(pkg, { recursive: true });
+  fs.writeFileSync(path.join(pkg, 'SKILL.md'), '# From package\n');
+  fs.writeFileSync(
+    path.join(pkg, 'agentsam.skill.json'),
+    JSON.stringify({
+      schema: 'agentsam.skill.v1',
+      id: 'pkg-skill',
+      name: 'Pkg',
+      slash: { suggested: '/pkg-skill' },
+      instructions: { source: 'package_file', ref: './SKILL.md' },
+      execution: { mode: 'turn' },
+    }),
+  );
+  installSkillFromPath(pkg, { home });
+
+  const storeRoot = path.join(home, 'objects');
+  fs.mkdirSync(storeRoot, { recursive: true });
+  fs.writeFileSync(path.join(storeRoot, 'remote.md'), '# From object store\n');
+
+  const resolver = new SkillContentResolver({
+    objectStore: createFilesystemObjectStore(storeRoot),
+    database: createMemoryDatabaseContent(new Map([['db:1', '# From database\n']])),
+  });
+
+  const runtime = new SkillRuntime({
+    registry: new SkillRegistry({ home, builtins: false }),
+    contentResolver: resolver,
+  });
+  const pkgHit = await runtime.invoke({ input: '/pkg-skill' });
+  assert.match(pkgHit.modelInstructions.content, /From package/);
+
+  const objectManifest = {
+    schema: 'agentsam.skill.v1',
+    id: 'obj-skill',
+    name: 'Obj',
+    instructions: { source: 'object_store', ref: 'remote.md' },
+    execution: { mode: 'turn' },
+  };
+  const obj = await resolver.resolve(objectManifest);
+  assert.match(obj.content, /object store/);
+
+  const db = await resolver.resolve({
+    schema: 'agentsam.skill.v1',
+    id: 'db-skill',
+    name: 'Db',
+    instructions: { source: 'database', ref: 'db:1' },
+    execution: { mode: 'turn' },
+  });
+  assert.match(db.content, /database/);
+});
+
+test('tool requirements block without subagent lookup', async () => {
+  const home = tmpHome();
+  const dir = path.join(home, 'toolish');
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, 'agentsam.skill.json'),
+    JSON.stringify({
+      schema: 'agentsam.skill.v1',
+      id: 'needs-tools',
+      name: 'Needs tools',
+      slash: { suggested: '/needs-tools' },
+      instructions: { source: 'inline', inline: '# Need tools' },
+      execution: {
+        mode: 'turn',
+        tools: ['repository.inspect', 'missing.tool'],
+        operations: ['codebaseindex.ingest'],
+      },
+    }),
+  );
+  installSkillFromPath(dir, { home });
+
+  const runtime = new SkillRuntime({
+    registry: new SkillRegistry({ home, builtins: false }),
+    toolRegistry: { has: (id) => id === 'repository.inspect' },
+  });
+  const result = await runtime.invoke({ input: '/needs-tools' });
+  assert.equal(result.interaction.status, 'blocked');
+  assert.equal(result.interaction.prompt.code, 'TOOL_REQUIRED');
+  assert.match(result.interaction.prompt.message, /missing\.tool/);
+});
+
+test('alias remaps trigger; metrics from resolved content', () => {
+  const home = tmpHome();
+  createUserSkill('brand-scan', { home });
+  aliasSkill('brand-scan', '/brand', { home });
+  const registry = new SkillRegistry({ home, builtins: false });
+  assert.equal(registry.getByTrigger('/brand')?.id, 'brand-scan');
+  const metrics = computeSkillContentMetrics('# hi\n\nworld');
+  assert.ok(metrics.byte_size > 0);
+  assert.ok(metrics.estimated_tokens > 0);
+  assert.match(metrics.checksum, /^sha256:/);
+});
+
+test('/skills lists vocabulary', async () => {
+  const home = tmpHome();
+  createUserSkill('one', { home });
+  const runtime = new SkillRuntime({
+    registry: new SkillRegistry({ home, builtins: false }),
+  });
+  const result = await runtime.invoke({ input: '/skills' });
+  assert.equal(result.matched, true);
+  assert.equal(result.interaction.status, 'complete');
+  assert.match(result.interaction.prompt.message, /\/one/);
+});
+
+test('/skills empty registry offers create path not a circular list tip', async () => {
+  const home = tmpHome();
+  const runtime = new SkillRuntime({
+    registry: new SkillRegistry({ home, builtins: false }),
+  });
+  const empty = await runtime.invoke({ input: '/skills' });
+  assert.equal(empty.interaction.status, 'needs_input');
+  assert.equal(empty.interaction.prompt.code, 'NO_SKILLS');
+  assert.match(empty.interaction.prompt.message, /agentsam skill create/);
+  assert.doesNotMatch(empty.interaction.prompt.message, /agentsam skill list/);
+
+  const hinted = await runtime.invoke({ input: '/skills release-check' });
+  assert.match(hinted.interaction.prompt.message, /skill create release-check/);
+});