@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.8

package/src/commands/autorag.js

@@ -2,10 +2,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
-import { repositoryRoot, readConfig, validateConfig, CONFIG_PATH } from '../knowledge/config.js';
+import { repositoryRoot, readConfig, validateConfig, defaultConfig, scopeKey, CONFIG_PATH } from '../knowledge/config.js';
 import { openSqliteStore } from '../knowledge/stores/sqlite.js';
 import { openPostgresStore } from '../knowledge/stores/postgres.js';
 import { planIndex, runIndex, retrieve } from '../knowledge/engine.js';
+import { discoverKnowledgeRuntime } from '../knowledge/runtime-discovery.js';
+import { getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
 import { discoverAutoRag, recommendAutoRag, safeAutoRagConfig, runAutoRagProbe, createProviderRegistry, createBackendRegistry } from '../../packages/agentsam-knowledge/src/index.js';
 
 const show = value => console.log(JSON.stringify(value, null, 2));
@@ -16,6 +18,12 @@ const parse = argv => parseArgs({ args: argv, allowPositionals: true, options: {
   kind: { type: 'string' }, scope: { type: 'string' }, provider: { type: 'string' }, backend: { type: 'string' }, model: { type: 'string' }, dimensions: { type: 'string' }, semantic: { type: 'boolean' }, 'allow-paid': { type: 'boolean' }, query: { type: 'string' },
 } });
 function readExisting(root) { try { return readConfig(root); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } }
+function generationConfig(root, existing) {
+  if (existing) return existing;
+  const project = tryReadProjectConfig(root);
+  const repositoryId = getRepositoryId(project) || portableRepositoryIdFromGit(root);
+  return repositoryId ? defaultConfig({ repositoryId }) : null;
+}
 function writeConfig(root, config) {
   const filename = path.join(root, CONFIG_PATH); fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
   const safe = JSON.stringify(validateConfig(config), null, 2) + '\n';
@@ -28,10 +36,20 @@ function adapterFor(config) {
   return { validate: profile => adapter.validate(profile), async embed(text, profile, context) { return context?.kind === 'query' ? adapter.embedQuery(text, profile, context) : (await adapter.embedDocuments([text], profile, context))[0]; } };
 }
 async function storeFor(root, config, readOnly = false) { return config.storage.driver === 'sqlite' ? openSqliteStore(localPath(root), { readOnly }) : openPostgresStore(process.env[config.storage.connection_env]); }
-function defaults(discovery, opts, existing) {
+function defaults(discovery, opts, existing, runtime) {
   const purpose = opts.kind || existing?.scope?.name || 'code';
-  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend: opts.backend || existing?.lane?.backend || 'local_exact', semantic: Boolean(opts.semantic) });
+  const declaredVectorize = (runtime?.cloudflare?.vectorize || []).filter(row => row.binding && row.index);
+  const adoptVectorize = !opts.backend && !existing?.lane?.backend && declaredVectorize.length === 1;
+  const backend = opts.backend || existing?.lane?.backend || (adoptVectorize ? 'cloudflare_vectorize' : 'local_exact');
+  const recommendation = recommendAutoRag({ discovery, purpose, include: opts.scope ? split(opts.scope) : existing?.scope?.include, provider: opts.provider || 'none', backend, semantic: Boolean(opts.semantic) });
   const config = safeAutoRagConfig({ existing: existing || {}, recommendation, repositoryId: existing?.repository_id || discovery.repository.identity, projectKey: existing?.project_key || discovery.repository.identity });
+  if (adoptVectorize) {
+    const resource = declaredVectorize[0];
+    config.lane.id = `${purpose}-cloudflare-vectorize`;
+    config.lane.backend = 'cloudflare_vectorize';
+    config.lane.binding = resource.binding;
+    config.lane.index = resource.index;
+  }
   if (opts.provider) {
     const models = { fixture: 'deterministic', gemini: 'gemini-embedding-2', openai: 'text-embedding-3-small', 'workers-ai': '@cf/baai/bge-base-en-v1.5', ollama: 'nomic-embed-text' };
     config.embedding = opts.provider === 'none' ? { provider: 'none', model: 'none', revision: '1', dimensions: 0, parameters: {} } : { provider: opts.provider, model: opts.model || models[opts.provider] || '', revision: '1', dimensions: Number(opts.dimensions || (opts.provider === 'fixture' ? 3 : 768)), parameters: { task: 'code retrieval' } };
@@ -43,7 +61,7 @@ async function interactiveOptions(discovery, opts) {
   const prompt = createInterface({ input: process.stdin, output: process.stdout });
   try {
     const kind = opts.kind || await prompt.question('What kind of knowledge? code, documents, schema, media, memory, mixed [code]: ') || 'code';
-    const suggested = kind === 'code' ? discovery.scopes.filter(scope => ['packages', 'src'].includes(scope)).join(',') : discovery.scopes.filter(scope => /docs|README|schema|migrations/.test(scope)).join(',');
+    const suggested = recommendAutoRag({ discovery, purpose: kind }).scope.join(',');
     const scope = opts.scope || await prompt.question(`Sources (literal paths, comma separated) [${suggested || '.'}]: `) || suggested || '.';
     const semantic = opts.semantic || (await prompt.question('Enable semantic embeddings for this setup? [no]: ')).toLowerCase() === 'yes';
     const provider = opts.provider || (semantic ? await prompt.question('Provider: fixture, gemini, openai, workers-ai, ollama [fixture]: ') || 'fixture' : 'none');
@@ -55,18 +73,54 @@ export async function runAutoRag(argv) {
   if (opts.help || !['setup', 'status', 'doctor', 'lanes', 'configure', 'probe', 'providers', 'backends', 'scope'].includes(command)) {
     console.log('agentsam autorag setup|status|doctor|lanes|configure|probe|providers|backends|scope [--cwd PATH] [--yes] [--kind code|documents|schema|media|memory|mixed] [--scope a,b] [--provider none|fixture|gemini|openai|workers-ai|ollama] [--backend local_exact|postgres_pgvector|supabase_pgvector|cloudflare_vectorize] [--semantic]'); return;
   }
-  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root);
-  if (command === 'providers') return show(await createProviderRegistry().capabilities());
-  if (command === 'backends') return show(createBackendRegistry().capabilities());
-  if (command === 'status') return show({ discovery, config: existing || null, generation: existing ? await (async () => { const store = await storeFor(root, existing, true); try { return await store?.active((await import('../knowledge/config.js')).scopeKey(existing)); } finally { await store?.close(); } })() : null });
+  const root = repositoryRoot(opts.cwd); const discovery = await discoverAutoRag({ root }); const existing = readExisting(root); const runtime = discoverKnowledgeRuntime(root, { knowledgeConfig: existing });
+  if (command === 'providers') {
+    const providers = await createProviderRegistry().capabilities();
+    const workersAi = runtime.resources.workers_ai;
+    return show(providers.map(item => item.id === 'workers-ai'
+      ? { ...item, runtime_configured: workersAi.configured, runtime_binding: workersAi.binding, locally_executable: workersAi.locally_executable, remotely_executable: workersAi.remotely_executable, credential_state: workersAi.credential_state }
+      : item));
+  }
+  if (command === 'backends') {
+    const backends = createBackendRegistry().capabilities();
+    const vectorize = runtime.resources.vectorize;
+    return show(backends.map(item => item.id === 'cloudflare_vectorize'
+      ? { ...item, declared_resources: vectorize, locally_executable: vectorize.some(row => row.locally_executable), remotely_executable: vectorize.some(row => row.remotely_executable), conflicts: runtime.conflicts }
+      : item));
+  }
+  if (command === 'status') {
+    const generationProfile = runtime.local_index.exists ? generationConfig(root, existing) : null;
+    const generation = generationProfile ? await (async () => {
+      const store = await storeFor(root, generationProfile, true);
+      try { return await store?.active(scopeKey(generationProfile)); }
+      finally { await store?.close(); }
+    })() : null;
+    return show({ discovery, config: existing || null, project_context: runtime, runtime, generation });
+  }
   if (command === 'doctor') {
-    const checks = [{ check: 'knowledge_config', ok: Boolean(existing), detail: existing ? CONFIG_PATH : 'Run agentsam autorag setup.' }, { check: 'local_sqlite', ok: true }, { check: 'git_merkle', ok: discovery.capabilities.git }];
-    if (existing?.embedding?.provider !== 'none') { try { adapterFor(existing).validate(existing.embedding); checks.push({ check: `provider:${existing.embedding.provider}`, ok: true }); } catch (error) { checks.push({ check: `provider:${existing.embedding.provider}`, ok: false, detail: error.message }); } }
-    return show({ ok: checks.every(check => check.ok), checks });
+    const hasRuntimeLane = runtime.lanes.some(lane => lane.configured);
+    const checks = [
+      { check: 'knowledge_authority', ok: Boolean(existing) || hasRuntimeLane, detail: existing ? CONFIG_PATH : hasRuntimeLane ? 'Detected repository knowledge runtime.' : 'No local config or declared runtime lane found.' },
+      { check: 'local_sqlite', ok: runtime.local_index.exists, blocking: false, detail: runtime.local_index.exists ? runtime.local_index.path : 'Not indexed yet; run agentsam index run or agentsam autorag probe.' },
+      { check: 'git_merkle', ok: discovery.repository.merkle, blocking: false, detail: discovery.repository.merkle ? '.agentsam/merkle.json' : 'No Merkle snapshot yet; run agentsam merkle root . --json when snapshot evidence is needed.' },
+    ];
+    if (existing?.embedding && existing.embedding.provider !== 'none') {
+      try { adapterFor(existing).validate(existing.embedding); checks.push({ check: 'provider:' + existing.embedding.provider, ok: true }); }
+      catch (error) { checks.push({ check: 'provider:' + existing.embedding.provider, ok: false, detail: error.message }); }
+    }
+    if (runtime.resources.vectorize.length) checks.push({ check: 'cloudflare_vectorize', ok: runtime.conflicts.length === 0 && runtime.resources.vectorize.every(row => row.configured && (row.locally_executable || row.remotely_executable)), detail: runtime.resources.vectorize });
+    if (runtime.resources.workers_ai.observed) checks.push({ check: 'workers_ai_runtime', ok: runtime.resources.workers_ai.remotely_executable || runtime.resources.workers_ai.locally_executable, detail: runtime.resources.workers_ai });
+    if (runtime.conflicts.length) checks.push({ check: 'project_context_conflicts', ok: false, detail: runtime.conflicts });
+    return show({ ok: checks.filter(check => check.blocking !== false).every(check => check.ok), checks, project_context: runtime, runtime });
+  }
+  if (command === 'lanes') {
+    const configured = existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector', source: CONFIG_PATH }] : [];
+    const laneKey = lane => [lane.backend, lane.binding || '', lane.index || ''].join(':');
+    const seen = new Set(configured.map(laneKey));
+    return show([...configured, ...runtime.lanes.filter(lane => !seen.has(laneKey(lane)))]);
   }
-  if (command === 'lanes') return show(existing ? [existing.lane || { id: 'legacy-local', backend: existing.storage.driver === 'sqlite' ? 'local_exact' : 'postgres_pgvector' }] : []);
   if (command === 'setup' || command === 'configure' || command === 'scope') {
-    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing);
+    const selected = opts.yes ? opts : await interactiveOptions(discovery, opts); const { recommendation, config } = defaults(discovery, selected, existing, runtime);
     writeConfig(root, config); return show({ action: command, config: CONFIG_PATH, recommendation, config, next: ['agentsam autorag probe', 'agentsam index plan', 'agentsam index run', 'agentsam search "symbol or phrase"'] });
   }
   if (!existing) throw new Error('AutoRAG is not configured. Run agentsam autorag setup first.');

package/src/commands/cheat-sheet.js

@@ -1,6 +1,7 @@
 /**
  * Canonical Agent Sam cheat-sheet — gcloud-like command groups.
  * Old top-level commands remain as compatibility aliases.
+ * Every row shows a copy-pasteable `agentsam …` invocation.
  */
 
 const GROUPS = Object.freeze([
@@ -19,8 +20,13 @@ const GROUPS = Object.freeze([
     label: 'Repository',
     commands: [
       ['inspect', 'Bounded repository authority view'],
+      ['machine', 'Deterministic local perception + asset discovery'],
+      ['machine inspect', 'Inspect a path (file or directory)'],
       ['recon', 'Bounded-worker finding packets'],
       ['codebaseindex', 'AST ingest + optional embeddings'],
+      ['index', 'Project inventory + knowledge index commands'],
+      ['index status', 'Show knowledge index freshness'],
+      ['search', 'Retrieve from the local knowledge index'],
       ['merkle', 'Integrity snapshots'],
       ['security', 'Dependency + trust-boundary scan'],
     ],
@@ -103,16 +109,30 @@ const GROUPS = Object.freeze([
       ['update', 'Component update preview (gcloud-like)'],
       ['billing', 'Billing account relationships (not --billing-project)'],
       ['cheat-sheet', 'This page'],
-      ['version', 'agentsam --version'],
+      ['version', 'Print CLI version'],
     ],
   },
 ]);
 
+/** Expand "a / b" rows into copy-pasteable `agentsam …` invocations. */
+export function agentsamInvocations(cmd) {
+  const raw = String(cmd || '').trim();
+  if (!raw) return [];
+  if (raw.includes(' / ')) {
+    return raw.split(' / ').map((part) => `agentsam ${part.trim()}`);
+  }
+  return [`agentsam ${raw}`];
+}
+
 export function listCheatSheetGroups() {
   return GROUPS.map((group) => ({
     id: group.id,
     label: group.label,
-    commands: group.commands.map(([cmd, summary]) => ({ cmd, summary })),
+    commands: group.commands.map(([cmd, summary]) => ({
+      cmd,
+      summary,
+      invocations: agentsamInvocations(cmd),
+    })),
   }));
 }
 
@@ -120,13 +140,18 @@ export function renderCheatSheet(version) {
   const lines = [
     '',
     `  Agent Sam cheat-sheet${version ? ` · v${version}` : ''}`,
-    '  Organized hierarchy · old top-level commands remain compatibility aliases.',
+    '  Organized hierarchy · each row shows a runnable `agentsam …` command.',
     '',
   ];
   for (const group of GROUPS) {
     lines.push(`  ${group.label}`);
     for (const [cmd, summary] of group.commands) {
-      lines.push(`    ${String(cmd).padEnd(42)}  ${summary}`);
+      const invocations = agentsamInvocations(cmd);
+      const primary = invocations[0] || `agentsam ${cmd}`;
+      lines.push(`    ${primary.padEnd(52)}  ${summary}`);
+      for (const extra of invocations.slice(1)) {
+        lines.push(`    ${extra.padEnd(52)}  (same group)`);
+      }
     }
     lines.push('');
   }

package/src/commands/codebaseindex.js

@@ -16,6 +16,8 @@ import { openSqliteStore } from '../knowledge/stores/sqlite.js';
 import { openPostgresStore } from '../knowledge/stores/postgres.js';
 import { planIndex, retrieve, runIndex } from '../knowledge/engine.js';
 import { createProviderRegistry } from '../../packages/agentsam-knowledge/src/providers/index.js';
+import { createBackendRegistry } from '../../packages/agentsam-knowledge/src/backends/index.js';
+import { discoverProjectContext } from '../knowledge/runtime-discovery.js';
 import { ensureProjectManifest, getRepositoryId, portableRepositoryIdFromGit, tryReadProjectConfig } from '../lib/project-config.js';
 import { parsePastedPaths, stageMaterials } from '../indexing/ingest/materials.js';
 import {
@@ -74,6 +76,21 @@ function writeKnowledgeConfig(root, config) {
   return validated;
 }
 
+function resolveVectorLane(root, vectors, input = {}) {
+  if (vectors !== 'vectorize') return null;
+  const explicitBinding = String(input.vectorBinding || input.binding || '').trim();
+  const explicitIndex = String(input.vectorIndex || input.index || '').trim();
+  if (explicitBinding || explicitIndex) {
+    if (!explicitBinding || !explicitIndex) throw new Error('Vectorize requires both vectorBinding and vectorIndex when either is supplied.');
+    return { backend: 'cloudflare_vectorize', binding: explicitBinding, index: explicitIndex };
+  }
+  const context = discoverProjectContext(root);
+  const resources = context.resources.vectorize.filter(row => row.configured);
+  if (resources.length === 1) return { backend: 'cloudflare_vectorize', binding: resources[0].binding, index: resources[0].index };
+  if (!resources.length) throw new Error('No Cloudflare Vectorize binding is declared by this project. Configure Wrangler or pass vectorBinding/vectorIndex explicitly.');
+  throw new Error('Multiple Cloudflare Vectorize bindings are declared. Select vectorBinding/vectorIndex explicitly.');
+}
+
 function loadOrBuildConfig(root, preferences) {
   const project = tryReadProjectConfig(root) || ensureProjectManifest(root, {});
   const repositoryId = getRepositoryId(project) || portableRepositoryIdFromGit(root) || preferences.repositoryId;
@@ -103,7 +120,14 @@ function loadOrBuildConfig(root, preferences) {
     storage: preferences.storage === 'postgres'
       ? { driver: 'postgres', connection_env: preferences.connectionEnv || 'AGENTSAM_DATABASE_URL' }
       : { driver: 'sqlite' },
-    lane: {
+    lane: preferences.vectorLane ? {
+      id: `${preferences.scopeName || 'default'}-cloudflare-vectorize`,
+      backend: 'cloudflare_vectorize',
+      resource: null,
+      binding: preferences.vectorLane.binding,
+      index: preferences.vectorLane.index,
+      metric: 'cosine',
+    } : {
       id: `${preferences.scopeName || 'default'}-ingest`,
       backend: preferences.storage === 'postgres' ? 'postgres_pgvector' : 'local_exact',
       resource: null,
@@ -172,11 +196,13 @@ export async function runCodebaseindexIngest(input = {}, ctx = {}) {
   const vectors = input.vectors || (embedding.provider === 'none' ? 'none'
     : storage === 'postgres' ? 'pgvector' : 'sqlite_exact');
 
+  const vectorLane = resolveVectorLane(root, vectors, input);
   const config = loadOrBuildConfig(root, {
     include,
     exclude,
     embedding,
     storage,
+    vectorLane,
     scopeName: input.scope || 'ingest',
     connectionEnv: input.connectionEnv,
   });
@@ -185,6 +211,9 @@ export async function runCodebaseindexIngest(input = {}, ctx = {}) {
   jobGraph = advanceJobGraph(jobGraph, 'lane.resolve');
 
   const embed = Boolean(input.embed) && embedding.provider !== 'none';
+  if (vectors === 'vectorize' && !embed && !input.planOnly) {
+    throw new Error('Cloudflare Vectorize execution requires an embedding provider and embed=true. Use planOnly to inspect the lane without writing vectors.');
+  }
   const store = await openStore(root, config, false);
   try {
     if (input.planOnly) {
@@ -214,12 +243,26 @@ export async function runCodebaseindexIngest(input = {}, ctx = {}) {
       validate: (...args) => (adapter ??= providerAdapter(config.embedding)).validate(...args),
       embed: (...args) => (adapter ??= providerAdapter(config.embedding)).embed(...args),
     };
+    const vectorBackend = config.lane?.backend === 'cloudflare_vectorize'
+      ? createBackendRegistry().get('cloudflare_vectorize')
+      : null;
+    const vectorContext = {
+      ...(ctx.cloudflare || {}),
+      ...(input.vectorContext || {}),
+      env: input.env || ctx.env || process.env,
+      ownerId: input.ownerId || ctx.ownerId || ctx.owner_id || '',
+      accountId: input.accountId || ctx.accountId || '',
+      workerBinding: input.workerBinding || ctx.workerBinding,
+      apiClient: input.apiClient || ctx.apiClient,
+    };
     const result = await runIndex({
       root,
       config,
       store,
       embed,
       embedder,
+      vectorBackend,
+      vectorContext,
       maxInputs: Number(input.maxInputs ?? 200),
       maxCharacters: Number(input.maxCharacters ?? 400000),
     });
@@ -568,7 +611,7 @@ async function runWizard(root, opts) {
   }));
   const storage = lane === 'supabase' ? 'postgres' : 'sqlite';
   if (lane === 'vectorize') {
-    note('Vectorize lane recorded for plan/receipt; full CF adapter wiring is a follow-up slice.', 'Lane note');
+    note('Uses this project’s declared Vectorize binding via Worker runtime or the current user’s authorized Cloudflare API transport.', 'Lane note');
   }
   if (lane === 'supabase') {
     note('Uses AGENTSAM_DATABASE_URL / Hyperdrive-style postgres. Owner IAM already has node-api.', 'Lane note');

package/src/commands/goap-world.js

@@ -0,0 +1,134 @@
+import { buildRepositoryAuditPacket } from '../agent/repository-audit.js';
+import { repositorySnapshot } from '../capabilities/repository-snapshot.js';
+import { getNextPlanStep, getPlan, openPlanLedger } from './plan-ledger.js';
+import { projectGoapWorld } from '../../packages/agentsam-goap/src/world.js';
+
+const PRIORITY_TO_TICKET = Object.freeze({
+  critical: 'P0',
+  high: 'P1',
+  medium: 'P2',
+  low: 'P3',
+});
+
+function stableJson(value) {
+  if (Array.isArray(value)) return '[' + value.map(stableJson).join(',') + ']';
+  if (value && typeof value === 'object') {
+    return '{' + Object.keys(value).sort().map((key) => JSON.stringify(key) + ':' + stableJson(value[key])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+export function knowledgeFreshness(snapshot = {}) {
+  const knowledge = snapshot.knowledge || {};
+  if (!knowledge.configured) return { status: 'not_configured', reason: 'knowledge_config_missing' };
+  if (!knowledge.indexed) return { status: 'not_indexed', reason: 'active_generation_missing' };
+  const receipt = knowledge.receipt || {};
+  if (receipt.scope && knowledge.scope && stableJson(receipt.scope) !== stableJson(knowledge.scope)) {
+    return { status: 'stale', reason: 'scope_policy_changed' };
+  }
+  if (receipt.merkle_root && snapshot.tree?.merkle_root && receipt.merkle_root !== snapshot.tree.merkle_root) {
+    return { status: 'stale', reason: 'repository_merkle_changed' };
+  }
+  return { status: 'current', reason: 'active_generation_matches_world' };
+}
+
+export async function buildLocalGoapState({ cwd = process.cwd(), snapshot = null } = {}) {
+  const ctx = openPlanLedger(cwd);
+  try {
+    const plan = getPlan(ctx, 'current');
+    if (!plan) return null;
+
+    const running = (plan.tasks || []).find((task) => task.status === 'running') || null;
+    const next = running ? null : getNextPlanStep(ctx, { planId: plan.id });
+    const step = running || next?.step || null;
+    const world = snapshot || await repositorySnapshot({ cwd: ctx.root });
+    const packet = buildRepositoryAuditPacket({
+      snapshot: world,
+      focus: [plan.title, step?.title].filter(Boolean),
+      requestedSections: ['repository', 'tree', 'knowledge', 'packages'],
+      evidenceBudget: 6000,
+    });
+    const freshness = knowledgeFreshness(world);
+    const projectedWorld = projectGoapWorld({
+      repository: {
+        ...world.repository,
+        merkle_root: world.tree?.merkle_root || null,
+      },
+      plan,
+      activeTodo: step,
+      knowledge: {
+        ...freshness,
+        generation_id: world.knowledge?.generation_id || null,
+      },
+      evidence: packet,
+      updatedAt: step?.updated_at_unix || plan.updated_at_unix || null,
+    });
+    const run = step?.agent_run_id
+      ? ctx.db.prepare('SELECT * FROM agentsam_agent_run WHERE id = ? LIMIT 1').get(step.agent_run_id) || null
+      : null;
+
+    const git = {
+      root: ctx.root,
+      repoFullName: world.repository?.full_name || ctx.git?.repoFullName || null,
+      revisionSha: world.repository?.revision_sha || ctx.git?.revisionSha || null,
+      branch: world.repository?.branch || ctx.git?.branch || null,
+      dirty: world.repository?.dirty ?? ctx.git?.dirty ?? null,
+    };
+    const activeTicket = step ? {
+      id: step.id,
+      title: step.title,
+      status: step.status,
+      priority: PRIORITY_TO_TICKET[step.priority] || 'P2',
+      subsystem: step.metadata?.kind || 'work',
+      surface: 'local',
+      status_reason: 'selected_from_project_local_plan',
+      description: step.description || null,
+      agent_run_id: step.agent_run_id || null,
+    } : {
+      id: plan.id,
+      title: plan.title,
+      status: plan.tasks_done === plan.tasks_total ? 'complete' : 'active',
+      priority: 'P2',
+      subsystem: 'plan',
+      surface: 'local',
+      status_reason: 'plan_has_no_open_executable_step',
+      agent_run_id: null,
+    };
+
+    return {
+      ok: true,
+      source: 'local_world',
+      repositoryId: world.repository?.repository_id || ctx.repositoryId,
+      git,
+      workspaceState: {
+        current_task_id: step?.id || null,
+        locked_by: 'project_local_plan',
+        checkpoint_sha: plan.metadata?.revision || null,
+        last_agent_action: 'world_snapshot_projected',
+        updated_at: step?.updated_at_unix || plan.updated_at_unix || null,
+      },
+      activeTicket,
+      agentRun: run,
+      recentCommits: [],
+      checkpoint: null,
+      cursor: {},
+      steps: plan.tasks || [],
+      stepsUnavailable: false,
+      localPlan: plan,
+      localStep: step,
+      worldSnapshot: {
+        snapshot_id: world.snapshot_id,
+        content_hash: world.content_hash,
+        merkle_root: world.tree?.merkle_root || null,
+        knowledge_generation_id: world.knowledge?.generation_id || null,
+        knowledge_freshness: freshness,
+        repository: world.repository,
+        actions: projectedWorld.actions,
+      },
+      boundedEvidence: packet,
+      canonicalWorld: projectedWorld,
+    };
+  } finally {
+    ctx.close();
+  }
+}

package/src/commands/goap.js

@@ -11,6 +11,7 @@ import {
   renderGoapPlan,
 } from '../../packages/agentsam-repository/src/goap.js';
 import { readAccountSession } from '../lib/account-session.js';
+import { buildLocalGoapState } from './goap-world.js';
 
 function parseArgs(args = []) {
   const flags = { _: [] };
@@ -102,7 +103,7 @@ export async function runGoap(subcommand = 'status', options = {}) {
     console.log(`Successfully created and activated GOAP goal: ${res.ticketId}`);
     console.log(`  Title:     ${res.title}`);
     console.log(`  Priority:  ${res.priority} [Subsystem: ${res.subsystem}]`);
-    console.log(`  Agent Run: ${res.agentRunId}`);
+    if (res.agentRunId) console.log(`  Agent Run: ${res.agentRunId}`);
     return;
   }
 
@@ -147,9 +148,15 @@ export async function runGoap(subcommand = 'status', options = {}) {
     return;
   }
 
-  const state = await readGoapState({ cwd, accountId });
-  if (!state.ok) {
-    console.error(`Error reading GOAP state: ${state.error || 'unknown error'}`);
+  let state = null;
+  try {
+    state = await buildLocalGoapState({ cwd });
+  } catch (error) {
+    if (jsonMode && options.debug) console.error(error?.stack || error);
+  }
+  if (!state && accountId) state = await readGoapState({ cwd, accountId });
+  if (!state?.ok) {
+    console.error(`Error reading GOAP state: ${state?.error || 'no local plan or remote GOAP state available'}`);
     return;
   }
 

package/src/commands/knowledge.js

@@ -169,10 +169,66 @@ export async function runSearch(argv) {
   finally { await store?.close(); }
 }
 
+function compactNumber(value) {
+  const n = Number(value || 0);
+  if (!Number.isFinite(n)) return '0';
+  if (Math.abs(n) >= 1_000_000) return `${(n / 1_000_000).toFixed(n >= 10_000_000 ? 1 : 2).replace(/\.0+$/, '')}m`;
+  if (Math.abs(n) >= 1_000) return `${(n / 1_000).toFixed(n >= 100_000 ? 0 : 1).replace(/\.0$/, '')}k`;
+  return String(n);
+}
+
+export function renderRepositoryObservation(observation) {
+  const data = observation?.data || {};
+  const git = data.git || {};
+  const summary = data.summary || {};
+  const top = Array.isArray(data.top_level) ? data.top_level.slice(0, 5) : [];
+  const pressure = Array.isArray(data.pressure_points) ? data.pressure_points.slice(0, 6) : [];
+  const dirty = git.dirty ? `dirty · ${git.changed_paths || 0} changed` : 'clean';
+  const head = git.head_sha ? String(git.head_sha).slice(0, 10) : 'unknown';
+
+  const lines = [
+    '',
+    '  Agent Sam · repository',
+    '',
+    `  repo       ${data.repo_name || path.basename(data.repo_root || '') || 'unknown'}`,
+    `  root       ${data.repo_root || 'unknown'}`,
+    `  git        ${git.branch || 'unknown'} @ ${head} · ${dirty}`,
+    `  scale      ${compactNumber(summary.file_count)} files · ${compactNumber(summary.source_file_count)} source · ${compactNumber(summary.total_lines)} lines`,
+  ];
+
+  if (top.length) {
+    lines.push('', '  Primary areas');
+    for (const row of top) {
+      lines.push(`    ${String(row.path || '.').padEnd(28)} ${compactNumber(row.files)} files · ${compactNumber(row.lines)} lines`);
+    }
+  }
+
+  if (pressure.length) {
+    lines.push('', '  Change pressure');
+    for (const row of pressure) {
+      lines.push(`    ${String(row.path || '.').padEnd(28)} pressure ${Number(row.pressure_score || 0).toFixed(1)} · stability ${Number(row.stability_score || 0).toFixed(1)}`);
+    }
+    lines.push('    relative activity heuristics — not quality grades');
+  }
+
+  lines.push(
+    '',
+    '  More',
+    '    agentsam repo --json              full deterministic receipt',
+    '    agentsam repo history             saved observations',
+    '    agentsam repo compare             compare latest saved observations',
+    '    agentsam inspect                  bounded architecture / authority view',
+    '    agentsam machine inspect          native deterministic perception',
+    '',
+  );
+  return lines.join('\n');
+}
+
 export async function runRepository(argv) {
   const { values: opts, positionals } = flags(argv, { save: { type: 'boolean' }, 'churn-days': { type: 'string' } });
   const command = positionals[0] || 'snapshot';
-  if (opts.help) { console.log('agentsam repo snapshot [--cwd PATH] [--churn-days 30] [--save] [--json]\nagentsam repo history|compare [--cwd PATH]\nUses the bundled Python repository intelligence; --save retains observations for comparisons.'); return; }
+  if (opts.help) { console.log('agentsam repo [snapshot] [--cwd PATH] [--churn-days 30] [--save] [--json]\nagentsam repo history|compare [--cwd PATH]\nDefault output is a human summary; --json emits the full deterministic receipt.'); return; }
+  if (command === 'context') throw new Error('Repository context is `agentsam context`. Use `agentsam repo snapshot|history|compare` for repository intelligence.');
   if (positionals.length > 1 || !['snapshot', 'history', 'compare'].includes(command)) throw new Error('Use agentsam repo snapshot|history|compare.');
   const root = repositoryRoot(opts.cwd);
   let store;
@@ -190,6 +246,7 @@ export async function runRepository(argv) {
     });
     const observation = { id: randomUUID(), created_at: new Date().toISOString(), kind: 'repository-intelligence', data: JSON.parse(result.stdout) };
     if (store) await store.observe(cacheNamespace(readConfig(root)), observation);
-    show(observation);
+    if (opts.json) show(observation);
+    else console.log(renderRepositoryObservation(observation));
   } finally { await store?.close(); }
 }