@geraldmaron/construct 1.2.3 → 1.3.0

package/apps/chat/engine/models.mjs

@@ -1,122 +0,0 @@
-/**
- * apps/chat/engine/models.mjs — model and provider resolution for the owned loop.
- *
- * The owned loop is provider-agnostic (ADR-0041/ADR-0003): model choice is never
- * hardcoded. This module reuses the core router (lib/model-router.mjs) so the chat
- * surface, the orchestration worker, and the embedded contract all resolve models
- * the same way. resolveChatModelSelection validates CX_MODEL pins against live
- * credential detection; resolveChatModelSelectionAsync also probes Copilot session
- * exchange so a bad token falls through before the first turn.
- */
-
-import {
-  getProviderModelCatalog,
-  describeModelFamily,
-  resolveValidatedChatModel,
-  isChatModelAvailable,
-} from '../../../lib/model-router.mjs';
-import { resolveFirstSecret } from '../../../lib/providers/secret-resolver.mjs';
-
-export function listChatModels({ env = process.env, cwd = process.cwd(), activeModelId = null } = {}) {
-  const { providers } = getProviderModelCatalog({ env, cwd, activeModelId });
-  const models = [];
-  const seen = new Set();
-  for (const provider of providers) {
-    for (const tier of ['reasoning', 'standard', 'fast']) {
-      for (const id of provider.options?.[tier] || []) {
-        if (seen.has(id)) continue;
-        seen.add(id);
-        models.push({
-          id,
-          label: id,
-          provider: provider.id,
-          configured: provider.configured,
-          local: provider.local === true,
-          suitable: true,
-          tier,
-          available: isChatModelAvailable(id, { env }).ok,
-        });
-      }
-    }
-  }
-  return models.sort((a, b) => Number(b.configured) - Number(a.configured) || a.id.localeCompare(b.id));
-}
-
-export { refreshLiveOpenRouterCatalog } from '../../../lib/models/catalog.mjs';
-
-export function recommendChatModel({ env = process.env } = {}) {
-  const { providers } = getProviderModelCatalog({ env });
-  const configured = providers.find((p) => p.configured);
-  if (!configured) return null;
-  const id = configured.tiers?.standard || configured.tiers?.fast || null;
-  if (!id) return null;
-  const check = isChatModelAvailable(id, { env });
-  if (!check.ok) return null;
-  return { id, reason: `configured provider ${configured.label}` };
-}
-
-export function resolveChatModelSelection({ env = process.env, requested = null, excludeFamilies = [] } = {}) {
-  return resolveValidatedChatModel({ env, requested, excludeFamilies });
-}
-
-export async function resolveFreeOpenRouterModel({ env = process.env, tier = 'standard', exclude = [] } = {}) {
-  const apiKey = resolveFirstSecret(['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'], { env });
-  if (!apiKey) return null;
-  const excludeSet = new Set(Array.isArray(exclude) ? exclude : []);
-  const { pollFreeModels, topForTier } = await import('../../../lib/model-free-selector.mjs');
-  const freeModels = await pollFreeModels(apiKey);
-  for (const candidate of topForTier(freeModels, tier, 20)) {
-    const modelId = candidate.id.startsWith('openrouter/') ? candidate.id : `openrouter/${candidate.id}`;
-    if (excludeSet.has(modelId)) continue;
-    if (isChatModelAvailable(modelId, { env }).ok) return modelId;
-  }
-  return null;
-}
-
-export async function resolveSessionModel(session, { env = process.env, exclude = [], tier = 'standard' } = {}) {
-  if (session?.modelMode === 'free-router') {
-    const merged = [...new Set([...getExcludeFromSession(session), ...exclude])];
-    return resolveFreeOpenRouterModel({ env, tier, exclude: merged });
-  }
-  return session?.model || session?.savedModel || null;
-}
-
-function getExcludeFromSession(session) {
-  if (!session?.failedModels) return [];
-  return session.failedModels instanceof Set ? [...session.failedModels] : [];
-}
-
-export async function resolveChatModelSelectionAsync({
-  env = process.env,
-  requested = null,
-  fetchImpl = fetch,
-} = {}) {
-  let resolution = resolveValidatedChatModel({ env, requested });
-  if (!resolution.id?.startsWith('github-copilot/')) return resolution;
-
-  const { preflightCopilotSession } = await import('../../../lib/providers/copilot-auth.mjs');
-  const probe = await preflightCopilotSession({ fetchImpl });
-  if (probe.ok) return resolution;
-
-  const fallback = resolveValidatedChatModel({ env, requested: null, excludeFamilies: ['github-copilot'] });
-  if (fallback.id) {
-    return {
-      ...fallback,
-      notice: `GitHub Copilot session failed (${probe.message}). Using ${fallback.id}.`,
-    };
-  }
-  return {
-    id: null,
-    source: null,
-    notice: `GitHub Copilot session failed: ${probe.message}`,
-    rejected: resolution.rejected,
-  };
-}
-
-export function resolveChatModel(opts = {}) {
-  return resolveChatModelSelection(opts).id;
-}
-
-export function describeChatModel(modelId, { env = process.env } = {}) {
-  return describeModelFamily(modelId, { env });
-}

package/apps/chat/engine/provider-adapters.mjs

@@ -1,171 +0,0 @@
-/**
- * apps/chat/engine/provider-adapters.mjs — centralized provider execution adapters
- * (construct-6zga.1.3).
- *
- * One registry, keyed by provider group, owns provider execution. Each adapter
- * owns its own credential resolution, base URL, native model-id translation, auth
- * scheme, and AI SDK provider construction; the dispatcher does no
- * provider/model-prefix behavior branch — it extracts the structural provider
- * group (the model id's first segment, the same identity lib/models keys on) and
- * looks the adapter up. Adding a compatible provider is a registry entry plus
- * matrix fixtures, never a dispatch edit.
- *
- * Public model ids are preserved: the native id handed to the SDK is the model id
- * with its group segment stripped, so anthropic/claude-x → claude-x and
- * openrouter/anthropic/claude-x → anthropic/claude-x (OpenRouter's own id).
- * Credentials resolve through the shared secret resolver (env, dotenv, shell rc,
- * 1Password op:// refs); a missing key fails fast with a remediation hint.
- */
-import { resolveFirstSecret } from '../../../lib/providers/secret-resolver.mjs';
-import { providerGroupForModel } from '../../../lib/models/execution-capability-profile.mjs';
-
-const OPENROUTER_BASE = 'https://openrouter.ai/api/v1';
-
-function envKey(env, ...names) {
-  return resolveFirstSecret(names, { env });
-}
-
-function missingKey(provider, varName) {
-  const err = new Error(`No credentials for ${provider}: set ${varName} (or run \`construct creds\`) and retry.`);
-  err.code = 'PROVIDER_KEY_MISSING';
-  return err;
-}
-
-// Adapter descriptors. `describe` is the serializable contract (auth scheme,
-// protocol, credential env, base URL source) for tracing and conformance fixtures;
-// `createModel` builds the AI SDK handle from the native id. The @ai-sdk/* imports
-// stay lazy so the zero-dep core never loads them.
-
-const ADAPTERS = {
-  anthropic: {
-    id: 'anthropic',
-    auth: 'api_key',
-    protocol: 'anthropic-messages',
-    credentialEnv: ['ANTHROPIC_API_KEY'],
-    baseURL: 'default',
-    async createModel({ nativeModelId, env }) {
-      const apiKey = envKey(env, 'ANTHROPIC_API_KEY');
-      if (!apiKey) throw missingKey('Anthropic', 'ANTHROPIC_API_KEY');
-      const { createAnthropic } = await import('@ai-sdk/anthropic');
-      return createAnthropic({ apiKey })(nativeModelId);
-    },
-  },
-  openai: {
-    id: 'openai',
-    auth: 'api_key',
-    protocol: 'openai-chat-completions',
-    credentialEnv: ['OPENAI_API_KEY'],
-    baseURL: 'default',
-    async createModel({ nativeModelId, env }) {
-      const apiKey = envKey(env, 'OPENAI_API_KEY');
-      if (!apiKey) throw missingKey('OpenAI', 'OPENAI_API_KEY');
-      const { createOpenAI } = await import('@ai-sdk/openai');
-      return createOpenAI({ apiKey })(nativeModelId);
-    },
-  },
-  openrouter: {
-    id: 'openrouter',
-    auth: 'api_key',
-    protocol: 'openai-compatible',
-    credentialEnv: ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
-    baseURL: OPENROUTER_BASE,
-    async createModel({ nativeModelId, env }) {
-      const apiKey = envKey(env, 'OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY');
-      if (!apiKey) throw missingKey('OpenRouter', 'OPENROUTER_API_KEY');
-      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
-      return createOpenAICompatible({ name: 'openrouter', baseURL: OPENROUTER_BASE, apiKey })(nativeModelId);
-    },
-  },
-  ollama: {
-    id: 'ollama',
-    auth: 'none',
-    protocol: 'openai-compatible',
-    credentialEnv: [],
-    baseURL: 'env:OLLAMA_BASE_URL',
-    async createModel({ modelId, nativeModelId, env }) {
-      const { isOllamaModelInstalled, formatOllamaModelMissingMessage } = await import('../../../lib/ollama/installed-models.mjs');
-      if (isOllamaModelInstalled(modelId, { env }) === false) {
-        const err = new Error(formatOllamaModelMissingMessage(nativeModelId));
-        err.code = 'OLLAMA_MODEL_NOT_PULLED';
-        throw err;
-      }
-      const baseURL = envKey(env, 'OLLAMA_BASE_URL') || 'http://localhost:11434/v1';
-      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
-      return createOpenAICompatible({ name: 'ollama', baseURL, apiKey: 'ollama' })(nativeModelId);
-    },
-  },
-  local: {
-    id: 'local',
-    auth: 'api_key',
-    protocol: 'openai-compatible',
-    credentialEnv: ['LOCAL_LLM_API_KEY'],
-    baseURL: 'env:LOCAL_LLM_BASE_URL',
-    async createModel({ nativeModelId, env }) {
-      const baseURL = envKey(env, 'LOCAL_LLM_BASE_URL');
-      if (!baseURL) throw missingKey('local OpenAI-compatible server', 'LOCAL_LLM_BASE_URL');
-      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
-      return createOpenAICompatible({ name: 'local', baseURL, apiKey: envKey(env, 'LOCAL_LLM_API_KEY') || 'local' })(nativeModelId);
-    },
-  },
-  'github-copilot': {
-    id: 'github-copilot',
-    auth: 'oauth',
-    protocol: 'openai-chat-completions',
-    credentialEnv: [],
-    baseURL: 'copilot',
-    async createModel({ nativeModelId }) {
-      const { getCopilotToken, copilotApiHeaders, COPILOT_API_BASE } = await import('../../../lib/providers/copilot-auth.mjs');
-      const { createOpenAICompatible } = await import('@ai-sdk/openai-compatible');
-      const copilotFetch = async (url, init = {}) => {
-        const token = await getCopilotToken();
-        const headers = new Headers(init.headers);
-        for (const [key, value] of Object.entries(copilotApiHeaders())) headers.set(key, value);
-        headers.set('Authorization', `Bearer ${token}`);
-        return fetch(url, { ...init, headers });
-      };
-      return createOpenAICompatible({ name: 'github-copilot', baseURL: COPILOT_API_BASE, apiKey: 'via-fetch', fetch: copilotFetch })(nativeModelId);
-    },
-  },
-};
-
-export function getProviderAdapter(group) {
-  return ADAPTERS[group] || null;
-}
-
-// Serializable adapter contract for tracing and conformance fixtures (no secrets,
-// no SDK handles) — the metadata a new provider must register.
-
-export function describeProviderAdapters() {
-  return Object.values(ADAPTERS).map((a) => ({
-    id: a.id,
-    auth: a.auth,
-    protocol: a.protocol,
-    credentialEnv: a.credentialEnv,
-    baseURL: a.baseURL,
-  }));
-}
-
-export function nativeModelId(modelId, group = providerGroupForModel(modelId)) {
-  return String(modelId).slice(group.length + 1);
-}
-
-/**
- * Map a Construct "provider/model" id onto an AI SDK language model via the
- * adapter registry. No provider/model-prefix behavior branch: the group is a
- * structural key, the adapter owns the behavior.
- */
-export async function resolveLanguageModel(modelId, env) {
-  if (!modelId) {
-    const err = new Error('No model selected and no configured provider found. Run `construct models` or set CX_MODEL_STANDARD.');
-    err.code = 'PROVIDER_MODEL_UNRESOLVED';
-    throw err;
-  }
-  const group = providerGroupForModel(modelId);
-  const adapter = ADAPTERS[group];
-  if (!adapter) {
-    const err = new Error(`Provider for model '${modelId}' is not wired into the owned loop yet. Try an anthropic/, openai/, openrouter/, ollama/, local/, or github-copilot/ model.`);
-    err.code = 'PROVIDER_UNSUPPORTED';
-    throw err;
-  }
-  return adapter.createModel({ modelId, nativeModelId: nativeModelId(modelId, group), env });
-}

package/apps/chat/engine/tools/permission.mjs

@@ -1,54 +0,0 @@
-/**
- * apps/chat/engine/tools/permission.mjs — the permission and sandbox gate for the
- * owned loop's tools.
- *
- * Owning the loop means Construct, not a host, decides whether a tool runs. This
- * gate reuses the host-agnostic decision vocabulary ADR-0040 defined
- * (allow | allow_always | reject) and the sandbox levels from lib/chat/config.mjs
- * (read-only, workspace-write, danger-full-access). Read-only tools (read, grep,
- * glob) always pass; mutating tools (write, edit, shell) are gated by the sandbox
- * level and the current permission mode, deferring to an interactive
- * `requestPermission` handler only in `ask` mode. `allow_always` is sticky for the
- * rest of the session so a user is not re-prompted per call.
- *
- * `allowOutside` (escape the workspace root) is granted only under
- * danger-full-access; every other level keeps tools inside the workspace, which
- * the primitives enforce independently.
- */
-
-export const READ_ONLY_TOOLS = new Set(['read', 'grep', 'glob']);
-export const MUTATING_TOOLS = new Set(['write', 'edit', 'shell']);
-
-export function createPermissionGate({
-  getSandbox = () => null,
-  getPermissionMode = () => 'allow_once',
-  requestPermission = null,
-} = {}) {
-  let alwaysAllowed = false;
-
-  async function check(toolName, input = {}) {
-    const sandbox = getSandbox() || 'workspace-write';
-    const allowOutside = sandbox === 'danger-full-access';
-
-    if (READ_ONLY_TOOLS.has(toolName)) return { allowed: true, allowOutside };
-
-    if (sandbox === 'read-only') {
-      return { allowed: false, allowOutside, reason: 'sandbox is read-only; mutating tools are disabled (change with /set sandbox workspace-write)' };
-    }
-
-    if (alwaysAllowed) return { allowed: true, allowOutside };
-
-    const mode = getPermissionMode() || 'allow_once';
-    if (mode === 'reject') return { allowed: false, allowOutside, reason: 'permission mode is reject' };
-    if (mode === 'allow_always') { alwaysAllowed = true; return { allowed: true, allowOutside }; }
-    if (mode === 'allow_once') return { allowed: true, allowOutside };
-
-    // ask mode: defer to the interactive handler, mapping its decision back.
-    const decision = requestPermission ? await requestPermission({ tool: toolName, input }) : 'allow';
-    if (decision === 'reject') return { allowed: false, allowOutside, reason: 'denied by user' };
-    if (decision === 'allow_always') { alwaysAllowed = true; return { allowed: true, allowOutside }; }
-    return { allowed: true, allowOutside };
-  }
-
-  return { check, get alwaysAllowed() { return alwaysAllowed; } };
-}

package/apps/chat/engine/tools/primitives.mjs

@@ -1,180 +0,0 @@
-/**
- * apps/chat/engine/tools/primitives.mjs — zero-dep executors for the owned loop's
- * agent tools (read, write, edit, glob, grep, shell).
- *
- * These are the side-effecting primitives the loop calls; they are pure Node so
- * they are fully testable in a tmpdir with no model, network, or SDK. Path safety
- * is enforced here: every path resolves inside the workspace root unless the caller
- * passes `allowOutside` (set only by the danger-full-access sandbox). Search tools
- * walk the tree with a hard result/size cap and skip the usual heavy/ignored dirs
- * so a grep never hangs the loop. Shell reuses the bounded worker runner
- * (lib/worker/run.mjs) for the timeout + path policy already proven there.
- *
- * Every function returns a structured, JSON-serializable result (never throws for
- * an ordinary "not found"/"no match" outcome) so the result maps cleanly onto a
- * tool_update event and back to the model.
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
-import { runJob } from '../../../../lib/worker/run.mjs';
-
-const IGNORED_DIRS = new Set(['node_modules', '.git', '.cx', 'dist', 'build', '.next', 'coverage', '.cache']);
-const MAX_READ_BYTES = 256 * 1024;
-const MAX_WALK_FILES = 20000;
-
-function resolveInside(cwd, target, { allowOutside = false } = {}) {
-  const root = path.resolve(cwd);
-  const resolved = path.resolve(root, target || '.');
-  if (!allowOutside && resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
-    const err = new Error(`path '${target}' is outside the workspace; not permitted under the current sandbox`);
-    err.code = 'PATH_OUTSIDE_WORKSPACE';
-    throw err;
-  }
-  return resolved;
-}
-
-export function readFileTool({ cwd, path: target, maxBytes = MAX_READ_BYTES, allowOutside = false } = {}) {
-  const file = resolveInside(cwd, target, { allowOutside });
-  if (!fs.existsSync(file)) return { ok: false, error: `no such file: ${target}` };
-  const stat = fs.statSync(file);
-  if (stat.isDirectory()) return { ok: false, error: `${target} is a directory` };
-  const buf = fs.readFileSync(file);
-  const truncated = buf.length > maxBytes;
-  return { ok: true, path: target, bytes: stat.size, truncated, content: buf.slice(0, maxBytes).toString('utf8') };
-}
-
-export function writeFileTool({ cwd, path: target, content = '', allowOutside = false } = {}) {
-  const file = resolveInside(cwd, target, { allowOutside });
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, content, 'utf8');
-  return { ok: true, path: target, bytes: Buffer.byteLength(content, 'utf8') };
-}
-
-export function editFileTool({ cwd, path: target, oldString, newString = '', replaceAll = false, allowOutside = false } = {}) {
-  const file = resolveInside(cwd, target, { allowOutside });
-  if (!fs.existsSync(file)) return { ok: false, error: `no such file: ${target}` };
-  if (typeof oldString !== 'string' || oldString.length === 0) return { ok: false, error: 'oldString is required and must be non-empty' };
-  const before = fs.readFileSync(file, 'utf8');
-  const occurrences = before.split(oldString).length - 1;
-  if (occurrences === 0) return { ok: false, error: 'oldString not found in file' };
-  if (occurrences > 1 && !replaceAll) return { ok: false, error: `oldString is not unique (${occurrences} matches); pass replaceAll or add more context` };
-  const after = replaceAll ? before.split(oldString).join(newString) : before.replace(oldString, newString);
-  fs.writeFileSync(file, after, 'utf8');
-  return { ok: true, path: target, replacements: replaceAll ? occurrences : 1 };
-}
-
-// Bounded depth-first walk yielding workspace-relative file paths, skipping the
-// ignored dirs. Caps the number of files visited so a pathological tree cannot
-// stall the loop.
-
-function* walkFiles(root) {
-  const stack = [root];
-  let visited = 0;
-  while (stack.length) {
-    const dir = stack.pop();
-    let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
-    for (const entry of entries) {
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
-        stack.push(full);
-      } else if (entry.isFile()) {
-        if (++visited > MAX_WALK_FILES) return;
-        yield full;
-      }
-    }
-  }
-}
-
-// Translate a simple glob ("**/*.mjs", "src/*.ts", "lib/**") into a RegExp. Only
-// the common operators are supported (no brace expansion), which covers what the
-// loop needs without pulling a glob dependency.
-
-function globToRegExp(pattern) {
-  let re = '';
-  for (let i = 0; i < pattern.length; i++) {
-    const c = pattern[i];
-    if (c === '*') {
-      if (pattern[i + 1] === '*') { re += '.*'; i++; if (pattern[i + 1] === '/') i++; }
-      else re += '[^/]*';
-    } else if (c === '?') re += '[^/]';
-    else if ('.+^${}()|[]\\'.includes(c)) re += `\\${c}`;
-    else re += c;
-  }
-  return new RegExp(`^${re}$`);
-}
-
-export function globTool({ cwd, pattern, limit = 200, allowOutside = false } = {}) {
-  const root = resolveInside(cwd, '.', { allowOutside });
-  if (!pattern) return { ok: false, error: 'pattern is required' };
-  const rx = globToRegExp(pattern);
-  const matches = [];
-  for (const file of walkFiles(root)) {
-    const rel = path.relative(root, file);
-    if (rx.test(rel)) {
-      matches.push(rel);
-      if (matches.length >= limit) break;
-    }
-  }
-  return { ok: true, pattern, matches, truncated: matches.length >= limit };
-}
-
-export function grepTool({ cwd, pattern, glob = null, limit = 200, caseInsensitive = false, allowOutside = false } = {}) {
-  const root = resolveInside(cwd, '.', { allowOutside });
-  if (!pattern) return { ok: false, error: 'pattern is required' };
-  let rx;
-  try { rx = new RegExp(pattern, caseInsensitive ? 'i' : ''); } catch (err) { return { ok: false, error: `invalid pattern: ${err.message}` }; }
-  const globRx = glob ? globToRegExp(glob) : null;
-  const matches = [];
-  for (const file of walkFiles(root)) {
-    const rel = path.relative(root, file);
-    if (globRx && !globRx.test(rel)) continue;
-    let text;
-    try {
-      const stat = fs.statSync(file);
-      if (stat.size > MAX_READ_BYTES) continue;
-      text = fs.readFileSync(file, 'utf8');
-    } catch { continue; }
-    if (text.includes('\u0000')) continue;
-    const lines = text.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-      if (rx.test(lines[i])) {
-        matches.push({ file: rel, line: i + 1, text: lines[i].slice(0, 300) });
-        if (matches.length >= limit) return { ok: true, pattern, matches, truncated: true };
-      }
-    }
-  }
-  return { ok: true, pattern, matches, truncated: false };
-}
-
-export async function shellTool({ cwd, command, timeoutSeconds = 60, allowOutside = false } = {}) {
-  if (!command || typeof command !== 'string') return { ok: false, error: 'command is required' };
-  const root = path.resolve(cwd);
-  const result = await runJob({
-    rootDir: root,
-    job: {
-      jobId: `chat-${randomUUID()}`,
-      command,
-      timeoutSeconds,
-      workspaceRef: root,
-      allowedPaths: allowOutside ? [] : [root],
-    },
-  });
-  let stdout = '';
-  let stderr = '';
-  try { stdout = fs.readFileSync(result.stdoutPath, 'utf8'); } catch { /* no stdout */ }
-  try { stderr = fs.readFileSync(result.stderrPath, 'utf8'); } catch { /* no stderr */ }
-  return {
-    ok: result.status === 'passed',
-    status: result.status,
-    exitCode: result.exitCode,
-    durationMs: result.durationMs,
-    stdout: stdout.slice(0, MAX_READ_BYTES),
-    stderr: stderr.slice(0, MAX_READ_BYTES),
-  };
-}
-
-export const __test__ = { resolveInside, globToRegExp };

package/apps/chat/engine/tools/registry.mjs

@@ -1,122 +0,0 @@
-/**
- * apps/chat/engine/tools/registry.mjs — builds the owned loop's tool set as Vercel
- * AI SDK tools, gated by the permission/sandbox policy.
- *
- * Each tool wraps a zero-dep primitive (primitives.mjs) behind the permission gate
- * (permission.mjs): the gate runs first, and a denial returns a structured result
- * the model can read rather than throwing, so the loop degrades gracefully instead
- * of crashing on a blocked action. A single `construct_tool` bridges the loop to
- * Construct's existing MCP tool surface via dispatchToolByName (mirroring the MCP
- * `construct_call` meta-tool), so the loop reaches knowledge search, skills, and
- * orchestration policy without re-declaring 60+ schemas here.
- *
- * `ai` and `zod` are imported lazily and only here, so the rest of the engine and
- * all of its tests stay free of the optional dependencies.
- */
-
-import {
-  readFileTool, writeFileTool, editFileTool, globTool, grepTool, shellTool,
-} from './primitives.mjs';
-import { createPermissionGate } from './permission.mjs';
-
-function denied(reason) {
-  return { ok: false, denied: true, error: reason };
-}
-
-export async function buildAgentTools({ env = process.env, cwd = process.cwd(), handlers = {}, only = null } = {}) {
-  const { tool } = await import('ai');
-  const { z } = await import('zod');
-
-  const gate = createPermissionGate({
-    getSandbox: handlers.getSandbox || (() => null),
-    getPermissionMode: handlers.getPermissionMode || (() => 'allow_once'),
-    requestPermission: handlers.requestPermission || null,
-  });
-
-  const defs = {
-    read: tool({
-      description: 'Read a UTF-8 text file from the workspace.',
-      inputSchema: z.object({ path: z.string().describe('workspace-relative file path') }),
-      execute: async ({ path: p }) => {
-        const verdict = await gate.check('read', { path: p });
-        if (!verdict.allowed) return denied(verdict.reason);
-        return readFileTool({ cwd, path: p, allowOutside: verdict.allowOutside });
-      },
-    }),
-    glob: tool({
-      description: 'Find files by glob pattern (supports * ** ?).',
-      inputSchema: z.object({ pattern: z.string(), limit: z.number().int().positive().max(1000).optional() }),
-      execute: async ({ pattern, limit }) => {
-        const verdict = await gate.check('glob', { pattern });
-        if (!verdict.allowed) return denied(verdict.reason);
-        return globTool({ cwd, pattern, limit, allowOutside: verdict.allowOutside });
-      },
-    }),
-    grep: tool({
-      description: 'Search file contents by regular expression, optionally filtered by a glob.',
-      inputSchema: z.object({
-        pattern: z.string(),
-        glob: z.string().optional(),
-        caseInsensitive: z.boolean().optional(),
-        limit: z.number().int().positive().max(1000).optional(),
-      }),
-      execute: async ({ pattern, glob, caseInsensitive, limit }) => {
-        const verdict = await gate.check('grep', { pattern });
-        if (!verdict.allowed) return denied(verdict.reason);
-        return grepTool({ cwd, pattern, glob, caseInsensitive, limit, allowOutside: verdict.allowOutside });
-      },
-    }),
-    write: tool({
-      description: 'Create or overwrite a workspace file with the given content.',
-      inputSchema: z.object({ path: z.string(), content: z.string() }),
-      execute: async ({ path: p, content }) => {
-        const verdict = await gate.check('write', { path: p });
-        if (!verdict.allowed) return denied(verdict.reason);
-        return writeFileTool({ cwd, path: p, content, allowOutside: verdict.allowOutside });
-      },
-    }),
-    edit: tool({
-      description: 'Replace an exact string in a workspace file. oldString must be unique unless replaceAll is set.',
-      inputSchema: z.object({
-        path: z.string(),
-        oldString: z.string(),
-        newString: z.string(),
-        replaceAll: z.boolean().optional(),
-      }),
-      execute: async ({ path: p, oldString, newString, replaceAll }) => {
-        const verdict = await gate.check('edit', { path: p });
-        if (!verdict.allowed) return denied(verdict.reason);
-        return editFileTool({ cwd, path: p, oldString, newString, replaceAll, allowOutside: verdict.allowOutside });
-      },
-    }),
-    shell: tool({
-      description: 'Run a bounded shell command in the workspace with a timeout.',
-      inputSchema: z.object({ command: z.string(), timeoutSeconds: z.number().int().positive().max(600).optional() }),
-      execute: async ({ command, timeoutSeconds }) => {
-        const verdict = await gate.check('shell', { command });
-        if (!verdict.allowed) return denied(verdict.reason);
-        return shellTool({ cwd, command, timeoutSeconds, allowOutside: verdict.allowOutside });
-      },
-    }),
-    construct_tool: tool({
-      description: 'Call a Construct MCP tool by name (e.g. knowledge_search, search_skills, orchestration_policy). Returns the tool result.',
-      inputSchema: z.object({ name: z.string(), args: z.record(z.string(), z.any()).optional() }),
-      execute: async ({ name, args }) => {
-        try {
-          const { dispatchToolByName } = await import('../../../../lib/mcp/server.mjs');
-          const result = await dispatchToolByName(name, args || {});
-          return { ok: true, name, result };
-        } catch (err) {
-          return { ok: false, name, error: err?.message || String(err) };
-        }
-      },
-    }),
-  };
-
-  if (!Array.isArray(only) || only.length === 0) return defs;
-  const filtered = {};
-  for (const name of only) if (defs[name]) filtered[name] = defs[name];
-  return filtered;
-}
-
-export const AGENT_TOOL_NAMES = ['read', 'glob', 'grep', 'write', 'edit', 'shell', 'construct_tool'];