@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

package/src/commands/run.js

@@ -0,0 +1,253 @@
+import { createAgentControlClient } from '../acp/client.js';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function number(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); }
+
+function parse(argv = []) {
+  const out = {
+    command: clean(argv[0]) || 'help',
+    id: null,
+    json: false,
+    local: false,
+    url: '',
+    once: false,
+    after: -1,
+    limit: 200,
+    intervalMs: 1000,
+    objective: '',
+    role: '',
+    workItemId: '',
+    stepId: '',
+    modelKey: '',
+    runtimeRequirements: {},
+  };
+  let i = 1;
+  if (!['help', 'start'].includes(out.command) && argv[i] && !String(argv[i]).startsWith('-')) out.id = String(argv[i++]);
+  for (; i < argv.length; i += 1) {
+    const arg = String(argv[i]);
+    if (arg === '--json') out.json = true;
+    else if (arg === '--local') out.local = true;
+    else if (arg === '--once') out.once = true;
+    else if (arg === '--url') out.url = String(argv[++i] || '');
+    else if (arg.startsWith('--url=')) out.url = arg.slice(6);
+    else if (arg === '--after') out.after = number(argv[++i], -1);
+    else if (arg.startsWith('--after=')) out.after = number(arg.slice(8), -1);
+    else if (arg === '--limit') out.limit = number(argv[++i], 200);
+    else if (arg.startsWith('--limit=')) out.limit = number(arg.slice(8), 200);
+    else if (arg === '--interval-ms') out.intervalMs = number(argv[++i], 1000);
+    else if (arg.startsWith('--interval-ms=')) out.intervalMs = number(arg.slice(14), 1000);
+    else if (arg === '--objective') out.objective = String(argv[++i] || '');
+    else if (arg.startsWith('--objective=')) out.objective = arg.slice(12);
+    else if (arg === '--role') out.role = String(argv[++i] || '');
+    else if (arg.startsWith('--role=')) out.role = arg.slice(7);
+    else if (arg === '--work-item') out.workItemId = String(argv[++i] || '');
+    else if (arg.startsWith('--work-item=')) out.workItemId = arg.slice(12);
+    else if (arg === '--step') out.stepId = String(argv[++i] || '');
+    else if (arg.startsWith('--step=')) out.stepId = arg.slice(7);
+    else if (arg === '--model') out.modelKey = String(argv[++i] || '');
+    else if (arg.startsWith('--model=')) out.modelKey = arg.slice(8);
+    else if (arg === '--runtime-json') out.runtimeRequirements = JSON.parse(String(argv[++i] || '{}'));
+    else if (arg.startsWith('--runtime-json=')) out.runtimeRequirements = JSON.parse(arg.slice(15) || '{}');
+    else throw new Error(`unknown_run_option:${arg}`);
+  }
+  return out;
+}
+
+function help() {
+  return [
+    'Agent Sam · run',
+    'Provider-neutral Agent Control Plane inspection and control.',
+    '',
+    'Usage:',
+    '  agentsam run start --objective <text> [--role <slug>] [--model <key>] [--runtime-json <json>] [--json]',
+    '  agentsam run get <run_id> [--json] [--local | --url <base-url>]',
+    '  agentsam run tree <run_id> [--json]',
+    '  agentsam run events <run_id> [--after <seq>] [--limit <n>] [--json]',
+    '  agentsam run watch <run_id> [--after <seq>] [--interval-ms <ms>] [--once] [--json]',
+    '  agentsam run spawn <parent_run_id> --objective <text> [--role <slug>] [--runtime-json <json>] [--json]',
+    '  agentsam run cancel <run_id> [--json]',
+    '  agentsam run receipt <run_id> [--json]',
+    '',
+    'Host selection:',
+    '  local SQLite is the default.',
+    '  AGENTSAM_CONTROL_PLANE_URL or --url selects any HTTP ACP host.',
+    '  AGENTSAM_CONTROL_PLANE_TOKEN supplies hosted bearer auth without putting secrets in shell history.',
+    '  --local forces the project-local SQLite control plane.',
+  ].join('\n');
+}
+
+function formatRun(run, clientKind) {
+  if (!run) return 'run not found';
+  return [
+    'Agent Sam · run',
+    `source   ${clientKind}`,
+    `id       ${run.id}`,
+    `status   ${run.status}${run.cancelRequested ? ' · cancel requested' : ''}`,
+    `mode     ${run.mode || 'unknown'}`,
+    `parent   ${run.parentRunId || '—'}`,
+    `model    ${run.modelKey || '—'}`,
+    `calls    model ${run.modelCallCount || 0} · tool ${run.toolCallCount || 0}`,
+    `cost     $${Number(run.costUsd || 0).toFixed(6)}`,
+    run.suspension ? `wait     ${run.suspension.state} · ${run.suspension.reason}` : null,
+  ].filter(Boolean).join('\n');
+}
+
+function treeLines(node, depth = 0, rows = []) {
+  if (!node) return rows;
+  const indent = '  '.repeat(depth);
+  rows.push(`${indent}${depth ? '└─ ' : ''}${node.id} · ${node.status} · ${node.mode || 'agent'}`);
+  for (const child of node.children || []) treeLines(child, depth + 1, rows);
+  return rows;
+}
+
+function eventLine(event) {
+  const at = event.createdAt ? new Date(event.createdAt).toISOString() : '';
+  return `#${event.seq} ${event.eventType}${event.phase ? ` · ${event.phase}` : ''}${event.label ? ` · ${event.label}` : ''}${at ? ` · ${at}` : ''}`;
+}
+
+function requireId(args) {
+  if (!clean(args.id)) {
+    const error = new Error(`run_id_required:${args.command}`);
+    error.hint = `Usage: agentsam run ${args.command} <run_id>`;
+    throw error;
+  }
+}
+
+export async function runRun(argv = [], options = {}) {
+  const args = parse(argv);
+  const write = options.write || ((value) => process.stdout.write(String(value)));
+  if (args.command === 'help' || args.command === '--help' || args.command === '-h') {
+    write(help() + '\n');
+    return { ok: true, command: 'help' };
+  }
+  if (!['start', 'get', 'tree', 'events', 'watch', 'spawn', 'cancel', 'receipt'].includes(args.command)) {
+    throw new Error(`unknown_run_command:${args.command}`);
+  }
+  if (args.command !== 'start') requireId(args);
+
+  const client = options.client || createAgentControlClient({
+    cwd: options.cwd || process.cwd(),
+    url: args.url || options.url,
+    token: options.token,
+    local: args.local,
+    fetchImpl: options.fetchImpl,
+  });
+
+  if (args.command === 'start') {
+    if (!clean(args.objective)) {
+      const error = new Error('run_objective_required');
+      error.hint = 'Usage: agentsam run start --objective <text>';
+      throw error;
+    }
+    const started = await client.start({
+      objective: args.objective,
+      role: clean(args.role) || 'lead',
+      model_key: clean(args.modelKey) || null,
+      runtime_requirements: args.runtimeRequirements,
+    });
+    if (args.json) write(JSON.stringify(started, null, 2) + '\n');
+    else {
+      write([
+        'Agent Sam · run started',
+        `run      ${started.run_id}`,
+        `queue    ${started.queue || 'host-managed'}`,
+        `status   ${started.status || 'queued'}`,
+      ].join('\n') + '\n');
+    }
+    return started;
+  }
+
+  if (args.command === 'get') {
+    const run = await client.getRun(args.id);
+    if (!run) throw new Error(`run_not_found:${args.id}`);
+    write(args.json ? JSON.stringify(run, null, 2) + '\n' : formatRun(run, client.kind) + '\n');
+    return run;
+  }
+
+  if (args.command === 'tree') {
+    const tree = await client.tree(args.id);
+    if (!tree) throw new Error(`run_not_found:${args.id}`);
+    write(args.json ? JSON.stringify(tree, null, 2) + '\n' : treeLines(tree).join('\n') + '\n');
+    return tree;
+  }
+
+  if (args.command === 'events') {
+    const events = await client.events(args.id, { after: args.after, limit: args.limit });
+    write(args.json ? JSON.stringify(events, null, 2) + '\n' : (events.map(eventLine).join('\n') || 'no events') + '\n');
+    return events;
+  }
+
+  if (args.command === 'spawn') {
+    if (!clean(args.objective)) {
+      const error = new Error('child_run_objective_required');
+      error.hint = 'Usage: agentsam run spawn <parent_run_id> --objective <text>';
+      throw error;
+    }
+    const spawned = await client.spawn(args.id, {
+      objective: args.objective,
+      role: clean(args.role) || null,
+      work_item_id: clean(args.workItemId) || null,
+      step_id: clean(args.stepId) || null,
+      model_key: clean(args.modelKey) || null,
+      runtime_requirements: args.runtimeRequirements,
+    });
+    if (args.json) write(JSON.stringify(spawned, null, 2) + '\n');
+    else {
+      write([
+        'Agent Sam · child run',
+        `parent   ${spawned.parent_run_id || args.id}`,
+        `child    ${spawned.child_run_id || '—'}`,
+        `queue    ${spawned.queue || 'host-managed'}`,
+        `status   ${spawned.dependency_status || 'pending'}`,
+      ].join('\n') + '\n');
+    }
+    return spawned;
+  }
+
+  if (args.command === 'cancel') {
+    const run = await client.cancel(args.id);
+    if (!run) throw new Error(`run_not_found:${args.id}`);
+    write(args.json ? JSON.stringify(run, null, 2) + '\n' : formatRun(run, client.kind) + '\n');
+    return run;
+  }
+
+  if (args.command === 'receipt') {
+    const receipt = await client.receipt(args.id);
+    if (!receipt) throw new Error(`run_not_found:${args.id}`);
+    if (args.json) write(JSON.stringify(receipt, null, 2) + '\n');
+    else {
+      write([
+        'Agent Sam · run receipt',
+        `id       ${receipt.runId}`,
+        `status   ${receipt.status}`,
+        `terminal ${receipt.terminal ? 'yes' : 'no'}`,
+        `events   ${receipt.eventCount}`,
+        `children ${receipt.childRunCount}`,
+        `cost     $${Number(receipt.usage?.costUsd || 0).toFixed(6)}`,
+      ].join('\n') + '\n');
+    }
+    return receipt;
+  }
+
+  let after = args.after;
+  const seen = [];
+  const wait = options.sleep || sleep;
+  do {
+    const events = await client.events(args.id, { after, limit: args.limit });
+    for (const event of events) {
+      seen.push(event);
+      after = Math.max(after, Number(event.seq));
+      write(args.json ? JSON.stringify(event) + '\n' : eventLine(event) + '\n');
+    }
+    const run = await client.getRun(args.id);
+    if (!run) throw new Error(`run_not_found:${args.id}`);
+    if (args.once || ['completed', 'failed', 'cancelled', 'timed_out'].includes(run.status)) {
+      return { run, events: seen, after };
+    }
+    await wait(Math.max(100, args.intervalMs));
+  } while (true);
+}

package/src/commands/shell.js

@@ -33,6 +33,7 @@ import { grantExecutionApproval, isExecutionApproved, toolApprovalKey } from '..
 import { runWhoami } from './whoami.js';
 import { runCredentials } from './credentials.js';
 import { runCheatSheet } from './cheat-sheet.js';
+import { createProjectHookRuntime, runHooks } from './hooks.js';
 import pkg from '../../package.json' with { type: 'json' };
 import { runLogin, runLogout } from './account-auth.js';
 import { runHelp } from '../ui/cli/help.js';
@@ -262,21 +263,48 @@ function spawnGit(cwd, args) {
   if (result.status !== 0) throw new Error(`git exited ${result.status}`);
 }
 
-function selectedModel(cwd) {
-  const preferences = readCliPreferences(cwd) || {};
-  const snapshot = preferences.modelSnapshot?.model_key === preferences.modelPreference
-    ? mergeModelReference(preferences.modelSnapshot)
+function selectedModel(cwd, state = null) {
+  const saved = readCliPreferences(cwd) || {};
+  const sessionConfig = state?.hookEffectiveConfig || {};
+  const preferences = {
+    ...saved,
+    ...(sessionConfig.model_key ? { modelPreference: sessionConfig.model_key } : {}),
+    ...(sessionConfig.reasoning_effort ? { reasoningEffort: sessionConfig.reasoning_effort } : {}),
+    ...(sessionConfig.requested_service_tier ? { serviceTier: sessionConfig.requested_service_tier } : {}),
+  };
+  const snapshot = saved.modelSnapshot?.model_key === preferences.modelPreference
+    ? mergeModelReference(saved.modelSnapshot)
     : null;
   let model = snapshot || getModelRecord(preferences.modelPreference);
+  if (!model && sessionConfig.model_key && sessionConfig.model_key.includes(':')) {
+    const [provider, ...modelParts] = sessionConfig.model_key.split(':');
+    const providerModelId = modelParts.join(':');
+    if (provider && providerModelId) {
+      model = {
+        model_key: sessionConfig.model_key,
+        provider,
+        provider_model_id: providerModelId,
+        label: providerModelId,
+        context_window: null,
+        context_window_source: 'unknown',
+        max_output_tokens: null,
+        max_output_tokens_source: 'unknown',
+        reasoning_efforts: ['auto'],
+        default_reasoning_effort: null,
+        service_tiers: ['default'],
+        capabilities: {},
+      };
+    }
+  }
   if (!model && (preferences.modelPreference === 'auto' || !preferences.modelPreference)) {
-    model = mergeModelReference(preferences.modelSnapshot) || listModelCatalog()[0];
+    model = mergeModelReference(saved.modelSnapshot) || listModelCatalog()[0];
   }
   if (!model) throw new Error('Select an exact provider-verified model with /model first so Agent Sam can verify supported runtime controls.');
   return { preferences, model };
 }
 
 async function resolveModelForTurn(cwd, state) {
-  const selected = selectedModel(cwd);
+  const selected = selectedModel(cwd, state);
   const { preferences } = selected;
   let model = selected.model;
 
@@ -291,7 +319,7 @@ async function resolveModelForTurn(cwd, state) {
       capabilities: { ...(model.capabilities || {}), local_runtime: true, ...(Object.fromEntries((probe.capabilities || []).map((name) => [name, true]))) },
     };
     updateCliPreferences(cwd, { modelPreference: model.model_key, modelSnapshot: model });
-    return { preferences: readCliPreferences(cwd) || preferences, model, credential: null, verification: 'local_runtime' };
+    return { preferences: { ...(readCliPreferences(cwd) || preferences), reasoningEffort: preferences.reasoningEffort, serviceTier: preferences.serviceTier }, model, credential: null, verification: 'local_runtime' };
   }
 
   const credential = resolveProviderCredential(model.provider, { home: state.home });
@@ -305,7 +333,7 @@ async function resolveModelForTurn(cwd, state) {
     if (!live) throw new Error(`selected_model_not_available_for_credential:${model.provider}:${model.provider_model_id}`);
     model = live;
     updateCliPreferences(cwd, { modelPreference: live.model_key, modelSnapshot: live });
-    return { preferences: readCliPreferences(cwd) || preferences, model, credential, verification: 'provider_api' };
+    return { preferences: { ...(readCliPreferences(cwd) || preferences), reasoningEffort: preferences.reasoningEffort, serviceTier: preferences.serviceTier }, model, credential, verification: 'provider_api' };
   }
 
   if (preferences.modelSnapshot?.availability === 'available') {
@@ -595,7 +623,47 @@ function checkpointCompaction(state, model, result) {
   return receipt;
 }
 
+async function ensureShellHookExperience(state) {
+  if (state.hookExperience) return state.hookExperience;
+  const experience = await createProjectHookRuntime({
+    cwd: state.cwd,
+    projectRoot: state.projectRoot,
+    home: state.home,
+    sessionId: state.session?.id,
+    conversationId: state.session?.conversation_id,
+    hooks: state.codeHooks,
+  });
+  state.hookExperience = experience;
+  if (!state.hookSessionStarted) {
+    const config = {
+      model_key: state.session?.model_key || null,
+      reasoning_effort: state.session?.reasoning_effort || null,
+      requested_service_tier: state.session?.requested_service_tier || 'default',
+      auto_compact: state.session?.auto_compact !== false,
+    };
+    const started = await experience.runtime.dispatch('session_start', {
+      config,
+      project_root: state.projectRoot,
+      cwd: state.cwd,
+    }, {
+      session_id: state.session?.id,
+      source: 'agentsam-cli',
+    }, { cwd: state.cwd });
+    const modified = started.input.config || config;
+    const allowed = {};
+    for (const key of ['model_key', 'reasoning_effort', 'requested_service_tier', 'auto_compact']) {
+      if (modified[key] !== undefined) allowed[key] = modified[key];
+    }
+    state.hookEffectiveConfig = { ...config, ...allowed };
+    if (state.session && Object.keys(allowed).length) persistSession(state, allowed);
+    state.hookSessionContext = started.output.additional_context || null;
+    state.hookSessionStarted = true;
+  }
+  return experience;
+}
+
 async function runInteractiveModelTurn(prompt, state) {
+  const hookExperience = await ensureShellHookExperience(state);
   const resolved = await resolveModelForTurn(state.cwd, state);
   const { preferences, model, credential } = resolved;
   const provider = createProviderAdapter({
@@ -660,7 +728,13 @@ async function runInteractiveModelTurn(prompt, state) {
       autoCompact: state.session?.auto_compact !== false,
       onCompaction: result => { if (state.session) checkpointCompaction(state, model, result); },
       promptCacheKey: state.session?.id || undefined,
+      hookRuntime: hookExperience.runtime,
+      sessionId: state.session?.id || undefined,
       runId: runtimeRunId || state.session?.id || undefined,
+      source: 'agentsam-cli',
+      ...(state.hookSessionContext ? {
+        contextItems: [{ kind: 'hook', ref: 'hook://session-start/context', priority: 96, content: state.hookSessionContext }],
+      } : {}),
       beforeRequest: (preflight) => approveModelRequest(preflight, state),
       beforeTool: (request) => approveToolExecution(request, state),
       emit(event) {
@@ -793,7 +867,7 @@ export async function dispatchShellLine(line, state = {}) {
       'help', 'exit', 'quit', 'clear', 'status', 'models', 'model',
       'whoami', 'cf', 'cloudflare', 'db', 'tunnel', 'connections',
       'connect', 'usage', 'session', 'providers', 'credentials', 'cheatsheet',
-      'settings', 'logs',
+      'settings', 'logs', 'hooks', 'hook',
       'git', 'diff', 'pwd', 'cd', 'fast', 'flex', 'standard', 'reasoning',
     ];
     if (commonVerbs.includes(bare)) {
@@ -862,6 +936,22 @@ export async function dispatchShellLine(line, state = {}) {
           state.rl?.resume?.();
         }
         break;
+      case '/hooks':
+      case '/hook': {
+        const hookCommand = args[0] || 'status';
+        await runHooks(args.length ? args : ['status'], { cwd: state.cwd, write, home: state.home, hooks: state.codeHooks });
+        if (['init', 'enable', 'disable'].includes(hookCommand)) {
+          if (state.hookExperience && state.hookSessionStarted) {
+            await state.hookExperience.runtime.dispatch('session_end', {
+              status: 'reloading_hooks',
+              elapsed_ms: state.session ? localSessionElapsedMs(state.session) : 0,
+            }, { session_id: state.session?.id, source: 'agentsam-cli' }, { cwd: state.cwd });
+          }
+          state.hookExperience = null;
+          state.hookSessionStarted = false;
+        }
+        break;
+      }
       case '/providers':
         state.rl?.pause?.();
         try {
@@ -1113,6 +1203,7 @@ export async function runShell(argv = [], options = {}) {
     session: options.session || null,
     home: options.home,
     providerFetchImpl: options.providerFetchImpl,
+    codeHooks: options.hooks || null,
     persistFooter: options.persistFooter === true,
   };
   const sub = argv[0] || '';
@@ -1201,6 +1292,20 @@ export async function runShell(argv = [], options = {}) {
     restorePaste();
     state.rl = null;
   }
+  if (state.hookExperience && state.hookSessionStarted) {
+    try {
+      await state.hookExperience.runtime.dispatch('session_end', {
+        status: interrupted ? 'interrupted' : 'paused',
+        elapsed_ms: state.session ? localSessionElapsedMs(state.session) : 0,
+        cumulative_usage: state.session?.cumulative_usage || {},
+      }, {
+        session_id: state.session?.id,
+        source: 'agentsam-cli',
+      }, { cwd: state.cwd });
+    } catch (error) {
+      writeLine(write, `  Hook cleanup warning: ${error?.message || error}`);
+    }
+  }
   if (state.session) {
     const activeElapsedMs = localSessionElapsedMs(state.session);
     persistSession(state, {

package/src/errors/diagnostic.js

@@ -181,16 +181,16 @@ export function diagnosticFromError(error, fallback = {}) {
   if (error?.diagnostic) return error.diagnostic;
   const envelope = error?.envelope || (error?.ok === false && error?.schema_version ? error : null);
   if (envelope) return legacyDiagnosticFromEnvelope(envelope, fallback);
-  return Object.freeze({
-    schema_version: 1,
-    source: fallback.source || 'agentsam',
-    kind: fallback.kind || 'runtime_error',
-    code: clean(error?.code || fallback.code) || 'runtime_error',
-    message: redactString(error?.message || error || fallback.message || 'Unknown error', 4_000),
-    http_status: Number(error?.status || fallback.status || 0) || null,
-    retriable: Boolean(fallback.retriable),
-    retry_strategy: fallback.retry_strategy || 'inspect_error',
+  const canonical = normalizeError(error, {
+    reason: fallback.reason,
+    domain: fallback.domain || 'runtime',
+    stage: fallback.stage,
+    feature: fallback.feature,
+    failure_behavior: fallback.failure_behavior,
+    side_effect_state: fallback.side_effect_state,
+    source: { kind: 'runtime', name: fallback.source || 'agentsam-sdk' },
   });
+  return legacyDiagnosticFromEnvelope(canonical, fallback);
 }
 
 export function renderDiagnosticError(error) {

package/src/go/container.js

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { probeGoDeploymentWithRetry } from './cloudflare.js';
+import { probeGoDeploymentWithRetry } from './probe.js';
 
 function runDocker(args, { productRoot, spawn = spawnSync } = {}) {
   const res = spawn('docker', args, {

package/src/go/contract.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { DEFAULT_PRODUCT } from './discover.js';
 
 const PACKAGE_TEMPLATE = {
@@ -90,12 +91,16 @@ function rel(root, file) {
   return path.relative(root, file).split(path.sep).join('/');
 }
 
-export function preflightToolchain({ requireDocker = false, productRoot = null } = {}) {
+export function preflightToolchain({
+  requireDocker = false,
+  productRoot = null,
+  spawn = spawnSync,
+} = {}) {
   const checks = [];
   const push = (id, ok, detail = '') => checks.push({ id, ok, detail });
 
   try {
-    const v = spawnSync('go', ['version'], { encoding: 'utf8' });
+    const v = spawn('go', ['version'], { encoding: 'utf8' });
     push('go', v.status === 0, (v.stdout || v.stderr || '').trim());
   } catch (e) {
     push('go', false, e.message);
@@ -103,7 +108,7 @@ export function preflightToolchain({ requireDocker = false, productRoot = null }
 
   const wranglerBin = resolveWranglerBin(productRoot);
   try {
-    const v = spawnSync(wranglerBin.command, wranglerBin.args.concat(['--version']), {
+    const v = spawn(wranglerBin.command, wranglerBin.args.concat(['--version']), {
       encoding: 'utf8',
       cwd: productRoot || process.cwd(),
     });
@@ -112,33 +117,71 @@ export function preflightToolchain({ requireDocker = false, productRoot = null }
     push('wrangler', false, e.message);
   }
 
-  try {
-    const v = spawnSync('docker', ['info'], { encoding: 'utf8' });
-    push('docker', v.status === 0, v.status === 0 ? 'available' : (v.stderr || 'unavailable').trim().slice(0, 200));
-  } catch (e) {
-    push('docker', false, e.message);
+  // Docker is capability-gated.
+  //
+  // A caller that does not require a container must not execute
+  // `docker info` merely to discover that Docker is optional.
+  //
+  // Besides wasting work, Docker Desktop may be installed while its
+  // daemon is stopped/unhealthy, and `docker info` can block for a
+  // significant period.
+  if (requireDocker) {
+    try {
+      const v = spawn('docker', ['info'], {
+        encoding: 'utf8',
+        timeout: 8000,
+      });
+      push(
+        'docker',
+        v.status === 0,
+        v.status === 0
+          ? 'available'
+          : (v.stderr || 'unavailable').trim().slice(0, 200),
+      );
+    } catch (e) {
+      push('docker', false, e.message);
+    }
+  } else {
+    push('docker', true, 'skipped:not-required');
   }
 
-  const failed = checks.filter((c) => {
-    if (c.ok) return false;
-    if (c.id === 'docker' && !requireDocker) return false;
-    return true;
-  });
+  const failed = checks.filter((c) => !c.ok);
   return { ok: failed.length === 0, checks, failed, wrangler: wranglerBin };
 }
 
-function resolveWranglerBin(productRoot) {
+export function resolveWranglerBin(productRoot) {
+  if (productRoot) {
+    try {
+      const req = createRequire(path.join(productRoot, 'package.json'));
+      const resolved = req.resolve('wrangler');
+      if (resolved) {
+        return { command: process.execPath, args: [resolved], source: 'package_dependency' };
+      }
+    } catch {
+      // Fall through to explicit paths / pinned npx fallback.
+    }
+  }
+
   const candidates = [];
   if (productRoot) {
-    candidates.push(path.join(productRoot, 'node_modules', 'wrangler', 'bin', 'wrangler.js'));
     candidates.push(path.join(productRoot, 'node_modules', '.bin', 'wrangler'));
   }
   candidates.push(path.join(process.cwd(), 'node_modules', '.bin', 'wrangler'));
   for (const candidate of candidates) {
     if (fs.existsSync(candidate)) {
-      if (candidate.endsWith('.js')) return { command: process.execPath, args: [candidate] };
-      return { command: candidate, args: [] };
+      return { command: candidate, args: [], source: 'local_bin' };
+    }
+  }
+
+  let requested = 'wrangler';
+  if (productRoot) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(path.join(productRoot, 'package.json'), 'utf8'));
+      const version = pkg.dependencies?.wrangler || pkg.devDependencies?.wrangler || '';
+      if (version) requested = 'wrangler@' + version;
+    } catch {
+      // Keep generic fallback only when package metadata is unavailable.
     }
   }
-  return { command: 'npx', args: ['--yes', 'wrangler'] };
+  return { command: 'npx', args: ['--yes', requested], source: 'npx_fallback' };
 }

package/src/go/discover.js

@@ -180,10 +180,6 @@ export function probeGoToolchain() {
 }
 
 export function resolveGoStateRoot(discovery, cwd = process.cwd()) {
-  const origin = discovery?.runtime?.origin || null;
-  if (origin === 'repository' || origin === 'sdk_development_tree') {
-    return discovery.runtime.productRoot;
-  }
   return repositoryRoot(cwd);
 }
 

package/src/go/index.js

@@ -1,7 +1,19 @@
 export { discoverGoRuntime, resolveProductRoot, resolveGoStateRoot, probeGoToolchain, DEFAULT_PRODUCT, SDK_ROOT } from './discover.js';
 export { ensureProductContract, readProductManifest, preflightToolchain } from './contract.js';
 export { buildGoProduct, runGoBuild, runGoTests, runGoVet } from './build.js';
-export { deployGoCloudflare, resolveWranglerIdentity, probeGoDeployment, probeGoDeploymentWithRetry, readLatestWranglerDeployment } from './cloudflare.js';
+export {
+  deployGoCloudflare,
+  resolveConfiguredDeploymentUrl,
+  resolveWranglerIdentity,
+  readLatestWranglerDeployment,
+  extractWorkersDevUrl,
+  guessWorkersDevUrl,
+} from './providers/cloudflare.js';
+
+export {
+  probeGoDeployment,
+  probeGoDeploymentWithRetry,
+} from './probe.js';
 export { verifyGoContainer } from './container.js';
 export { verifyGoProduct } from './verify.js';
 export {