@inneranimalmedia/agentsam-sdk 2.4.1 → 2.6.0

package/src/knowledge/context-pack.js

@@ -1,12 +1,23 @@
 export function createContextPack({ queryId, query, hits = [], diagnostics = {}, confidence = "unknown" }) {
   const normalizedHits = hits.map((hit) => Object.freeze({ stale: false, reasons: [], metadata: {}, ...hit }));
+  const estimatedTokens = estimateTokens(normalizedHits);
+  const chars = normalizedHits.reduce((sum, hit) => sum + String(hit.content || "").length, 0);
+  const considered = Number.isInteger(diagnostics.sources_considered) ? diagnostics.sources_considered : normalizedHits.length;
+  const deferred = Number.isInteger(diagnostics.sources_deferred) ? diagnostics.sources_deferred : Math.max(0, considered - normalizedHits.length);
   return Object.freeze({
     query_id: queryId,
     query,
     hits: normalizedHits,
-    estimated_tokens: estimateTokens(normalizedHits),
+    estimated_tokens: estimatedTokens,
     confidence,
     diagnostics: Object.freeze({ ...diagnostics }),
+    receipt: Object.freeze({
+      chars,
+      estimated_tokens: estimatedTokens,
+      sources_considered: considered,
+      sources_included: normalizedHits.length,
+      sources_deferred: deferred,
+    }),
   });
 }
 

package/src/knowledge/contracts.js

@@ -1,5 +1,7 @@
 /** Provider-neutral AgentSam Knowledge SDK contracts and validators. */
 
+import { normalizeResultPolicy } from '../context/result-policy.js';
+
 export const KNOWLEDGE_OPERATIONS = Object.freeze({
   RETRIEVE: "knowledge.retrieve",
   INDEX: "knowledge.index",
@@ -9,10 +11,13 @@ export function assertRetrievalQuery(value) {
   if (!value || typeof value !== "object") throw new TypeError("RetrievalQuery must be an object");
   if (!String(value.text || "").trim()) throw new TypeError("RetrievalQuery.text is required");
   if (value.workspace_id != null && !String(value.workspace_id).trim()) throw new TypeError("RetrievalQuery.workspace_id must be non-empty when present");
-  const topK = value.top_k ?? 12;
-  if (!Number.isInteger(topK) || topK < 1 || topK > 100) throw new RangeError("top_k must be 1..100");
-  if (!Number.isInteger(value.token_budget ?? 8000) || (value.token_budget ?? 8000) < 256) throw new RangeError("token_budget must be at least 256");
-  return { ...value, top_k: topK, token_budget: value.token_budget ?? 8000 };
+  const resultPolicy = normalizeResultPolicy(value.result_policy || {});
+  const topK = value.top_k ?? resultPolicy.max_items;
+  if (!Number.isInteger(topK) || topK < 1 || topK > resultPolicy.max_items) throw new RangeError(`top_k must be 1..${resultPolicy.max_items} under the active result policy`);
+  const defaultTokenBudget = Math.max(256, Math.floor(resultPolicy.max_chars / 4));
+  const tokenBudget = value.token_budget ?? defaultTokenBudget;
+  if (!Number.isInteger(tokenBudget) || tokenBudget < 256 || tokenBudget > defaultTokenBudget) throw new RangeError(`token_budget must be 256..${defaultTokenBudget} under the active result policy`);
+  return { ...value, result_policy: resultPolicy, top_k: topK, token_budget: tokenBudget };
 }
 
 export function assertContextPack(value) {

package/src/knowledge/engine.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { validateConfig, fingerprint, scopeKey, cacheNamespace, gitEvidence } from './config.js';
 import { PARSER, inventory, readSource, parseSource } from './source.js';
 import { createContextPack } from './context-pack.js';
+import { normalizeResultPolicy } from '../context/result-policy.js';
 
 export const embeddingProfileId = profile => fingerprint({ ...profile, input_format: 'agentsam-code-content:1' });
 export function validateVector(vector, dimensions) {
@@ -72,10 +73,13 @@ export async function runIndex({ root, config, store, embedder, embed = false, m
   return { ...receipt, generation_id: generation.id, published: true };
 }
 
-export async function retrieve({ store, config: input, text, semantic = false, embedder, topK = 8, tokenBudget = 8000, generationId }) {
+export async function retrieve({ store, config: input, text, semantic = false, embedder, topK = 8, tokenBudget = 6000, generationId, resultPolicy: requestedResultPolicy }) {
   const config = validateConfig(input);
   if (typeof text !== 'string' || !text.trim()) throw new Error('A nonempty query is required.');
-  if (!Number.isInteger(topK) || topK < 1 || topK > 100 || !Number.isInteger(tokenBudget) || tokenBudget < 256) throw new Error('topK must be 1..100 and tokenBudget at least 256.');
+  const resultPolicy = normalizeResultPolicy(requestedResultPolicy || {});
+  if (!Number.isInteger(topK) || topK < 1 || topK > resultPolicy.max_items) throw new Error(`topK must be 1..${resultPolicy.max_items} under the active result policy.`);
+  const maxTokenBudget = Math.max(256, Math.floor(resultPolicy.max_chars / 4));
+  if (!Number.isInteger(tokenBudget) || tokenBudget < 256 || tokenBudget > maxTokenBudget) throw new Error(`tokenBudget must be 256..${maxTokenBudget} under the active result policy.`);
   const generation = generationId ? await store?.getGeneration(scopeKey(config), generationId) : await store?.active(scopeKey(config));
   if (!generation) throw new Error('No generation found for this repository/scope. Run agentsam index run.');
   let queryVector;
@@ -113,6 +117,6 @@ export async function retrieve({ store, config: input, text, semantic = false, e
       metadata: { generation_id: generation.id, symbol: hit.symbol, content_hash: hit.content_hash, freshness: 'working tree not checked' } }); estimatedTokens += tokens;
     if (hits.length === topK) break;
   }
-  return createContextPack({ queryId: randomUUID(), query: { text, top_k: topK, token_budget: tokenBudget }, hits,
+  return createContextPack({ queryId: randomUUID(), query: { text, top_k: topK, token_budget: tokenBudget, result_policy: resultPolicy }, hits,
     diagnostics: { generation_id: generation.id, source_hash: generation.source_hash, scope: generation.config.scope, mode: semantic ? 'semantic-exact' : 'lexical', freshness: 'snapshot; working tree not checked' } });
 }

package/src/knowledge/service/server.js

@@ -30,7 +30,7 @@ function normalizeRequest(body, repositories, allowEmbeddings) {
   };
   const request = { ...body, embed: body.embed ?? false, semantic: body.semantic ?? false,
     max_inputs: bounded('max_inputs', 100, 0, 1000), max_characters: bounded('max_characters', 200000, 0, 2000000),
-    top_k: bounded('top_k', 8, 1, 100), token_budget: bounded('token_budget', 8000, 256, 32000) };
+    top_k: bounded('top_k', 8, 1, 8), token_budget: bounded('token_budget', 6000, 256, 6000) };
   const config = structuredClone(repo.config);
   if (body.scope !== undefined) config.scope.name = body.scope;
   if (body.include !== undefined) config.scope.include = body.include;

package/src/lib/account-session.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveSdkKey } from '../../packages/identity/src/contracts/auth-config.js';
+
+export const ACCOUNT_SESSION_SCHEMA = 'agentsam-account-session-v1';
+
+function clean(value) { return value == null ? '' : String(value).trim(); }
+function homeDirectory(options = {}) {
+  return path.resolve(clean(options.home) || clean(options.env?.HOME) || clean(options.env?.USERPROFILE) || os.homedir());
+}
+
+export function accountSessionPath(options = {}) {
+  return path.join(homeDirectory(options), '.agentsam', 'auth', 'session.json');
+}
+
+export function readAccountSession(options = {}) {
+  const filename = accountSessionPath(options);
+  if (!fs.existsSync(filename)) return null;
+  try {
+    const stat = fs.statSync(filename);
+    if (!stat.isFile()) return null;
+    if (process.platform !== 'win32' && (stat.mode & 0o077) !== 0) return null;
+    const parsed = JSON.parse(fs.readFileSync(filename, 'utf8'));
+    if (parsed?.schema_version !== ACCOUNT_SESSION_SCHEMA) return null;
+    const token = clean(parsed.sdk_key);
+    if (!token.startsWith('sdk_')) return null;
+    return {
+      schema_version: ACCOUNT_SESSION_SCHEMA,
+      sdk_key: token,
+      user_id: clean(parsed.user_id) || null,
+      account_id: clean(parsed.account_id) || null,
+      email: clean(parsed.email) || null,
+      created_at: clean(parsed.created_at) || null,
+      updated_at: clean(parsed.updated_at) || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveAccountSession(session = {}, options = {}) {
+  const token = clean(session.sdk_key || session.access_token);
+  if (!token.startsWith('sdk_')) throw new Error('account_session_sdk_key_required');
+  const filename = accountSessionPath(options);
+  const dir = path.dirname(filename);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(dir, 0o700); } catch { /* best effort */ }
+  }
+  const previous = readAccountSession(options);
+  const now = new Date().toISOString();
+  const value = {
+    schema_version: ACCOUNT_SESSION_SCHEMA,
+    sdk_key: token,
+    user_id: clean(session.user_id) || previous?.user_id || null,
+    account_id: clean(session.account_id) || previous?.account_id || null,
+    email: clean(session.email) || previous?.email || null,
+    created_at: previous?.created_at || now,
+    updated_at: now,
+  };
+  const temp = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(temp, 0o600); } catch { /* best effort */ }
+  }
+  fs.renameSync(temp, filename);
+  return { ...value };
+}
+
+export function clearAccountSession(options = {}) {
+  const filename = accountSessionPath(options);
+  if (!fs.existsSync(filename)) return false;
+  fs.rmSync(filename, { force: true });
+  return true;
+}
+
+export function resolveAccountSdkKey(options = {}) {
+  const env = options.env || process.env;
+  const explicit = clean(options.explicit);
+  const fromEnv = resolveSdkKey(env, explicit);
+  if (fromEnv) return { value: fromEnv, source: explicit ? 'explicit' : 'environment' };
+  const session = readAccountSession({ ...options, env });
+  return session?.sdk_key
+    ? { value: session.sdk_key, source: 'agentsam_account_session', session }
+    : { value: '', source: null, session: null };
+}
+
+export function describeAccountSession(options = {}) {
+  const resolved = resolveAccountSdkKey(options);
+  return {
+    configured: Boolean(resolved.value),
+    source: resolved.source,
+    user_id: resolved.session?.user_id || null,
+    account_id: resolved.session?.account_id || null,
+    email: resolved.session?.email || null,
+  };
+}

package/src/lib/agent-instructions.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { findProjectRules } from './project-rules.js';
+
+export const AGENT_RUNTIME_FILENAME = 'AGENTSAM.md';
+export const AGENT_INSTRUCTION_PRECEDENCE = Object.freeze(['AGENTSAM.md', '.agentsamrules']);
+
+function sha256(value) {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function findUp(startDir, filename) {
+  let dir = path.resolve(startDir);
+  for (let i = 0; i < 16; i += 1) {
+    const candidate = path.join(dir, filename);
+    if (fs.existsSync(candidate)) return candidate;
+    const boundary = fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json'));
+    if (boundary) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function findAgentRuntimeContract(startDir = process.cwd()) {
+  return findUp(startDir, AGENT_RUNTIME_FILENAME);
+}
+
+export function compileAgentInstructions(startDir = process.cwd(), options = {}) {
+  const maxChars = Number(options.maxChars ?? 24_000);
+  if (!Number.isInteger(maxChars) || maxChars < 1) throw new RangeError('agent instructions maxChars must be a positive integer');
+
+  const runtimePath = options.runtimeFilename ? path.resolve(options.runtimeFilename) : findAgentRuntimeContract(startDir);
+  const projectPath = options.projectFilename ? path.resolve(options.projectFilename) : findProjectRules(startDir);
+  const descriptors = [
+    { id: 'runtime', filename: AGENT_RUNTIME_FILENAME, path: runtimePath },
+    { id: 'project', filename: '.agentsamrules', path: projectPath },
+  ];
+  const sections = [];
+  const sources = [];
+  let sourceChars = 0;
+
+  for (const descriptor of descriptors) {
+    if (!descriptor.path || !fs.existsSync(descriptor.path)) continue;
+    const source = fs.readFileSync(descriptor.path, 'utf8');
+    sourceChars += source.length;
+    sources.push(Object.freeze({
+      id: descriptor.id,
+      filename: descriptor.filename,
+      path: descriptor.path,
+      chars: source.length,
+      hash: sha256(source),
+    }));
+    sections.push(`<!-- agentsam:${descriptor.id}:${descriptor.filename} -->\n${source.trim()}\n`);
+  }
+
+  const combined = sections.join('\n');
+  const truncated = combined.length > maxChars;
+  const content = truncated ? `${combined.slice(0, Math.max(0, maxChars - 1))}…` : combined;
+  return Object.freeze({
+    found: sources.length > 0,
+    path: projectPath || runtimePath || null,
+    content,
+    chars: content.length,
+    source_chars: sourceChars,
+    truncated,
+    hash: combined ? sha256(combined) : null,
+    precedence: AGENT_INSTRUCTION_PRECEDENCE,
+    sources: Object.freeze(sources),
+  });
+}

package/src/lib/auth.js

@@ -5,6 +5,7 @@ import http from 'node:http';
 import { randomBytes } from 'node:crypto';
 import { postJson } from './core-client.js';
 import { promptToOpenUrl } from './open-url.js';
+import { saveAccountSession } from './account-session.js';
 
 function randomState() {
   return randomBytes(16).toString('hex');
@@ -63,5 +64,8 @@ export async function authenticateViaBrowser() {
 
   const code = await codePromise;
   const session = await postJson('/api/sdk/auth/exchange', { code, state });
+  if (String(session?.access_token || '').trim().startsWith('sdk_')) {
+    saveAccountSession(session);
+  }
   return session;
 }

package/src/lib/bridge-client.js

@@ -1,17 +1,19 @@
-const DEFAULT_BASE_URL = 'https://inneranimalmedia.com';
+import {
+  resolveBridgeKey as resolveContractBridgeKey,
+  resolveIamOrigin,
+} from '../../packages/identity/src/contracts/auth-config.js';
 
 function clean(value) {
   return value == null ? '' : String(value).trim();
 }
 
 export function resolveAgentSamBaseUrl(env = process.env, explicit = '') {
-  return clean(
-    explicit || env.AGENTSAM_BASE_URL || env.AGENTSAM_CORE_URL || env.IAM_CORE_URL || DEFAULT_BASE_URL,
-  ).replace(/\/$/, '');
+  const compatibilityBase = env?.AGENTSAM_BASE_URL || env?.AGENTSAM_CORE_URL || env?.IAM_CORE_URL || '';
+  return resolveIamOrigin(env, explicit || env?.IAM_ORIGIN || compatibilityBase);
 }
 
 export function resolveBridgeKey(env = process.env, explicit = '') {
-  return clean(explicit || env.AGENTSAM_BRIDGE_KEY);
+  return resolveContractBridgeKey(env, explicit);
 }
 
 /**

package/src/lib/cli-preferences.js

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { getProjectName, tryReadProjectConfig } from './project-config.js';
+
+export const CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v2';
+export const LEGACY_CLI_PREFERENCES_SCHEMA = 'agentsam-cli-preferences-v1';
+
+function readJson(filename) {
+  try { return JSON.parse(fs.readFileSync(filename, 'utf8')); }
+  catch { return null; }
+}
+
+function gitValue(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return result.status === 0 ? String(result.stdout || '').trim() : '';
+}
+
+export function findCliProjectRoot(startDir = process.cwd()) {
+  const cwd = path.resolve(startDir);
+  const gitRoot = gitValue(cwd, ['rev-parse', '--show-toplevel']);
+  if (gitRoot) return path.resolve(gitRoot);
+  let dir = cwd;
+  for (let i = 0; i < 16; i += 1) {
+    if (fs.existsSync(path.join(dir, '.agentsam', 'cli.json')) || fs.existsSync(path.join(dir, '.agentsam', 'config.json')) || fs.existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return cwd;
+}
+
+export function detectCliProject(startDir = process.cwd()) {
+  const root = findCliProjectRoot(startDir);
+  const config = tryReadProjectConfig(root) || {};
+  const pkg = readJson(path.join(root, 'package.json')) || {};
+  const branch = gitValue(root, ['branch', '--show-current']);
+  const remote = gitValue(root, ['config', '--get', 'remote.origin.url']);
+  const project = String(getProjectName(config, pkg.name || path.basename(root)));
+  const website = String(pkg.homepage || '').trim();
+  return { root, project, branch, remote, website, configured: Boolean(getProjectName(config)) };
+}
+
+export function cliPreferencesPath(root) { return path.join(path.resolve(root), '.agentsam', 'cli.json'); }
+
+function normalizePreferences(value = {}) {
+  return {
+    schemaVersion: CLI_PREFERENCES_SCHEMA,
+    trustedDirectory: value.trustedDirectory === true,
+    runtime: value.runtime || 'local',
+    terminal: value.terminal || '',
+    modelPreference: value.modelPreference || 'auto',
+    reasoningEffort: value.reasoningEffort || 'auto',
+    serviceTier: value.serviceTier || 'default',
+    modelAuthority: 'preference-only',
+    updatedAt: value.updatedAt || null,
+  };
+}
+
+export function readCliPreferences(root) {
+  const value = readJson(cliPreferencesPath(root));
+  if (!value) return null;
+  if (value.schemaVersion !== CLI_PREFERENCES_SCHEMA && value.schemaVersion !== LEGACY_CLI_PREFERENCES_SCHEMA) return null;
+  return normalizePreferences(value);
+}
+
+export function writeCliPreferences(root, value = {}) {
+  const filename = cliPreferencesPath(root);
+  fs.mkdirSync(path.dirname(filename), { recursive: true });
+  const previous = readCliPreferences(root) || {};
+  const next = normalizePreferences({ ...previous, ...value, updatedAt: new Date().toISOString() });
+  fs.writeFileSync(filename, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+export function updateCliPreferences(root, patch = {}) {
+  return writeCliPreferences(root, { ...(readCliPreferences(root) || {}), ...patch });
+}

package/src/lib/core-client.js

@@ -1,16 +1,16 @@
+import { resolveIamOrigin } from '../../packages/identity/src/contracts/auth-config.js';
+
 /**
  * IAM CORE client — SDK is a delivery mechanism; intelligence lives server-side.
  *
- * Default base URL https://inneranimalmedia.com is CORRECT-AS-DESIGNED for
- * multi-tenant client serving (thin client → IAM CORE). Override with
- * IAM_CORE_URL / AGENTSAM_CORE_URL. Without a CORE backend, consumers get
- * scaffold/local CLI only.
+ * IAM_ORIGIN is the canonical platform authority/API origin. During the
+ * migration window IAM_CORE_URL / AGENTSAM_CORE_URL remain compatibility-only
+ * fallbacks. Without a CORE backend, consumers get scaffold/local CLI only.
  */
 
-const DEFAULT_CORE = 'https://inneranimalmedia.com';
-
-export function coreBaseUrl() {
-  return (process.env.IAM_CORE_URL || process.env.AGENTSAM_CORE_URL || DEFAULT_CORE).replace(/\/$/, '');
+export function coreBaseUrl(env = process.env) {
+  const explicit = env?.IAM_ORIGIN || env?.IAM_CORE_URL || env?.AGENTSAM_CORE_URL || '';
+  return resolveIamOrigin(env, explicit);
 }
 
 export async function postJson(path, body, token) {

package/src/lib/deploy/git-guard.js

@@ -0,0 +1,69 @@
+/**
+ * Production Wrangler deploys are allowed only from a clean main that matches origin/main.
+ * Dry-run / plan may run from a feature branch. Never from /private/tmp.
+ */
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const BLOCKED_BRANCH_PREFIXES = ['feat/', 'fix/', 'chore/', 'release/'];
+
+function git(cwd, args) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return {
+    status: r.status,
+    stdout: String(r.stdout || '').trim(),
+    stderr: String(r.stderr || '').trim(),
+  };
+}
+
+export function inspectDeployGit(cwd = process.cwd()) {
+  const root = git(cwd, ['rev-parse', '--show-toplevel']);
+  const branch = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const head = git(cwd, ['rev-parse', 'HEAD']);
+  const origin = git(cwd, ['rev-parse', 'origin/main']);
+  const porcelain = git(cwd, ['status', '--porcelain']);
+  const detached = branch.stdout === 'HEAD';
+  const repoRoot = root.stdout || path.resolve(cwd);
+  return {
+    ok: root.status === 0,
+    repoRoot,
+    branch: branch.stdout,
+    detached,
+    head: head.stdout,
+    originMain: origin.stdout,
+    dirty: Boolean(porcelain.stdout),
+    tmpCheckout: repoRoot.includes('/private/tmp/') || repoRoot.includes('/tmp/'),
+  };
+}
+
+export function productionDeployBlockedReason(info) {
+  if (!info?.ok) return 'not a git checkout';
+  if (info.tmpCheckout) return 'refusing production deploy from a temporary checkout';
+  if (info.detached) return 'refusing production deploy from detached HEAD';
+  if (info.branch !== 'main') {
+    return `refusing production deploy from ${info.branch}; origin/main only`;
+  }
+  for (const prefix of BLOCKED_BRANCH_PREFIXES) {
+    if (info.branch.startsWith(prefix)) {
+      return `refusing production deploy from ${info.branch}`;
+    }
+  }
+  if (!info.originMain) return 'origin/main is missing; fetch before deploying';
+  if (info.head !== info.originMain) {
+    return `HEAD (${info.head.slice(0, 12)}) != origin/main (${info.originMain.slice(0, 12)})`;
+  }
+  if (info.dirty) return 'working tree is not clean';
+  return null;
+}
+
+export function assertProductionDeployAllowed(cwd = process.cwd()) {
+  const info = inspectDeployGit(cwd);
+  const reason = productionDeployBlockedReason(info);
+  if (reason) {
+    const err = new Error(reason);
+    err.code = 'production_deploy_refused';
+    err.git = info;
+    throw err;
+  }
+  return info;
+}

package/src/lib/deploy/health.js

@@ -0,0 +1,57 @@
+export const DEFAULT_HEALTH_ORIGIN = 'https://agentsam.inneranimalmedia.com';
+export const HEALTH_USER_AGENT = 'AgentSam-deploy-health/1';
+
+export function parseWranglerVersionId(output = '') {
+  const text = String(output || '');
+  const m = text.match(/Current Version ID:\s*([0-9a-f-]{36})/i)
+    || text.match(/Version ID:\s*([0-9a-f-]{36})/i);
+  return m ? m[1] : null;
+}
+
+export function resolveHealthOrigin({ env = process.env, wranglerConfigText = '' } = {}) {
+  const fromEnv = String(env.PRODUCT_HOST || env.AGENTSAM_HEALTH_ORIGIN || '').trim();
+  if (fromEnv) return fromEnv.replace(/\/+$/, '');
+  const m = String(wranglerConfigText || '').match(/"pattern"\s*:\s*"([^"]+)"/);
+  if (m) {
+    const host = m[1].trim();
+    if (host.startsWith('http://') || host.startsWith('https://')) return host.replace(/\/+$/, '');
+    return `https://${host.replace(/\/+$/, '')}`;
+  }
+  return DEFAULT_HEALTH_ORIGIN;
+}
+
+export async function probeDeployHealth(origin, { fetchImpl = globalThis.fetch, paths = ['/health', '/'] } = {}) {
+  const results = {};
+  for (const p of paths) {
+    const url = `${String(origin).replace(/\/+$/, '')}${p}`;
+    try {
+      const res = await fetchImpl(url, {
+        redirect: 'manual',
+        headers: {
+          'User-Agent': HEALTH_USER_AGENT,
+          Accept: 'application/json,text/html,*/*',
+        },
+      });
+      let body = null;
+      if (p === '/health') {
+        try { body = await res.json(); } catch { body = null; }
+      }
+      const ok = res.status >= 200 && res.status < 400;
+      results[p] = {
+        status: res.status,
+        ok,
+        ...(body && typeof body === 'object' ? {
+          appOk: body.ok === true,
+          cloudflareConfigured: Boolean(body?.connections?.cloudflare?.configured),
+        } : {}),
+      };
+    } catch (err) {
+      results[p] = { status: 0, ok: false, error: err.message };
+    }
+  }
+  return {
+    origin,
+    results,
+    ok: Object.values(results).every((r) => r.ok),
+  };
+}