@contentful/experience-design-system-generation 2.26.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Contentful GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@contentful/experience-design-system-generation",
+  "version": "2.26.1",
+  "description": "Agent-invocation and skill-prompt engine for the Contentful Experience Design System SDK",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "node": "./dist/src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://npm.pkg.github.com/"
+  },
+  "files": [
+    "dist/",
+    "skills/"
+  ],
+  "scripts": {
+    "build": "nx build experience-design-system-generation",
+    "typecheck": "nx typecheck experience-design-system-generation",
+    "clean": "nx clean experience-design-system-generation",
+    "test": "nx test experience-design-system-generation",
+    "lint": "nx lint experience-design-system-generation",
+    "lint:fix": "nx lint:fix experience-design-system-generation"
+  },
+  "dependencies": {
+    "@contentful/experience-design-system-types": "workspace:*"
+  },
+  "devDependencies": {
+    "@tsconfig/node24": "^24.0.4",
+    "@types/node": "^24.0.3",
+    "eslint": "^9.39.5",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.0.16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/contentful/experience-design-system-sdk-public.git",
+    "directory": "packages/experience-design-system-generation"
+  },
+  "homepage": "https://github.com/contentful/experience-design-system-sdk-public#readme",
+  "bugs": {
+    "url": "https://github.com/contentful/experience-design-system-sdk-public/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "module": "./src/index.js"
+}

package/dist/src/agent-invoker.d.ts

@@ -0,0 +1,24 @@
+import type { AgentDebugEvent, AgentAuthStatus, AgentName, AgentRunResult } from './agent-runner.js';
+export interface InvokeAgentOptions {
+    agent: AgentName;
+    model?: string;
+    prompt: string;
+    timeoutMs: number;
+    onOutput?: (chunk: string) => void;
+}
+/**
+ * Abstracts "invoke an agent and get a result back" from the local-subprocess
+ * mechanism `runAgent` uses today. A remote implementation (e.g. against an
+ * internal agents service) implements the same contract without importing
+ * this package's subprocess transport.
+ */
+export interface AgentInvoker {
+    invoke(options: InvokeAgentOptions): Promise<AgentRunResult>;
+    checkAuth(agent: AgentName): Promise<AgentAuthStatus>;
+}
+export interface CreateLocalCliAgentInvokerOptions {
+    /** Wire in a debug-event sink (e.g. the CLI's own debug logger). No-op by default. */
+    onDebugEvent?: AgentDebugEvent;
+}
+/** Default `AgentInvoker`: spawns the agent CLI binary as a local subprocess. */
+export declare function createLocalCliAgentInvoker(options?: CreateLocalCliAgentInvokerOptions): AgentInvoker;

package/dist/src/agent-invoker.js

@@ -0,0 +1,13 @@
+import { checkAgentAuth, runAgent } from './agent-runner.js';
+/** Default `AgentInvoker`: spawns the agent CLI binary as a local subprocess. */
+export function createLocalCliAgentInvoker(options = {}) {
+    const { onDebugEvent } = options;
+    return {
+        invoke(invokeOptions) {
+            return runAgent({ ...invokeOptions, onDebugEvent });
+        },
+        checkAuth(agent) {
+            return checkAgentAuth(agent);
+        },
+    };
+}

package/dist/src/agent-names.d.ts

@@ -0,0 +1,4 @@
+export declare const AGENT_NAMES: readonly ["claude", "codex", "opencode", "cursor"];
+export type AgentName = (typeof AGENT_NAMES)[number];
+export declare const DEFAULT_AGENT_NAME: AgentName;
+export declare function isAgentName(value: string): value is AgentName;

package/dist/src/agent-names.js

@@ -0,0 +1,5 @@
+export const AGENT_NAMES = ['claude', 'codex', 'opencode', 'cursor'];
+export const DEFAULT_AGENT_NAME = 'claude';
+export function isAgentName(value) {
+    return AGENT_NAMES.includes(value);
+}

package/dist/src/agent-runner.d.ts

@@ -0,0 +1,127 @@
+import type { AgentName } from './agent-names.js';
+export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName, type AgentName } from './agent-names.js';
+export interface AgentRunResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}
+export interface ClassifyPropCall {
+    tool: 'classify_prop';
+    prop: string;
+    cdf_type: string;
+    cdf_category: 'content' | 'design' | 'state';
+    values?: string[];
+    token_kind?: string;
+    required?: boolean;
+    description?: string;
+    default?: string | boolean;
+    /** Internal LLM rationale; not customer-facing. Persisted to raw_props.rationale. */
+    reason?: string;
+}
+export interface ExcludePropCall {
+    tool: 'exclude_prop';
+    prop: string;
+    reason: string;
+}
+export interface ClassifyComponentCall {
+    tool: 'classify_component';
+    description?: string;
+    /**
+     * Component-level rationale strings. Surfaced by the `I` ComponentRationalePanel.
+     * Each field is optional; missing fields leave existing DB values untouched
+     * (sparse update semantics in applyToolCalls).
+     */
+    rationale?: {
+        description?: string;
+        props?: string;
+        slots?: string;
+    };
+}
+export interface ClassifySlotCall {
+    tool: 'classify_slot';
+    slot: string;
+    required?: boolean;
+    allowed_components?: string[];
+    description?: string;
+    /** Per-slot rationale; persisted to raw_slots.rationale. */
+    rationale?: string;
+}
+export type ToolCall = ClassifyPropCall | ExcludePropCall | ClassifyComponentCall | ClassifySlotCall;
+export interface SelectComponentCall {
+    tool: 'select_component';
+    name: string;
+    reason?: string;
+    confidence?: number;
+}
+export interface RejectComponentCall {
+    tool: 'reject_component';
+    name: string;
+    reason?: string;
+    confidence?: number;
+}
+export type SelectToolCall = SelectComponentCall | RejectComponentCall;
+export interface ParsedSelectToolCalls {
+    calls: SelectToolCall[];
+    warnings: string[];
+}
+export declare function parseSelectToolCallLines(stdout: string): ParsedSelectToolCalls;
+export interface SetTokenCall {
+    tool: 'set_token';
+    path: string;
+    type: string;
+    value: unknown;
+    description?: string;
+}
+export interface SetGroupCall {
+    tool: 'set_group';
+    path: string;
+    description?: string;
+}
+export type TokenToolCall = SetTokenCall | SetGroupCall;
+export interface ParsedTokenToolCalls {
+    calls: TokenToolCall[];
+    warnings: string[];
+}
+export interface ParsedToolCalls {
+    calls: ToolCall[];
+    warnings: string[];
+}
+export declare function parseToolCallLines(stdout: string): ParsedToolCalls;
+export declare function parseTokenToolCallLines(stdout: string): ParsedTokenToolCalls;
+export declare function resolveBinary(agent: AgentName): string;
+/**
+ * Resolve the model for an agent. Explicit flag/creds value wins, then a
+ * per-agent `EDS_AGENT_MODEL_<AGENT>` env override (mirrors the
+ * `EDS_AGENT_BINARY_<AGENT>` pattern), otherwise the lightweight default for
+ * that agent.
+ */
+export declare function resolveAgentModel(agent: AgentName, explicit?: string): string;
+export type AgentDebugEvent = (name: string, payload?: Record<string, unknown>) => void;
+export declare function buildArgs(agent: AgentName, prompt: string, model?: string, promptViaStdin?: boolean): string[];
+export declare function runAgent(options: {
+    agent: AgentName;
+    prompt: string;
+    timeoutMs: number;
+    model?: string;
+    onOutput?: (chunk: string) => void;
+    /**
+     * Deliver the prompt on stdin instead of as an argv positional. Required for
+     * large prompts (e.g. the composition resolver inlining candidate files),
+     * which overflow ARG_MAX when passed as an argument.
+     */
+    promptViaStdin?: boolean;
+    /** Optional debug-event sink; callers own how/where events get logged. */
+    onDebugEvent?: AgentDebugEvent;
+}): Promise<AgentRunResult>;
+export type AgentAuthStatus = 'ok' | 'unauthenticated' | 'not-found';
+export declare function checkAgentAuth(agent: AgentName): Promise<AgentAuthStatus>;
+/**
+ * Build a diagnostic string from a failed agent run, surfacing the agent's own
+ * stderr (or stdout, when stderr is empty) so callers never emit a context-free
+ * "agent failed". Callers only invoke this on a failed run: either a non-zero
+ * exit, or a zero exit that produced no tool calls. A non-zero exit is reported
+ * as such; a zero exit is therefore the "produced no tool calls" case.
+ */
+export declare function describeAgentFailure(result: AgentRunResult, maxDetail?: number): string;
+export declare function extractSentinelOutput(stdout: string): string | null | 'multiple';

package/dist/src/agent-runner.js

@@ -0,0 +1,420 @@
+import { spawn } from 'node:child_process';
+export { AGENT_NAMES, DEFAULT_AGENT_NAME, isAgentName } from './agent-names.js';
+const VALID_SELECT_TOOL_NAMES = new Set(['select_component', 'reject_component']);
+export function parseSelectToolCallLines(stdout) {
+    const calls = [];
+    const warnings = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('{'))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            warnings.push(`unparseable line: ${line.slice(0, 120)}`);
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null || !('tool' in obj))
+            continue;
+        const rec = obj;
+        if (!VALID_SELECT_TOOL_NAMES.has(rec.tool))
+            continue;
+        if (typeof rec.name !== 'string' || !rec.name) {
+            warnings.push(`${String(rec.tool)} missing name — skipped`);
+            continue;
+        }
+        const call = {
+            tool: rec.tool,
+            name: rec.name,
+        };
+        if (typeof rec.reason === 'string')
+            call.reason = rec.reason;
+        if (typeof rec.confidence === 'number' && rec.confidence >= 1 && rec.confidence <= 5) {
+            if (call.tool === 'select_component') {
+                call.confidence = rec.confidence;
+            }
+            else {
+                call.confidence = rec.confidence;
+            }
+        }
+        calls.push(call);
+    }
+    return { calls, warnings };
+}
+const VALID_TOOL_NAMES = new Set(['classify_prop', 'exclude_prop', 'classify_component', 'classify_slot']);
+const VALID_TOKEN_TOOL_NAMES = new Set(['set_token', 'set_group']);
+const VALID_CDF_TYPES = new Set(['string', 'richtext', 'media', 'enum', 'token', 'boolean']);
+const VALID_CATEGORIES = new Set(['content', 'design', 'state']);
+export function parseToolCallLines(stdout) {
+    const calls = [];
+    const warnings = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('{'))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            warnings.push(`unparseable line: ${line.slice(0, 120)}`);
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null || !('tool' in obj))
+            continue;
+        const rec = obj;
+        if (!VALID_TOOL_NAMES.has(rec.tool)) {
+            warnings.push(`unknown tool: ${String(rec.tool)}`);
+            continue;
+        }
+        const tool = rec.tool;
+        if (tool === 'classify_prop') {
+            if (typeof rec.prop !== 'string' || !rec.prop) {
+                warnings.push('classify_prop missing prop name — skipped');
+                continue;
+            }
+            if (typeof rec.cdf_type !== 'string' || !VALID_CDF_TYPES.has(rec.cdf_type)) {
+                warnings.push(`classify_prop '${rec.prop}': invalid cdf_type '${String(rec.cdf_type)}' — skipped`);
+                continue;
+            }
+            if (typeof rec.cdf_category !== 'string' || !VALID_CATEGORIES.has(rec.cdf_category)) {
+                warnings.push(`classify_prop '${rec.prop}': invalid cdf_category '${String(rec.cdf_category)}' — skipped`);
+                continue;
+            }
+            const call = {
+                tool: 'classify_prop',
+                prop: rec.prop,
+                cdf_type: rec.cdf_type,
+                cdf_category: rec.cdf_category,
+            };
+            if (Array.isArray(rec.values) && rec.values.every((v) => typeof v === 'string')) {
+                call.values = rec.values;
+            }
+            if (typeof rec.token_kind === 'string')
+                call.token_kind = rec.token_kind;
+            if (typeof rec.required === 'boolean')
+                call.required = rec.required;
+            if (typeof rec.description === 'string')
+                call.description = rec.description;
+            if (typeof rec.default === 'string' || typeof rec.default === 'boolean')
+                call.default = rec.default;
+            if (typeof rec.reason === 'string')
+                call.reason = rec.reason;
+            calls.push(call);
+        }
+        else if (tool === 'exclude_prop') {
+            if (typeof rec.prop !== 'string' || !rec.prop) {
+                warnings.push('exclude_prop missing prop name — skipped');
+                continue;
+            }
+            calls.push({
+                tool: 'exclude_prop',
+                prop: rec.prop,
+                reason: typeof rec.reason === 'string' ? rec.reason : '',
+            });
+        }
+        else if (tool === 'classify_component') {
+            const call = { tool: 'classify_component' };
+            if (typeof rec.description === 'string')
+                call.description = rec.description;
+            if (typeof rec.rationale === 'object' && rec.rationale !== null) {
+                const r = rec.rationale;
+                const rationale = {};
+                if (typeof r.description === 'string')
+                    rationale.description = r.description;
+                if (typeof r.props === 'string')
+                    rationale.props = r.props;
+                if (typeof r.slots === 'string')
+                    rationale.slots = r.slots;
+                if (Object.keys(rationale).length > 0)
+                    call.rationale = rationale;
+            }
+            calls.push(call);
+        }
+        else if (tool === 'classify_slot') {
+            if (typeof rec.slot !== 'string' || !rec.slot) {
+                warnings.push('classify_slot missing slot name — skipped');
+                continue;
+            }
+            const call = { tool: 'classify_slot', slot: rec.slot };
+            if (typeof rec.required === 'boolean')
+                call.required = rec.required;
+            if (Array.isArray(rec.allowed_components) && rec.allowed_components.every((v) => typeof v === 'string')) {
+                call.allowed_components = rec.allowed_components;
+            }
+            if (typeof rec.description === 'string')
+                call.description = rec.description;
+            if (typeof rec.rationale === 'string')
+                call.rationale = rec.rationale;
+            calls.push(call);
+        }
+    }
+    return { calls, warnings };
+}
+export function parseTokenToolCallLines(stdout) {
+    const calls = [];
+    const warnings = [];
+    for (const raw of stdout.split('\n')) {
+        const line = raw.trim();
+        if (!line.startsWith('{'))
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            warnings.push(`unparseable line: ${line.slice(0, 120)}`);
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null || !('tool' in obj))
+            continue;
+        const rec = obj;
+        if (!VALID_TOKEN_TOOL_NAMES.has(rec.tool))
+            continue; // not a token call — skip silently
+        if (rec.tool === 'set_token') {
+            if (typeof rec.path !== 'string' || !rec.path) {
+                warnings.push('set_token missing path — skipped');
+                continue;
+            }
+            if (typeof rec.type !== 'string' || !rec.type) {
+                warnings.push(`set_token '${rec.path}': missing type — skipped`);
+                continue;
+            }
+            if (!('value' in rec)) {
+                warnings.push(`set_token '${rec.path}': missing value — skipped`);
+                continue;
+            }
+            const call = { tool: 'set_token', path: rec.path, type: rec.type, value: rec.value };
+            if (typeof rec.description === 'string')
+                call.description = rec.description;
+            calls.push(call);
+        }
+        else if (rec.tool === 'set_group') {
+            if (typeof rec.path !== 'string' || !rec.path) {
+                warnings.push('set_group missing path — skipped');
+                continue;
+            }
+            const call = { tool: 'set_group', path: rec.path };
+            if (typeof rec.description === 'string')
+                call.description = rec.description;
+            calls.push(call);
+        }
+    }
+    return { calls, warnings };
+}
+// --- Agent invocation ---
+const AGENT_BINARIES = {
+    claude: 'claude',
+    codex: 'codex',
+    opencode: 'opencode',
+    cursor: 'cursor-agent',
+};
+export function resolveBinary(agent) {
+    const envKey = `EDS_AGENT_BINARY_${agent.toUpperCase()}`;
+    const override = process.env[envKey];
+    if (override && override.trim())
+        return override.trim();
+    return AGENT_BINARIES[agent];
+}
+/**
+ * Default models per agent — lightweight/fast picks to control cost when no
+ * explicit model is configured. cursor uses `gpt-mini` (verified alias from
+ * GetUsableModels; haiku is not available in cursor's model catalog).
+ */
+const DEFAULT_MODELS = {
+    claude: 'haiku',
+    codex: 'gpt-5.4-mini', // requires OPENAI_API_KEY; ChatGPT account users must pass --model
+    opencode: 'claude-haiku-4-5',
+    cursor: 'gpt-mini', // cursor alias for gpt-5.4-mini-medium; haiku not in cursor's catalog
+};
+/**
+ * Resolve the model for an agent. Explicit flag/creds value wins, then a
+ * per-agent `EDS_AGENT_MODEL_<AGENT>` env override (mirrors the
+ * `EDS_AGENT_BINARY_<AGENT>` pattern), otherwise the lightweight default for
+ * that agent.
+ */
+export function resolveAgentModel(agent, explicit) {
+    if (explicit && explicit.trim())
+        return explicit.trim();
+    const override = process.env[`EDS_AGENT_MODEL_${agent.toUpperCase()}`];
+    if (override && override.trim())
+        return override.trim();
+    return DEFAULT_MODELS[agent];
+}
+export function buildArgs(agent, prompt, model, promptViaStdin = false) {
+    const modelArg = ['--model', resolveAgentModel(agent, model)];
+    // When the prompt is delivered on stdin, omit it from argv — a large prompt
+    // as a command-line argument overflows ARG_MAX (spawn E2BIG). All four CLIs
+    // read the prompt from stdin when it isn't passed positionally.
+    const promptArg = promptViaStdin ? [] : [prompt];
+    switch (agent) {
+        case 'claude':
+            return ['--print', ...modelArg, ...promptArg];
+        case 'codex':
+            // --dangerously-bypass-approvals-and-sandbox required for non-interactive use
+            return ['exec', ...modelArg, '--dangerously-bypass-approvals-and-sandbox', ...promptArg];
+        case 'opencode':
+            return ['run', ...modelArg, ...promptArg];
+        case 'cursor':
+            // cursor-agent uses --print for non-interactive stdout output
+            return ['--print', ...modelArg, ...promptArg];
+    }
+}
+export async function runAgent(options) {
+    const { agent, prompt, timeoutMs, model, onOutput, promptViaStdin, onDebugEvent } = options;
+    const binary = resolveBinary(agent);
+    const useStdin = !!promptViaStdin;
+    const args = buildArgs(agent, prompt, model, useStdin);
+    const startedAt = Date.now();
+    onDebugEvent?.('run.start', {
+        agent,
+        binary,
+        model,
+        timeoutMs,
+        promptLen: prompt.length,
+        promptHead: prompt.slice(0, 500),
+    });
+    return new Promise((resolve) => {
+        const child = spawn(binary, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        if (useStdin && child.stdin) {
+            // Guard against EPIPE: the child may close stdin before we finish
+            // writing (fast exit, or it stops reading). Swallow the write error —
+            // the child's own exit code/stderr is the source of truth.
+            child.stdin.on('error', () => { });
+            child.stdin.write(prompt, () => {
+                child.stdin?.end();
+            });
+        }
+        else {
+            child.stdin?.end();
+        }
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            stdout += text;
+            onOutput?.(text);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            const result = {
+                exitCode: signal ? 1 : (code ?? 1),
+                stdout,
+                stderr,
+                timedOut,
+            };
+            onDebugEvent?.('run.end', {
+                agent,
+                model,
+                durationMs: Date.now() - startedAt,
+                exitCode: result.exitCode,
+                signal,
+                timedOut,
+                stdoutLen: stdout.length,
+                stderrLen: stderr.length,
+                stderrTail: stderr.slice(-1000),
+            });
+            resolve(result);
+        });
+    });
+}
+export async function checkAgentAuth(agent) {
+    const binary = resolveBinary(agent);
+    // Verify the selected agent's binary exists first — for EVERY agent, not
+    // just claude. When `binary` is an absolute path (e.g. set via
+    // EDS_AGENT_BINARY_<AGENT>=/opt/custom/bin), `which` on some shells doesn't
+    // resolve it — check the filesystem directly for absolute paths, and fall
+    // back to `which` for bare names on $PATH.
+    const binaryExists = await new Promise((resolve) => {
+        if (binary.startsWith('/')) {
+            import('node:fs/promises').then((fs) => fs.access(binary).then(() => resolve(true), () => resolve(false)));
+            return;
+        }
+        const child = spawn('which', [binary], { stdio: 'ignore' });
+        child.on('close', (code) => resolve(code === 0));
+    });
+    if (!binaryExists)
+        return 'not-found';
+    // Only Claude exposes `auth status --json`. Non-Claude agents are considered
+    // authenticated once their binary is present — never gate them on claude
+    // (e.g. Codex-via-Bedrock users would otherwise be blocked by a claude check).
+    if (agent !== 'claude')
+        return 'ok';
+    // Use `claude auth status` — fast, no API call, works regardless of which
+    // auth provider (direct, Bedrock, Vertex) or whether AWS_PROFILE is set.
+    return new Promise((resolve) => {
+        const child = spawn(binary, ['auth', 'status', '--json'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let done = false;
+        const timer = setTimeout(() => {
+            if (!done) {
+                done = true;
+                child.kill('SIGTERM');
+                resolve('unauthenticated');
+            }
+        }, 5000);
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.on('close', (code) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            if (code !== 0) {
+                resolve('unauthenticated');
+                return;
+            }
+            try {
+                const status = JSON.parse(stdout);
+                resolve(status.loggedIn ? 'ok' : 'unauthenticated');
+            }
+            catch {
+                resolve('unauthenticated');
+            }
+        });
+    });
+}
+/**
+ * Build a diagnostic string from a failed agent run, surfacing the agent's own
+ * stderr (or stdout, when stderr is empty) so callers never emit a context-free
+ * "agent failed". Callers only invoke this on a failed run: either a non-zero
+ * exit, or a zero exit that produced no tool calls. A non-zero exit is reported
+ * as such; a zero exit is therefore the "produced no tool calls" case.
+ */
+export function describeAgentFailure(result, maxDetail = 800) {
+    const base = result.exitCode !== 0 ? `agent exited with code ${result.exitCode}` : 'agent produced no tool calls';
+    const detail = (result.stderr.trim() || result.stdout.trim()).slice(-maxDetail).trim();
+    return detail ? `${base} — ${detail}` : base;
+}
+export function extractSentinelOutput(stdout) {
+    const START = '<<<EDS_OUTPUT_START>>>';
+    const END = '<<<EDS_OUTPUT_END>>>';
+    const startIdx = stdout.indexOf(START);
+    const endIdx = stdout.indexOf(END);
+    if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx)
+        return null;
+    // Check for multiple blocks
+    const secondStart = stdout.indexOf(START, startIdx + START.length);
+    if (secondStart !== -1 && secondStart < endIdx)
+        return 'multiple';
+    const afterStart = stdout.indexOf(END, startIdx);
+    const secondEnd = stdout.indexOf(END, afterStart + END.length);
+    if (secondEnd !== -1)
+        return 'multiple';
+    return stdout.slice(startIdx + START.length, endIdx).trim();
+}