@moda-ai/cli 1.20.1 → 1.22.0

package/dist/init/sdk-integration.js

@@ -1,172 +1,835 @@
-// src/init/sdk-integration.ts — Run an installed coding agent to integrate the
-// Moda SDK directly, instead of leaving a guide for the user to action by hand.
-//
-// This reuses the same coding-agent spawn machinery as `moda harness analyze`
-// (see src/harness.ts), but in write mode. The integration knowledge itself
-// lives in the bundled integration skills (skills/integration/, authored in
-// packages/integration-skills/): we resolve the skill matching the detected
-// stack, materialize it into .claude/skills/<id>/, and hand the agent a thin
-// prompt that points at the skill file — the prompt no longer inlines API
-// documentation.
+// src/init/sdk-integration.ts — Agent-owned SDK integration during `moda init`.
+// The coding agent investigates the repo, applies relevant catalog skills,
+// runs repo checks and a smoke LLM call, and reports via a structured protocol.
+// The CLI enforces deterministic guards and independently verifies the trace.
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { codingAgentDisplayName, describeCodingAgentEvent, detectAvailableCodingAgents, runCodingAgent, } from '../harness.js';
-// Re-exported for callers/tests that treat this module as the card-rendering
-// surface; the implementation lives in harness.ts next to the event parser so
-// the agent-stream analyst path can reuse it without an import cycle.
+import { installIntegrationSkill } from '../skills-bundled.js';
+import { cleanupSdkCatalog, materializeSdkCatalog, renderCatalogListing, } from './sdk-catalog.js';
+import { extractSdkAgentResult, SDK_RESULT_FILE, SDK_RESULT_JSON_BEGIN, SDK_RESULT_JSON_END, SDK_RESULT_SCHEMA_VERSION, } from './sdk-protocol.js';
+import { generateVerificationId, verifyExactTrace, } from './sdk-verification.js';
+import { readRuntimeSummary, renderRuntimeSummaryBlock } from './sdk-guide.js';
 export { describeCodingAgentEvent } from '../harness.js';
-import { installIntegrationSkill, readBundledSkillMd } from '../skills-bundled.js';
-import { detectSdkGuideContext, renderDetectionBlock, renderSdkIntegrationGuide, stripSkillFrontmatter, } from './sdk-guide.js';
-import { resolveIntegrationSkillId } from './skill-resolver.js';
-/**
- * Pick an installed coding-agent CLI and run it, in write mode, to integrate
- * the Moda SDK into the repo. Returns `no-agent` (without throwing) when no
- * CLI is installed so the caller can fall back to writing the static guide.
- */
+const OUTCOME_SCHEMA_VERSION = 'moda.sdk_integration_outcome.v1';
+const MAX_SCAN_FILE_BYTES = 1_048_576;
+const MAX_SCANNED_FILES = 2_000;
+const MAX_SCAN_DIRECTORIES = 2_000;
+const SECRET_KEY_PATTERN = /moda_sk_[A-Za-z0-9]{8,}/g;
+const DEGRADED_GUARDS_NOTE = 'changed-file guards degraded: not a git repository';
 export async function runSdkIntegration(options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const available = detectAvailableCodingAgents();
-    if (available.length === 0)
-        return { status: 'no-agent' };
+    if (available.length === 0) {
+        return { status: 'agent_unavailable', repair_attempts: 0 };
+    }
     const adapter = options.adapter && available.some((item) => item.adapter === options.adapter)
         ? options.adapter
         : available[0].adapter;
     const human = options.human ?? false;
     const emit = (message) => {
-        options.onProgress?.(message);
+        const redacted = redactSecretText(message, options.apiKey);
+        options.onProgress?.(redacted);
         if (human)
-            process.stderr.write(`  ${codingAgentDisplayName(adapter)}: ${message}\n`);
+            process.stderr.write(`  ${codingAgentDisplayName(adapter)}: ${redacted}\n`);
     };
-    const context = detectSdkGuideContext(cwd);
-    const skillId = resolveIntegrationSkillId(context);
-    let installedSkillId;
-    let inlineSkill;
-    if (skillId) {
-        try {
-            const install = installIntegrationSkill(skillId, cwd);
-            installedSkillId = install.skillId;
-            emit(install.status === 'installed'
-                ? `Installed integration skill ${skillId} to .claude/skills/${skillId}/`
-                : `Integration skill ${skillId} already up to date`);
-        }
-        catch (err) {
-            // Materialization failed (unwritable .claude/skills target, a colliding
-            // user-authored file, or a missing/corrupt bundle). Do NOT silently drop
-            // the resolved stack to the generic checklist — that would contradict the
-            // detection block. When the bundle is still readable, inline the skill's
-            // content into the prompt so the agent keeps the stack-specific steps;
-            // only a truly absent bundle (e.g. an unbuilt dev tree) falls through to
-            // the generic guide.
-            const message = err instanceof Error ? err.message : String(err);
-            emit(`Could not materialize integration skill ${skillId}: ${message}`);
-            const skillMd = readBundledSkillMd(skillId);
-            if (skillMd) {
-                inlineSkill = { skillId, markdown: skillMd };
-                emit(`Inlining ${skillId} instructions into the agent prompt instead`);
+    const runAgent = options.runAgent ?? runCodingAgent;
+    const verify = options.verify ?? verifyExactTrace;
+    const maxRepairAttempts = resolveMaxRepairAttempts(options.maxRepairAttempts);
+    const runId = randomBytes(4).toString('hex');
+    const verificationId = generateVerificationId();
+    let catalog;
+    let gitBaseline = null;
+    let runStartedAt = Date.now();
+    let guardsDegraded = false;
+    let degradedGuardsEmitted = false;
+    const markGuardsDegraded = () => {
+        guardsDegraded = true;
+        if (degradedGuardsEmitted)
+            return;
+        degradedGuardsEmitted = true;
+        emit(DEGRADED_GUARDS_NOTE);
+    };
+    try {
+        catalog = materializeSdkCatalog(cwd, runId);
+        gitBaseline = snapshotGitStatus(cwd);
+        runStartedAt = Date.now();
+        if (gitBaseline === null)
+            markGuardsDegraded();
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            status: 'agent_failed',
+            adapter,
+            verification_id: verificationId,
+            repair_attempts: 0,
+            detail: redactSecretText(`Could not materialize the SDK skill catalog: ${detail}`, options.apiKey),
+        };
+    }
+    const attemptCtx = {
+        cwd,
+        adapter,
+        verificationId,
+        catalog,
+        gitBaseline,
+        apiKey: options.apiKey,
+        ingestUrl: options.ingestUrl,
+        human,
+        emit,
+        onEvent: options.onEvent,
+        onPhase: options.onPhase,
+        runAgent,
+        verify,
+        fetchAudit: options.fetchAudit,
+        verifyTimeoutMs: options.verifyTimeoutMs,
+    };
+    let repairAttemptsUsed = 0;
+    let lastAgentResult;
+    let lastVerification;
+    let lastSecurityFindings;
+    let lastOutcome = { status: 'agent_failed', detail: 'No agent attempt completed.' };
+    let installedSkillIds;
+    let protocolRetryUsed = false;
+    try {
+        options.onPhase?.('investigating', 'Investigating repository and integrating the Moda SDK…');
+        emit('Starting SDK integration…');
+        while (true) {
+            const isRepair = repairAttemptsUsed > 0;
+            const prompt = isRepair
+                ? renderSdkRepairPrompt({
+                    catalogDir: catalog.relativeDir,
+                    catalogListing: renderCatalogListing(catalog.index),
+                    verificationId,
+                    attempt: repairAttemptsUsed,
+                    maxAttempts: maxRepairAttempts,
+                    classification: lastOutcome.repairable ?? 'telemetry_not_observed',
+                    previousResult: lastAgentResult,
+                    verification: lastVerification,
+                    securityFindings: lastSecurityFindings,
+                    harnessSummary: readRuntimeSummary(cwd),
+                })
+                : renderSdkIntegrationPrompt({
+                    catalogDir: catalog.relativeDir,
+                    catalogListing: renderCatalogListing(catalog.index),
+                    verificationId,
+                    harnessSummary: readRuntimeSummary(cwd),
+                });
+            const run = await invokeAgent(attemptCtx, prompt);
+            const extraction = await extractResultWithProtocolRetry(attemptCtx, run, protocolRetryUsed, () => {
+                protocolRetryUsed = true;
+            });
+            if ('agentFailed' in extraction) {
+                lastOutcome = extraction.agentFailed;
+                break;
+            }
+            lastAgentResult = sanitizeAgentResult(extraction.result, options.apiKey);
+            removeAgentResultFile(cwd);
+            const guards = applyDeterministicGuards(cwd, gitBaseline, lastAgentResult, runStartedAt, options.apiKey);
+            if (guards.guardsDegraded)
+                markGuardsDegraded();
+            lastSecurityFindings = guards.securityFindings.length > 0 ? guards.securityFindings : undefined;
+            if (guards.securityFindings.length > 0) {
+                lastOutcome = {
+                    status: 'needs_human_input',
+                    detail: 'remove the leaked key, rotate it, and keep secrets in the environment',
+                };
+                break;
+            }
+            if (guards.dishonestIntegrated) {
+                lastOutcome = {
+                    status: 'agent_failed',
+                    detail: 'agent reported integration but no files changed',
+                };
+                break;
+            }
+            lastOutcome = await mapAgentResultToOutcome(attemptCtx, lastAgentResult);
+            if (lastOutcome.verification) {
+                lastVerification = lastOutcome.verification;
             }
+            if (!lastOutcome.repairable || repairAttemptsUsed >= maxRepairAttempts) {
+                break;
+            }
+            repairAttemptsUsed += 1;
+            options.onPhase?.('repairing', `Repairing SDK integration (attempt ${repairAttemptsUsed} of ${maxRepairAttempts})…`);
+            emit(`Repair attempt ${repairAttemptsUsed} of ${maxRepairAttempts}…`);
+        }
+        if (lastOutcome.status === 'integrated_verified' && lastAgentResult) {
+            installedSkillIds = installUsedSkills(lastAgentResult, catalog, cwd, emit);
+        }
+        const finalStatus = lastOutcome.status;
+        const finalDetail = composeFinalDetail(finalStatus, lastOutcome.detail, lastVerification, options.apiKey, guardsDegraded);
+        writeFinalOutcomeArtifact(cwd, {
+            status: finalStatus,
+            verification_id: verificationId,
+            verification: lastVerification,
+            agent_result: lastAgentResult,
+            repair_attempts: repairAttemptsUsed,
+            security_findings: lastSecurityFindings,
+        });
+        return {
+            status: finalStatus,
+            adapter,
+            verification_id: verificationId,
+            verification: lastVerification,
+            agent_result: lastAgentResult,
+            repair_attempts: repairAttemptsUsed,
+            ...(lastSecurityFindings ? { security_findings: lastSecurityFindings } : {}),
+            ...(installedSkillIds ? { installed_skill_ids: installedSkillIds } : {}),
+            ...(finalDetail ? { detail: finalDetail } : {}),
+        };
+    }
+    finally {
+        cleanupSdkCatalog(catalog.dir);
+    }
+}
+export function renderSdkIntegrationPrompt(opts) {
+    // Only surface prior harness discovery when it actually found something;
+    // an all-zero summary is noise, not context.
+    const summary = opts.harnessSummary;
+    const hasHarnessSignals = Boolean(summary && (summary.runtimeAgents > 0 || summary.frameworks.length > 0 || summary.providers.length > 0));
+    const harnessBlock = summary && hasHarnessSignals
+        ? [
+            'Context from Moda\'s earlier harness discovery (may be incomplete):',
+            renderRuntimeSummaryBlock(summary),
+            '',
+        ]
+        : [];
+    return [
+        'You are running inside `moda init` as a one-shot SDK integration task. The user has',
+        'approved letting you install packages and edit source files in THIS repository to add',
+        'Moda LLM observability. Do the integration now — do not just describe it.',
+        '',
+        ...SAFETY_RULES,
+        '',
+        'Investigation:',
+        '- Inspect this repository yourself: workspace/monorepo layout, package manifests and',
+        '  lockfiles, scripts, app entry points, LLM clients/wrappers, existing telemetry or',
+        '  existing Moda setup, tests/build/typecheck/lint commands, and runtime requirements.',
+        '- If Moda is already integrated, do not duplicate it. You MUST still run the smoke',
+        '  through the EXISTING integration with the provided verification id, then report',
+        '  `nothing_to_integrate` with an honest summary and the `smoke` field set.',
+        '',
+        ...harnessBlock,
+        'Skill catalog (read relevant skills; multiple may apply):',
+        opts.catalogListing,
+        '',
+        `Read \`${opts.catalogDir}/<id>/SKILL.md\` for every skill relevant to this repo`,
+        '(EXAMPLE.md beside it shows the finished integration). Multiple skills may apply',
+        '(e.g. a monorepo with a Node service and a Python service, or two providers) —',
+        'apply each relevant one. The catalog is guidance, not a constraint: if the repo\'s',
+        'stack has no matching skill, use the closest skill plus the docs pattern, and say',
+        'so in the result.',
+        '',
+        'Repository checks:',
+        '- Discover and run this repo\'s own build/typecheck/lint/test commands relevant to',
+        '  your changes; record each in commands_run with exit codes.',
+        '- If they fail and you cannot fix within the integration scope → status',
+        '  repository_checks_failed.',
+        '',
+        'Smoke + verification id:',
+        `- Run one real request through an instrumented application path that makes an actual`,
+        '  LLM call, with the Moda conversation id set to EXACTLY',
+        `  \`${opts.verificationId}\` (each skill documents the conversation-id API, e.g.`,
+        '  Moda.conversationId / moda.conversation_id).',
+        '- Prefer a minimal temporary script under .moda/tmp/ (delete it after) or an existing',
+        '  safe entry point — never a destructive path (no prod mutations, no long-running',
+        '  servers left up). Flush before exit.',
+        '- MODA_API_KEY and MODA_INGEST_URL are already exported in your environment for the',
+        '  smoke run — reference them, never print or copy their values.',
+        '- If the smoke cannot run (missing provider key, needs a running service you cannot',
+        '  start safely) → status smoke_execution_failed or needs_human_input with',
+        '  remaining_actions.',
+        '',
+        renderResultProtocolSection(),
+    ].join('\n');
+}
+export function renderSdkRepairPrompt(opts) {
+    const evidence = {
+        previous_agent_result: opts.previousResult ?? null,
+        verification: opts.verification ?? null,
+        security_findings: opts.securityFindings ?? [],
+    };
+    return [
+        `Repair attempt ${opts.attempt} of ${opts.maxAttempts} failed: ${opts.classification}`,
+        '',
+        'Structured evidence from the previous attempt:',
+        JSON.stringify(evidence, null, 2),
+        '',
+        ...SAFETY_RULES,
+        '',
+        `Skill catalog directory: ${opts.catalogDir}`,
+        opts.catalogListing,
+        '',
+        `Use the SAME verification id for the smoke run: \`${opts.verificationId}\`.`,
+        'Re-run only what is needed; report honestly via the result protocol.',
+        '',
+        renderResultProtocolSection(),
+    ].join('\n');
+}
+const SAFETY_RULES = [
+    'Scope and safety rules:',
+    '- Only touch this repository (the working directory you were launched in).',
+    '- Install the Moda SDK with the package manager this repo already uses.',
+    '- Instrument the real LLM call sites; do not invent files or frameworks that are not here.',
+    '- NEVER write MODA_API_KEY or any secret into source files, and never create or edit',
+    '  .env files. The key is already exported in your environment as MODA_API_KEY for the',
+    '  smoke run — reference it, never print or copy its value.',
+    '- Make the smallest correct change. Match the existing code style and imports.',
+    '- Do not modify anything under the ephemeral skill catalog directory.',
+    '- Do not run `git commit`.',
+    '- Do not edit `.moda/` state files except `.moda/sdk-integration-result.json`.',
+    '- If the repo has no LLM calls or something is ambiguous, stop and report honestly',
+    '  via the result protocol.',
+];
+function renderResultProtocolSection() {
+    return [
+        'Result protocol (REQUIRED — write file AND print markers as your last output):',
+        `- Write \`${SDK_RESULT_FILE}\` with schema_version \`${SDK_RESULT_SCHEMA_VERSION}\`.`,
+        `- Print the same JSON between ${SDK_RESULT_JSON_BEGIN} and ${SDK_RESULT_JSON_END}.`,
+        'Fields:',
+        '- schema_version (required): must be moda.sdk_integration_result.v1',
+        '- status (required): integrated | needs_human_input | repository_checks_failed |',
+        '  smoke_execution_failed | nothing_to_integrate | failed',
+        '- summary (required): one-line human summary',
+        '- skills_consulted: string[] of catalog skill ids you read',
+        '- skills_used: string[] of catalog skill ids you applied',
+        '- packages_installed: string[]',
+        '- files_changed: string[] of repo-relative paths',
+        '- call_sites_instrumented: { file, detail? }[] (plain strings accepted as {file})',
+        '- commands_run: { command, exit_code, kind? }[]',
+        `- smoke: { method, command?, verification_id } | null — verification_id must be exactly`,
+        '  the id provided above when smoke ran',
+        '- remaining_actions: string[] for the human when blocked',
+        '- failure: { class, detail } | null',
+        '',
+        'Report honestly: `integrated` means you completed integration, checks passed, and the',
+        'smoke ran — Moda will independently verify the trace; false claims are detected.',
+    ].join('\n');
+}
+function resolveMaxRepairAttempts(override) {
+    if (override !== undefined && Number.isFinite(override)) {
+        return Math.min(3, Math.max(0, Math.trunc(override)));
+    }
+    const raw = process.env.MODA_SDK_REPAIR_ATTEMPTS;
+    if (!raw)
+        return 1;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return 1;
+    return Math.min(3, Math.max(0, Math.trunc(parsed)));
+}
+function snapshotGitStatus(cwd) {
+    // core.quotePath=off makes git emit non-ASCII paths as raw UTF-8 instead of
+    // octal-escaped C-quoted strings ("caf\303\251.ts"), so the secret scan sees
+    // real paths for new files/dirs with non-ASCII names. Control characters and
+    // quotes are still C-quoted with the escapes unquoteGitPath handles.
+    const result = spawnSync('git', ['-c', 'core.quotePath=off', 'status', '--porcelain'], {
+        cwd,
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return null;
+    return result.stdout ?? '';
+}
+function gitDelta(baseline, cwd) {
+    const after = snapshotGitStatus(cwd);
+    if (baseline === null || after === null)
+        return { lines: [], degraded: true };
+    const beforeLines = new Set(baseline.split('\n').filter(Boolean));
+    return {
+        lines: after.split('\n').filter((line) => line && !beforeLines.has(line)),
+        degraded: false,
+    };
+}
+export function parseGitDeltaPaths(deltaLines) {
+    const paths = [];
+    for (const line of deltaLines) {
+        if (!line.trim())
+            continue;
+        const body = line.slice(3).trim();
+        if (!body)
+            continue;
+        const renameAt = body.lastIndexOf(' -> ');
+        const rawPath = renameAt >= 0 ? body.slice(renameAt + 4) : body;
+        paths.push(unquoteGitPath(rawPath));
+    }
+    return paths;
+}
+const GIT_QUOTE_ESCAPES = {
+    '"': 0x22,
+    '\\': 0x5c,
+    a: 0x07,
+    b: 0x08,
+    f: 0x0c,
+    n: 0x0a,
+    r: 0x0d,
+    t: 0x09,
+    v: 0x0b,
+};
+/**
+ * Decode a git C-quoted porcelain path. Escapes are byte-level (octal \NNN
+ * sequences encode UTF-8 bytes), so decoding accumulates bytes and re-decodes
+ * as UTF-8 at the end. With core.quotePath=off (see snapshotGitStatus) octal
+ * escapes only appear for control bytes, but decode them anyway for safety.
+ */
+function unquoteGitPath(path) {
+    const trimmed = path.trim();
+    if (trimmed.length < 2 || trimmed[0] !== '"' || trimmed.at(-1) !== '"')
+        return trimmed;
+    const inner = trimmed.slice(1, -1);
+    const bytes = [];
+    for (let i = 0; i < inner.length; i++) {
+        const ch = inner[i];
+        if (ch !== '\\') {
+            for (const byte of Buffer.from(ch, 'utf8'))
+                bytes.push(byte);
+            continue;
+        }
+        const octal = inner.slice(i + 1, i + 4);
+        if (/^[0-7]{3}$/.test(octal)) {
+            bytes.push(parseInt(octal, 8));
+            i += 3;
+            continue;
+        }
+        const next = inner[i + 1];
+        if (next !== undefined && GIT_QUOTE_ESCAPES[next] !== undefined) {
+            bytes.push(GIT_QUOTE_ESCAPES[next]);
+            i += 1;
+            continue;
         }
+        bytes.push(0x5c); // Unknown escape: keep the literal backslash.
     }
-    const prompt = renderSdkIntegrationPrompt(context, {
-        installedSkillId,
-        inlineSkill,
-        resolvedSkillId: skillId ?? undefined,
+    return Buffer.from(bytes).toString('utf8');
+}
+// Filesystem mtime granularity slack (FAT is 2s; also covers same-tick writes).
+const MTIME_SLACK_MS = 2000;
+function filesTouchedSince(cwd, paths, sinceMs) {
+    const resolvedCwd = resolve(cwd);
+    return paths.some((relPath) => {
+        const absPath = resolve(cwd, relPath.replace(/\\/g, '/'));
+        if (!absPath.startsWith(resolvedCwd + '/') && absPath !== resolvedCwd)
+            return false;
+        try {
+            return statSync(absPath).mtimeMs >= sinceMs - MTIME_SLACK_MS;
+        }
+        catch {
+            return false;
+        }
     });
-    const run = await runCodingAgent({
-        adapter,
+}
+function applyDeterministicGuards(cwd, gitBaseline, result, runStartedAt, apiKey) {
+    const delta = gitDelta(gitBaseline, cwd);
+    const deltaPaths = parseGitDeltaPaths(delta.lines);
+    const candidatePaths = uniquePaths([...deltaPaths, ...result.files_changed]);
+    const securityFindings = scanForSecrets(cwd, candidatePaths, apiKey);
+    // When the git delta is trustworthy an "integrated" claim needs real
+    // evidence of change: either a new status line, or a claimed file whose
+    // mtime moved during the run. The mtime fallback exists because the delta is
+    // a status-line set difference, so edits to a file that was already dirty at
+    // baseline (or committed by the agent) produce no new line. A fabricated
+    // files_changed list pointing at untouched files corroborates nothing.
+    // Degraded mode (not a git repository) keeps the self-report-only check.
+    const claimCorroborated = deltaPaths.length > 0
+        || filesTouchedSince(cwd, result.files_changed, runStartedAt);
+    const dishonestIntegrated = result.status === 'integrated'
+        && (delta.degraded ? result.files_changed.length === 0 : !claimCorroborated);
+    return { securityFindings, dishonestIntegrated, guardsDegraded: delta.degraded };
+}
+function uniquePaths(paths) {
+    return [...new Set(paths.map((p) => p.replace(/\\/g, '/')).filter(Boolean))];
+}
+function scanForSecrets(cwd, paths, apiKey) {
+    const findings = [];
+    const resolvedCwd = resolve(cwd);
+    const scanPaths = collectSecretScanFiles(cwd, paths);
+    for (const relPath of scanPaths) {
+        const absPath = resolve(cwd, relPath);
+        if (!absPath.startsWith(resolvedCwd + '/') && absPath !== resolvedCwd)
+            continue;
+        if (!existsSync(absPath))
+            continue;
+        let stat;
+        try {
+            stat = statSync(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        // Oversized files are scanned up to MAX_SCAN_FILE_BYTES rather than skipped
+        // outright, so a leaked key hidden in a large (e.g. generated) file can't
+        // evade the guard by size alone.
+        let content;
+        try {
+            content = stat.size > MAX_SCAN_FILE_BYTES
+                ? readFilePrefix(absPath, MAX_SCAN_FILE_BYTES)
+                : readFileSync(absPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (content.includes('\0'))
+            continue;
+        let leaked = false;
+        if (apiKey && content.includes(apiKey))
+            leaked = true;
+        SECRET_KEY_PATTERN.lastIndex = 0;
+        if (SECRET_KEY_PATTERN.test(content))
+            leaked = true;
+        if (leaked)
+            findings.push(relPath.replace(/\\/g, '/'));
+    }
+    return findings;
+}
+/** Read at most `maxBytes` from the start of a file, decoded as UTF-8. */
+function readFilePrefix(absPath, maxBytes) {
+    const fd = openSync(absPath, 'r');
+    try {
+        const buffer = Buffer.allocUnsafe(maxBytes);
+        const bytesRead = readSync(fd, buffer, 0, maxBytes, 0);
+        return buffer.toString('utf8', 0, bytesRead);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function collectSecretScanFiles(cwd, paths) {
+    const resolvedCwd = resolve(cwd);
+    const files = [];
+    const seenFiles = new Set();
+    let visitedDirectories = 0;
+    const isInsideRepo = (path) => path === resolvedCwd || path.startsWith(`${resolvedCwd}/`);
+    const addFile = (path) => {
+        if (files.length >= MAX_SCANNED_FILES || !isInsideRepo(path))
+            return;
+        const relPath = relative(resolvedCwd, path).replace(/\\/g, '/');
+        if (!relPath || seenFiles.has(relPath))
+            return;
+        seenFiles.add(relPath);
+        files.push(relPath);
+    };
+    const addEnvFiles = (dir) => {
+        if (files.length >= MAX_SCANNED_FILES || !isInsideRepo(dir))
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && (entry.name === '.env' || entry.name.startsWith('.env.'))) {
+                addFile(join(dir, entry.name));
+            }
+        }
+    };
+    const addDirectoryFiles = (rootDir) => {
+        const stack = [rootDir];
+        while (stack.length > 0 &&
+            files.length < MAX_SCANNED_FILES &&
+            visitedDirectories < MAX_SCAN_DIRECTORIES) {
+            const dir = stack.pop();
+            if (!dir || !isInsideRepo(dir))
+                continue;
+            visitedDirectories += 1;
+            let entries;
+            try {
+                entries = readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (files.length >= MAX_SCANNED_FILES)
+                    break;
+                const path = join(dir, entry.name);
+                if (entry.isDirectory())
+                    stack.push(path);
+                else if (entry.isFile())
+                    addFile(path);
+            }
+        }
+    };
+    // Gitignored env files do not appear in porcelain output. Always inspect the
+    // repo root and candidate parent directories before ordinary candidates.
+    addEnvFiles(resolvedCwd);
+    const candidates = uniquePaths(paths).slice(0, MAX_SCANNED_FILES);
+    for (const relPath of candidates) {
+        if (files.length >= MAX_SCANNED_FILES)
+            break;
+        const absPath = resolve(cwd, relPath);
+        if (!isInsideRepo(absPath))
+            continue;
+        addEnvFiles(dirname(absPath));
+        if (!existsSync(absPath))
+            continue;
+        let stat;
+        try {
+            stat = statSync(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isFile())
+            addFile(absPath);
+        else if (stat.isDirectory() && relPath.replace(/\\/g, '/').endsWith('/')) {
+            addDirectoryFiles(absPath);
+        }
+    }
+    return files;
+}
+async function invokeAgent(ctx, prompt) {
+    const env = { ...process.env };
+    if (ctx.apiKey)
+        env.MODA_API_KEY = ctx.apiKey;
+    if (ctx.ingestUrl)
+        env.MODA_INGEST_URL = ctx.ingestUrl;
+    return ctx.runAgent({
+        adapter: ctx.adapter,
         prompt,
-        rootDir: cwd,
+        rootDir: ctx.cwd,
         mode: 'write',
-        stream: human || Boolean(options.onEvent),
+        env,
+        stream: ctx.human || Boolean(ctx.onEvent),
         progressToStderr: false,
-        onProgress: (message) => emit(message),
+        onProgress: (message) => ctx.emit(message),
         onAgentEvent: (event) => {
-            options.onEvent?.(event);
+            ctx.onEvent?.(event);
             const card = describeCodingAgentEvent(event);
             if (card)
-                emit(card);
+                ctx.emit(card);
         },
     });
+}
+/**
+ * Extract the agent result; on a protocol violation, re-prompt once for the
+ * result JSON. The protocol retry has its OWN single-use budget (it is a
+ * clarification, not a repair) and never consumes repair attempts — total
+ * agent invocations stay bounded at 1 initial + 1 protocol retry +
+ * maxRepairAttempts repairs.
+ */
+async function extractResultWithProtocolRetry(ctx, run, protocolRetryUsed, onProtocolRetry) {
     if (run.failedToStart) {
-        return { status: 'failed', adapter, detail: `${codingAgentDisplayName(adapter)} CLI failed to start.` };
+        return { agentFailed: { status: 'agent_failed', detail: 'CLI failed to start' } };
     }
     if (run.timedOut) {
-        return { status: 'failed', adapter, detail: `${codingAgentDisplayName(adapter)} timed out during SDK integration.` };
+        return { agentFailed: { status: 'agent_failed', detail: 'timed out' } };
     }
-    if (run.status !== 0) {
-        const tail = `${run.stdout}\n${run.stderr}`.trim().slice(-800);
+    let extraction = extractSdkAgentResult({ cwd: ctx.cwd, stdout: run.stdout, stderr: run.stderr });
+    if ('error' in extraction && !protocolRetryUsed) {
+        onProtocolRetry();
+        ctx.emit('Agent did not emit a valid result; requesting protocol retry…');
+        const retryRun = await invokeAgent(ctx, renderProtocolRetryPrompt(ctx.catalog.relativeDir));
+        if (retryRun.failedToStart) {
+            return { agentFailed: { status: 'agent_failed', detail: 'CLI failed to start' } };
+        }
+        if (retryRun.timedOut) {
+            return { agentFailed: { status: 'agent_failed', detail: 'timed out' } };
+        }
+        extraction = extractSdkAgentResult({
+            cwd: ctx.cwd,
+            stdout: retryRun.stdout,
+            stderr: retryRun.stderr,
+        });
+    }
+    if ('error' in extraction) {
+        const tail = redactOutputTail(`${run.stdout}\n${run.stderr}`, ctx.apiKey);
+        const exitNote = run.status !== 0 ? ` exited with status ${run.status ?? 'unknown'}.` : '.';
         return {
-            status: 'failed',
-            adapter,
-            detail: `${codingAgentDisplayName(adapter)} exited with status ${run.status ?? 'unknown'}.${tail ? `\n${tail}` : ''}`,
+            agentFailed: {
+                status: 'agent_failed',
+                detail: `SDK integration result protocol violation${exitNote}${tail ? `\n${tail}` : ''}`,
+            },
         };
     }
-    return { status: 'integrated', adapter, skillId: installedSkillId };
+    return { result: extraction.result };
 }
-const SAFETY_RULES = [
-    'Scope and safety rules:',
-    '- Only touch this repository (the working directory you were launched in).',
-    '- Install the Moda SDK with the package manager this repo already uses.',
-    '- Instrument the real LLM call sites; do not invent files or frameworks that are not here.',
-    '- Never write MODA_API_KEY (or any secret) into source files, and never create or edit',
-    '  .env files. The key belongs in the environment / a secret manager at runtime.',
-    '- Make the smallest correct change. Match the existing code style and imports.',
-    '- If something is ambiguous or the repo has no LLM calls to instrument, stop and explain',
-    '  rather than guessing.',
-];
-export function renderSdkIntegrationPrompt(context, skill = {}) {
-    const header = [
-        'You are running inside `moda init` as a one-shot SDK integration task. The user has',
-        'approved letting you install packages and edit source files in THIS repository to add',
-        'Moda LLM observability. Do the integration now — do not just describe it.',
-        '',
-        ...SAFETY_RULES,
-        '',
-        renderDetectionBlock(context),
-        '',
-    ];
-    const body = renderPromptBody(context, skill);
-    const footer = [
+function renderProtocolRetryPrompt(catalogDir) {
+    return [
+        'Your previous run did not emit a valid SDK integration result.',
+        'Write `.moda/sdk-integration-result.json` AND print the same JSON between',
+        `${SDK_RESULT_JSON_BEGIN} and ${SDK_RESULT_JSON_END} as your last output.`,
+        `Do not modify anything under ${catalogDir}.`,
         '',
-        'When finished, print a short summary of: the package(s) installed, the files you edited,',
-        'and any step a human still needs to do (e.g. setting MODA_API_KEY in the deploy env).',
-    ];
-    return [...header, ...body, ...footer].join('\n');
+        renderResultProtocolSection(),
+    ].join('\n');
+}
+function removeAgentResultFile(cwd) {
+    const path = join(cwd, SDK_RESULT_FILE);
+    try {
+        if (existsSync(path))
+            rmSync(path);
+    }
+    catch {
+        // Best-effort cleanup before CLI rewrites the final artifact.
+    }
+}
+async function mapAgentResultToOutcome(ctx, result) {
+    const agentDetail = (detail) => redactSecretText(detail, ctx.apiKey);
+    switch (result.status) {
+        case 'needs_human_input':
+            return {
+                status: 'needs_human_input',
+                detail: agentDetail(result.failure?.detail ?? result.summary),
+            };
+        case 'nothing_to_integrate': {
+            if (!result.smoke) {
+                return {
+                    status: 'nothing_to_integrate',
+                    detail: 'agent reports Moda is already integrated — not independently verified',
+                };
+            }
+            const verification = await verifyAgentSmoke(ctx);
+            if (verification.observed) {
+                return {
+                    status: 'nothing_to_integrate',
+                    detail: `existing integration verified — trace reached Moda (${verification.llm_spans} llm span(s))`,
+                    verification,
+                };
+            }
+            return {
+                status: 'nothing_to_integrate',
+                detail: 'agent reports Moda is already integrated — verification trace was not observed',
+                verification,
+            };
+        }
+        case 'repository_checks_failed':
+            return {
+                status: 'repository_checks_failed',
+                detail: agentDetail(result.failure?.detail ?? result.summary),
+                repairable: 'repository_checks_failed',
+            };
+        case 'smoke_execution_failed':
+            return {
+                status: 'smoke_execution_failed',
+                detail: agentDetail(result.failure?.detail ?? result.summary),
+                repairable: 'smoke_execution_failed',
+            };
+        case 'failed':
+            return {
+                status: 'agent_failed',
+                detail: agentDetail(result.failure?.detail ?? result.summary),
+                repairable: 'failed',
+            };
+        case 'integrated': {
+            const verification = await verifyAgentSmoke(ctx);
+            if (verification.observed) {
+                let detail = `trace reached Moda (${verification.llm_spans} llm span(s))`;
+                if (verification.duplicate_count > 0) {
+                    detail += `; warning: duplicate_count=${verification.duplicate_count}`;
+                }
+                return {
+                    status: 'integrated_verified',
+                    detail,
+                    verification,
+                };
+            }
+            return {
+                status: 'telemetry_not_observed',
+                detail: 'integration applied but the verification trace was not observed',
+                verification,
+                repairable: 'telemetry_not_observed',
+            };
+        }
+        default:
+            return { status: 'agent_failed', detail: agentDetail(result.summary) };
+    }
 }
 /**
- * Four-tier body, most-specific first:
- *   1. skill materialized on disk → point the agent at it;
- *   2. skill resolved but not materialized → inline its content so a detected
- *      stack never degrades to the generic checklist;
- *   3. skill resolved but its content is unavailable (bundle absent/unreadable)
- *      → generic checklist, but flagged as a degraded fallback and pinned to the
- *      detected stack so it is not silently treated as stack-less;
- *   4. nothing resolved (no language detected) → plain generic checklist.
+ * Independent exact-trace verification: the CLI polls the Data API for the
+ * CLI-minted verification id and requires >=1 llm span. Agent claims are never
+ * trusted as proof.
+ *
+ * ACCEPTED RISK (documented, not mitigated): the agent holds the tenant's
+ * MODA_API_KEY/MODA_INGEST_URL in its environment for the smoke run, so a
+ * deliberately deceptive agent could hand-craft an OTLP payload carrying the
+ * verification id + an llm span instead of exercising the instrumented app.
+ * The user's own coding agent operating on their own tenant is trusted not to
+ * be adversarial — the guards here target agent laziness, dishonest
+ * self-reports, and honest mistakes, not a malicious agent with the key. The
+ * same env access also means a prompt-injected agent could exfiltrate the key;
+ * the user approves this tradeoff in the plan step, and the deterministic
+ * secret scan + redaction limit accidental persistence/echoes.
  */
-function renderPromptBody(context, skill) {
-    if (skill.installedSkillId) {
-        const id = skill.installedSkillId;
-        return [
-            `Read \`.claude/skills/${id}/SKILL.md\` and follow its steps exactly, including its`,
-            `stop conditions. \`EXAMPLE.md\` in the same directory shows the finished integration —`,
-            'match its structure.',
-        ];
-    }
-    if (skill.inlineSkill) {
-        return [
-            `The bundled integration skill \`${skill.inlineSkill.skillId}\` matches this repo's stack,`,
-            'but could not be written to disk, so its full content is inlined below. Follow its steps',
-            'exactly, including its stop conditions:',
-            '',
-            '---',
-            '',
-            stripSkillFrontmatter(skill.inlineSkill.markdown).trim(),
-        ];
+async function verifyAgentSmoke(ctx) {
+    ctx.onPhase?.('verifying', 'Verifying trace in Moda…');
+    ctx.emit('Verifying trace in Moda…');
+    const evidence = await ctx.verify({
+        verificationId: ctx.verificationId,
+        timeoutMs: ctx.verifyTimeoutMs,
+        fetchAudit: ctx.fetchAudit,
+    });
+    // last_error carries arbitrary error text (the one evidence field that can),
+    // and the evidence lands verbatim in the outcome artifact and repair prompts.
+    return evidence.last_error !== undefined
+        ? { ...evidence, last_error: redactSecretText(evidence.last_error, ctx.apiKey) }
+        : evidence;
+}
+function installUsedSkills(result, catalog, cwd, emit) {
+    const validIds = new Set(catalog.index.skills.map((skill) => skill.id));
+    const installed = [];
+    const warnings = [];
+    for (const skillId of result.skills_used) {
+        if (!validIds.has(skillId)) {
+            warnings.push(`unknown skill id ${skillId}`);
+            continue;
+        }
+        try {
+            installIntegrationSkill(skillId, cwd);
+            installed.push(skillId);
+            emit(`Installed integration skill ${skillId} to .claude/skills/${skillId}/`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            warnings.push(`could not install ${skillId}: ${message}`);
+        }
     }
-    // Tiers 3 & 4 share one renderer: renderSdkIntegrationGuide flags the degraded
-    // fallback (and pins to the detection block) when a skill resolved but its
-    // content was unavailable, and renders the plain generic checklist otherwise.
-    return [
-        'Follow this Moda-authored integration checklist:',
-        '',
-        renderSdkIntegrationGuide(context, skill.resolvedSkillId),
-    ];
+    if (warnings.length > 0) {
+        emit(warnings.join('; '));
+    }
+    return installed;
+}
+function composeFinalDetail(status, detail, verification, apiKey, guardsDegraded) {
+    const baseDetail = detail ?? (status === 'integrated_verified' && verification
+        ? `verified — trace reached Moda (${verification.llm_spans} llm span(s))`
+        : undefined);
+    const combined = guardsDegraded
+        ? [baseDetail, DEGRADED_GUARDS_NOTE].filter(Boolean).join('; ')
+        : baseDetail;
+    return combined ? redactSecretText(combined, apiKey) : undefined;
+}
+function writeFinalOutcomeArtifact(cwd, payload) {
+    const path = join(cwd, SDK_RESULT_FILE);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify({
+        schema_version: OUTCOME_SCHEMA_VERSION,
+        status: payload.status,
+        verification_id: payload.verification_id,
+        verification: payload.verification,
+        agent_result: payload.agent_result,
+        repair_attempts: payload.repair_attempts,
+        ...(payload.security_findings ? { security_findings: payload.security_findings } : {}),
+        finished_at: new Date().toISOString(),
+    }, null, 2)}\n`);
+}
+export function redactSecretText(text, apiKey) {
+    let redacted = text;
+    for (const secret of [apiKey, process.env.MODA_API_KEY]) {
+        if (secret)
+            redacted = redacted.split(secret).join('[REDACTED]');
+    }
+    SECRET_KEY_PATTERN.lastIndex = 0;
+    return redacted.replace(SECRET_KEY_PATTERN, '[REDACTED]');
+}
+function sanitizeAgentResult(result, apiKey) {
+    return JSON.parse(redactSecretText(JSON.stringify(result), apiKey));
+}
+function redactOutputTail(output, apiKey) {
+    return redactSecretText(output, apiKey).trim().slice(-800);
 }
 //# sourceMappingURL=sdk-integration.js.map