@geraldmaron/construct 1.2.1 → 1.2.3

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

@@ -0,0 +1,171 @@
+/**
+ * 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

@@ -0,0 +1,54 @@
+/**
+ * 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

@@ -0,0 +1,180 @@
+/**
+ * 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

@@ -0,0 +1,122 @@
+/**
+ * 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'];

package/apps/chat/engine/turn-controls.mjs

@@ -0,0 +1,70 @@
+/**
+ * apps/chat/engine/turn-controls.mjs — resolve one turn's execution controls from
+ * the compiled execution policy (construct-rv2x).
+ *
+ * The owned-loop engine (ai-sdk-agent.mjs) calls this once per turn to turn a
+ * capability profile plus the turn overlay into the concrete knobs streamText
+ * needs: the step cap, the output-token cap, caching eligibility, and the tool-
+ * group / schema budget, plus the continuation/compaction budget the session uses
+ * to decide when to compact context (construct-6zga.1.9). The capability profile
+ * is resolved from the active model id, so a mid-session model switch re-derives
+ * the envelope.
+ *
+ * Behavior preservation is the contract: this never throws and never returns a
+ * tighter envelope than today for a hosted-direct model. hosted-direct keeps the
+ * legacy step cap, the full tool set, and unbounded output; every other class
+ * enforces its compiled budget. An explicit CX_CHAT_MAX_STEPS operator override
+ * wins over the policy's step cap. Any failure in policy resolution falls back to
+ * the legacy envelope (16 steps, full tool set, no cap, no caching) so a policy
+ * bug can never break a chat turn.
+ */
+
+import { resolveExecutionCapabilityProfile } from '../../../lib/models/execution-capability-profile.mjs';
+import { compilePolicyFromOverlay } from '../../../lib/models/execution-policy.mjs';
+import { continuationBudgetFromPolicy } from '../../../lib/chat/context-continuation.mjs';
+
+const LEGACY_STEP_CAP = 16;
+
+const LEGACY_CONTROLS = Object.freeze({
+  policy: null,
+  iterations: LEGACY_STEP_CAP,
+  outputCap: null,
+  cacheEligible: false,
+  allowedToolGroups: null,
+  maxToolSchemas: Infinity,
+  degraded: false,
+  continuation: Object.freeze({ triggerTokens: null, triggerRatio: null }),
+});
+
+function legacyControls() {
+  return { ...LEGACY_CONTROLS };
+}
+
+export function resolveTurnControls({ model = null, turnOverlay = null, env = {} } = {}) {
+  try {
+    const profile = resolveExecutionCapabilityProfile({ model });
+    const toolFailure = turnOverlay?.toolFailure === true;
+    const policy = compilePolicyFromOverlay({ profile, overlay: turnOverlay, toolFailure });
+
+    const envSteps = Number(env?.CX_CHAT_MAX_STEPS);
+    const iterations = envSteps > 0 ? Math.floor(envSteps) : policy.tools.maxToolIterations;
+
+    // hosted-direct is the mandated default path: keep today's unbounded output
+    // until live-probe evidence supersedes the compatibility_fallback tier. Every
+    // other class enforces its compiled output budget.
+    const outputCap = policy.source.capabilityClass === 'hosted-direct' ? null : policy.output.outputTokenBudget;
+
+    return {
+      policy,
+      iterations,
+      outputCap,
+      cacheEligible: policy.caching.eligible === true,
+      allowedToolGroups: policy.tools.allowedToolGroups,
+      maxToolSchemas: policy.tools.maxToolSchemas,
+      degraded: policy.degradedMode === true,
+      continuation: continuationBudgetFromPolicy(policy),
+    };
+  } catch {
+    return legacyControls();
+  }
+}