@agentworkforce/persona-kit 0.19.0

package/dist/interactive-spec.js

@@ -0,0 +1,260 @@
+function stripProviderPrefix(model) {
+    const idx = model.indexOf('/');
+    return idx >= 0 ? model.slice(idx + 1) : model;
+}
+function hasAnyPermission(p) {
+    if (!p)
+        return false;
+    return Boolean(p.allow?.length || p.deny?.length || p.mode);
+}
+function hasCodexLaunchSettings(settings) {
+    if (!settings)
+        return false;
+    return Boolean(settings.sandboxMode ||
+        settings.approvalPolicy ||
+        settings.workspaceWriteNetworkAccess !== undefined ||
+        settings.webSearch);
+}
+/**
+ * Translate a persona's runtime fields into a concrete `{bin, args}` for
+ * spawning an interactive harness session. Pure — no I/O, no side effects.
+ *
+ * The claude branch always emits `--mcp-config` + `--strict-mcp-config`
+ * (with an empty `mcpServers: {}` payload if the persona declares none),
+ * so the spawned session only sees the persona's declared MCP servers,
+ * never the user's or project's Claude Code config.
+ *
+ * The codex branch carries the system prompt via `initialPrompt` because
+ * codex has no dedicated system-prompt flag today — callers append it as
+ * the final positional `[PROMPT]`.
+ *
+ * The opencode branch routes model + system prompt through opencode's
+ * agent abstraction (see https://opencode.ai/config.json: `agent.<id>.{
+ * model, prompt, mode }`). It emits an `opencode.json` via `configFiles`
+ * for the caller to materialize at cwd, and selects it with `--agent
+ * <personaId>`. It deliberately does NOT use `--prompt` (that flag
+ * pre-fills the TUI input with a user message) or bare `-m` (opencode
+ * expects full `provider/model` form and silently falls back to its
+ * default when given a stripped model name). `initialPrompt` is `null`
+ * so callers do not append a trailing positional, which opencode would
+ * otherwise interpret as a project directory.
+ *
+ * Both codex and opencode emit a warning if the persona declares
+ * `mcpServers` or `permissions` — those features aren't wired for those
+ * harnesses yet.
+ */
+export function buildInteractiveSpec(input) {
+    const { harness, personaId, model, systemPrompt, mcpServers, permissions, harnessSettings, pluginDirs } = input;
+    const warnings = [];
+    const hasPluginDirs = pluginDirs !== undefined && pluginDirs.length > 0;
+    switch (harness) {
+        case 'claude': {
+            const mcpPayload = JSON.stringify({ mcpServers: mcpServers ?? {} });
+            // Skip --append-system-prompt entirely when the persona's prompt is
+            // empty (e.g. an optional task-description input that wasn't
+            // forwarded). Personas should keep systemPrompt sparse — the harness
+            // already auto-loads CLAUDE.md / AGENTS.md from cwd, so the heavy
+            // operating spec lives in the sidecar and the systemPrompt is only
+            // worth setting when there's a concrete task to kick off with.
+            const args = [
+                '--model',
+                model,
+                ...(systemPrompt ? ['--append-system-prompt', systemPrompt] : []),
+                '--mcp-config',
+                mcpPayload,
+                '--strict-mcp-config'
+            ];
+            if (hasPluginDirs) {
+                for (const dir of pluginDirs) {
+                    args.push('--plugin-dir', dir);
+                }
+            }
+            if (permissions?.allow && permissions.allow.length > 0) {
+                args.push('--allowedTools', ...permissions.allow);
+            }
+            if (permissions?.deny && permissions.deny.length > 0) {
+                args.push('--disallowedTools', ...permissions.deny);
+            }
+            if (permissions?.mode) {
+                args.push('--permission-mode', permissions.mode);
+            }
+            if (hasCodexLaunchSettings(harnessSettings)) {
+                warnings.push('persona declares codex-only harnessSettings but the claude harness ignores sandboxMode, approvalPolicy, workspaceWriteNetworkAccess, and webSearch.');
+            }
+            return { bin: 'claude', args, initialPrompt: null, warnings, configFiles: [] };
+        }
+        case 'codex': {
+            if (mcpServers && Object.keys(mcpServers).length > 0) {
+                warnings.push('persona declares mcpServers but the codex harness is not yet wired for runtime MCP injection; proceeding without MCP.');
+            }
+            if (hasAnyPermission(permissions)) {
+                warnings.push('persona declares permissions but the codex harness is not yet wired for runtime permission injection; proceeding with codex defaults.');
+            }
+            if (hasPluginDirs) {
+                warnings.push('pluginDirs is currently claude-only; ignoring under the codex harness. Skills must be staged via codex conventions.');
+            }
+            const args = ['-m', stripProviderPrefix(model)];
+            if (harnessSettings?.sandboxMode) {
+                args.push('--sandbox', harnessSettings.sandboxMode);
+            }
+            if (harnessSettings?.approvalPolicy) {
+                args.push('--ask-for-approval', harnessSettings.approvalPolicy);
+            }
+            if (harnessSettings?.workspaceWriteNetworkAccess !== undefined) {
+                args.push('-c', `sandbox_workspace_write.network_access=${String(harnessSettings.workspaceWriteNetworkAccess)}`);
+            }
+            if (harnessSettings?.webSearch) {
+                args.push('--search');
+            }
+            return {
+                bin: 'codex',
+                args,
+                initialPrompt: systemPrompt,
+                warnings,
+                configFiles: []
+            };
+        }
+        case 'opencode': {
+            if (mcpServers && Object.keys(mcpServers).length > 0) {
+                warnings.push('persona declares mcpServers but the opencode harness is not yet wired for runtime MCP injection; proceeding without MCP.');
+            }
+            if (hasAnyPermission(permissions)) {
+                warnings.push('persona declares permissions but the opencode harness is not yet wired for runtime permission injection; proceeding with opencode defaults.');
+            }
+            if (hasPluginDirs) {
+                warnings.push('pluginDirs is currently claude-only; ignoring under the opencode harness. Skills must be staged via opencode conventions.');
+            }
+            if (hasCodexLaunchSettings(harnessSettings)) {
+                warnings.push('persona declares codex-only harnessSettings but the opencode harness ignores sandboxMode, approvalPolicy, workspaceWriteNetworkAccess, and webSearch.');
+            }
+            // opencode resolves a persona's system prompt + model through its own
+            // "agent" abstraction (see https://opencode.ai/config.json: `agent.<id>.{
+            // model, prompt, mode }`). Earlier revisions tried to use `--prompt` for
+            // the system prompt and `-m` for the model directly, but that was wrong
+            // on two counts:
+            //   (a) `--prompt` pre-fills the TUI input buffer with a *user* message,
+            //       not the agent's instructions — the persona's systemPrompt ended
+            //       up sitting unsent in the chat field.
+            //   (b) `-m` expects `provider/model` (opencode's own docs); stripping
+            //       the `opencode/` prefix left just `gpt-5-nano`, which opencode
+            //       could not resolve and silently fell back to its default model.
+            // The correct shape is an `opencode.json` under cwd defining an agent
+            // with the persona's prompt + full-provider-form model, selected via
+            // `--agent <personaId>` at launch. We emit that file via configFiles
+            // so the CLI can drop it into the mount dir before exec.
+            // `permission: { '*': 'allow' }` is wildcard-allow across every
+            // opencode tool (read / edit / bash / webfetch / etc.), matching the
+            // built-in `build` agent's effective permissions. Without this,
+            // opencode applies its restrictive default and agent-side edits never
+            // reach the mount (the user-visible symptom: "I asked the agent to
+            // change files and nothing synced"). The mount already sandboxes
+            // writes so wildcard-allow does not escape to the real repo outside
+            // of autosync, and callers who want a read-only persona (e.g. a code
+            // reviewer) can override this in a follow-up PR that threads a
+            // richer permission spec through the persona config — the current
+            // harness-kit PersonaPermissions shape is claude-specific and
+            // already warned about for opencode.
+            //
+            // The bare-string form `permission: 'allow'` was valid in older
+            // opencode versions but is rejected by 1.14.x: the agent decoder
+            // runs `Object.assign({}, $.permission)` before the schema's own
+            // string→`{'*': str}` normalizer fires, which spreads the string's
+            // indexed chars and then fails validation against
+            // `'ask' | 'allow' | 'deny'` ("Expected PermissionActionConfig, got
+            // 'a' / 'l' / 'l' / 'o' / 'w'"). Emitting the object form directly
+            // avoids that pre-decode step.
+            // Omit `prompt` when the persona's systemPrompt is empty so opencode
+            // falls back to the AGENTS.md that the harness auto-loads from cwd.
+            // Personas should keep systemPrompt sparse — see the claude branch
+            // above for the rationale.
+            const agentConfig = {
+                agent: {
+                    [personaId]: {
+                        model,
+                        ...(systemPrompt ? { prompt: systemPrompt } : {}),
+                        mode: 'primary',
+                        permission: { '*': 'allow' }
+                    }
+                }
+            };
+            return {
+                bin: 'opencode',
+                args: ['--agent', personaId],
+                initialPrompt: null,
+                warnings,
+                configFiles: [
+                    {
+                        path: 'opencode.json',
+                        contents: JSON.stringify(agentConfig, null, 2) + '\n'
+                    }
+                ]
+            };
+        }
+        default: {
+            // Exhaustiveness guard: if `Harness` gains a new variant, this
+            // assertion will fail to compile and force the maintainer to handle
+            // the new case above rather than silently dropping into an untyped
+            // fallthrough at runtime.
+            const _exhaustive = harness;
+            throw new Error(`Unhandled harness: ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Translate a persona's runtime into a non-interactive, one-shot command.
+ * Layers harness-specific non-interactive flags on top of {@link buildInteractiveSpec},
+ * then appends the user task. Pure — no I/O.
+ *
+ * - `claude`: appends `--print --output-format text [--name <n>] <task>`.
+ * - `codex`:  prefixes `exec`, appends `--skip-git-repo-check`, then a prompt
+ *   built from any `initialPrompt` joined with the user task.
+ * - `opencode`: prefixes `run`, appends `--model <m> --format default
+ *   [--dir <cwd>] [--title <n>] <task>`.
+ */
+export function buildNonInteractiveSpec(input) {
+    const interactive = buildInteractiveSpec(input);
+    switch (input.harness) {
+        case 'claude': {
+            const args = [...interactive.args, '--print', '--output-format', 'text'];
+            if (input.name)
+                args.push('--name', input.name);
+            args.push(input.task);
+            return {
+                bin: interactive.bin,
+                args,
+                configFiles: interactive.configFiles,
+                warnings: interactive.warnings
+            };
+        }
+        case 'codex': {
+            const prompt = interactive.initialPrompt
+                ? `${interactive.initialPrompt}\n\nUser task:\n${input.task}`
+                : input.task;
+            return {
+                bin: interactive.bin,
+                args: ['exec', ...interactive.args, '--skip-git-repo-check', prompt],
+                configFiles: interactive.configFiles,
+                warnings: interactive.warnings
+            };
+        }
+        case 'opencode': {
+            const args = ['run', ...interactive.args, '--model', input.model, '--format', 'default'];
+            if (input.workingDirectory)
+                args.push('--dir', input.workingDirectory);
+            if (input.name)
+                args.push('--title', input.name);
+            args.push(input.task);
+            return {
+                bin: interactive.bin,
+                args,
+                configFiles: interactive.configFiles,
+                warnings: interactive.warnings
+            };
+        }
+        default: {
+            const _exhaustive = input.harness;
+            throw new Error(`Unhandled harness: ${String(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=interactive-spec.js.map

package/dist/interactive-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-spec.js","sourceRoot":"","sources":["../src/interactive-spec.ts"],"names":[],"mappings":"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"}

package/dist/interactive-spec.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interactive-spec.test.d.ts.map

package/dist/interactive-spec.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-spec.test.d.ts","sourceRoot":"","sources":["../src/interactive-spec.test.ts"],"names":[],"mappings":""}

package/dist/interactive-spec.test.js

@@ -0,0 +1,308 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { buildInteractiveSpec } from './interactive-spec.js';
+test('claude branch always emits --mcp-config + --strict-mcp-config', () => {
+    const result = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'you are a test'
+    });
+    assert.equal(result.bin, 'claude');
+    assert.equal(result.initialPrompt, null);
+    assert.deepEqual(result.warnings, []);
+    // Both flags present even with no mcpServers — forces isolation from
+    // user/project Claude Code config.
+    const args = result.args;
+    const mcpIdx = args.indexOf('--mcp-config');
+    assert.ok(mcpIdx >= 0, 'expected --mcp-config');
+    assert.equal(args[mcpIdx + 1], '{"mcpServers":{}}');
+    assert.ok(args.includes('--strict-mcp-config'));
+    assert.ok(args.includes('--model'));
+    assert.ok(args.includes('--append-system-prompt'));
+});
+test('claude branch serializes resolved mcpServers into the --mcp-config payload', () => {
+    const result = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-sonnet-4-6',
+        systemPrompt: 'x',
+        mcpServers: {
+            posthog: {
+                type: 'http',
+                url: 'https://mcp.posthog.com/mcp',
+                headers: { Authorization: 'Bearer phx_real' }
+            }
+        }
+    });
+    const mcpIdx = result.args.indexOf('--mcp-config');
+    const payload = JSON.parse(result.args[mcpIdx + 1]);
+    assert.deepEqual(payload, {
+        mcpServers: {
+            posthog: {
+                type: 'http',
+                url: 'https://mcp.posthog.com/mcp',
+                headers: { Authorization: 'Bearer phx_real' }
+            }
+        }
+    });
+});
+test('claude branch translates permissions to flags', () => {
+    const result = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'x',
+        permissions: {
+            allow: ['mcp__posthog', 'Bash(git *)'],
+            deny: ['Bash(rm -rf *)'],
+            mode: 'acceptEdits'
+        }
+    });
+    const args = result.args;
+    const allowIdx = args.indexOf('--allowedTools');
+    const denyIdx = args.indexOf('--disallowedTools');
+    const modeIdx = args.indexOf('--permission-mode');
+    assert.ok(allowIdx >= 0 && denyIdx >= 0 && modeIdx >= 0);
+    assert.equal(args[allowIdx + 1], 'mcp__posthog');
+    assert.equal(args[allowIdx + 2], 'Bash(git *)');
+    assert.equal(args[denyIdx + 1], 'Bash(rm -rf *)');
+    assert.equal(args[modeIdx + 1], 'acceptEdits');
+});
+test('claude branch omits permission flags when unset or empty', () => {
+    const result = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'x',
+        permissions: { allow: [], deny: [] }
+    });
+    assert.ok(!result.args.includes('--allowedTools'));
+    assert.ok(!result.args.includes('--disallowedTools'));
+    assert.ok(!result.args.includes('--permission-mode'));
+});
+test('codex carries system prompt as initial positional; strips provider prefix from model', () => {
+    const result = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'openai-codex/gpt-5.3-codex',
+        systemPrompt: 'system-directive'
+    });
+    assert.equal(result.bin, 'codex');
+    assert.deepEqual(result.args, ['-m', 'gpt-5.3-codex']);
+    assert.equal(result.initialPrompt, 'system-directive');
+});
+test('codex translates sandbox harness settings to launch flags', () => {
+    const result = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'openai-codex/gpt-5.3-codex',
+        systemPrompt: 'x',
+        harnessSettings: {
+            reasoning: 'high',
+            timeoutSeconds: 1200,
+            sandboxMode: 'workspace-write',
+            approvalPolicy: 'on-request',
+            workspaceWriteNetworkAccess: true,
+            webSearch: true
+        }
+    });
+    assert.deepEqual(result.args, [
+        '-m',
+        'gpt-5.3-codex',
+        '--sandbox',
+        'workspace-write',
+        '--ask-for-approval',
+        'on-request',
+        '-c',
+        'sandbox_workspace_write.network_access=true',
+        '--search'
+    ]);
+});
+test('codex warns when mcpServers / permissions are declared', () => {
+    const result = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'openai-codex/gpt-5.3-codex',
+        systemPrompt: 'x',
+        mcpServers: { foo: { type: 'http', url: 'https://example.com' } },
+        permissions: { allow: ['mcp__foo'] }
+    });
+    assert.equal(result.warnings.length, 2);
+    assert.match(result.warnings[0], /codex harness is not yet wired for runtime MCP/);
+    assert.match(result.warnings[1], /codex harness is not yet wired for runtime permission/);
+});
+test('opencode defines a per-persona agent in opencode.json and selects it with --agent', () => {
+    const result = buildInteractiveSpec({
+        harness: 'opencode',
+        personaId: 'test-persona',
+        model: 'opencode/minimax-m2.5',
+        systemPrompt: 'you are a test'
+    });
+    assert.equal(result.bin, 'opencode');
+    // No --prompt (that flag pre-fills the TUI input with the system prompt as
+    // a *user* message) and no bare -m (opencode's -m expects provider/model;
+    // earlier code stripped the provider and silently fell back to the default
+    // model). Model + system prompt now live in the emitted opencode.json,
+    // selected by persona id via --agent.
+    assert.deepEqual(result.args, ['--agent', 'test-persona']);
+    assert.ok(!result.args.includes('--prompt'));
+    assert.ok(!result.args.includes('--model'));
+    assert.ok(!result.args.includes('-m'));
+    assert.equal(result.initialPrompt, null);
+});
+test('opencode configFiles carries a well-formed opencode.json with the agent definition', () => {
+    const result = buildInteractiveSpec({
+        harness: 'opencode',
+        personaId: 'test-persona',
+        model: 'opencode/minimax-m2.5',
+        systemPrompt: 'you are a test'
+    });
+    assert.equal(result.configFiles.length, 1);
+    const [file] = result.configFiles;
+    assert.equal(file.path, 'opencode.json');
+    const parsed = JSON.parse(file.contents);
+    assert.deepEqual(parsed, {
+        agent: {
+            'test-persona': {
+                model: 'opencode/minimax-m2.5',
+                prompt: 'you are a test',
+                mode: 'primary',
+                // Wildcard-allow across opencode's tool set — matches the built-in
+                // `build` agent. Without this, opencode's restrictive default kept
+                // agents from making any edits and autosync had nothing to
+                // propagate on exit. Object form (not bare 'allow' string) because
+                // opencode 1.14.x's agent-config decoder Object.assigns the value
+                // before its string-normalizer runs, which mangles strings into
+                // their indexed chars.
+                permission: { '*': 'allow' }
+            }
+        }
+    });
+});
+test('claude and codex emit an empty configFiles array', () => {
+    const claude = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'x'
+    });
+    assert.deepEqual(claude.configFiles, []);
+    const codex = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'openai-codex/gpt-5.3-codex',
+        systemPrompt: 'x'
+    });
+    assert.deepEqual(codex.configFiles, []);
+});
+test('claude branch omits --append-system-prompt when systemPrompt is empty', () => {
+    // Empty systemPrompt is the persona's signal that no kickoff message is
+    // intended (e.g. an optional task input that wasn't forwarded). The
+    // harness still auto-loads CLAUDE.md from cwd, so the agent has its
+    // operating spec; we just don't want a stray `--append-system-prompt ''`
+    // flag steering behavior on every turn.
+    const result = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: ''
+    });
+    assert.ok(!result.args.includes('--append-system-prompt'));
+    // strict-mcp still emitted — that's about isolation, not the prompt.
+    assert.ok(result.args.includes('--strict-mcp-config'));
+});
+test('opencode omits agent.prompt when systemPrompt is empty', () => {
+    const result = buildInteractiveSpec({
+        harness: 'opencode',
+        personaId: 'test-persona',
+        model: 'opencode/minimax-m2.5',
+        systemPrompt: ''
+    });
+    const [file] = result.configFiles;
+    const parsed = JSON.parse(file.contents);
+    assert.equal(parsed.agent['test-persona'].prompt, undefined);
+    assert.equal(parsed.agent['test-persona'].model, 'opencode/minimax-m2.5');
+    assert.equal(parsed.agent['test-persona'].mode, 'primary');
+});
+test('codex passes empty systemPrompt through as a falsy initialPrompt', () => {
+    // Caller appends initialPrompt only when truthy, so an empty
+    // systemPrompt produces a TUI-only launch with no kickoff message.
+    const result = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'openai-codex/gpt-5.3-codex',
+        systemPrompt: ''
+    });
+    assert.equal(result.initialPrompt, '');
+});
+test('claude branch appends --plugin-dir per entry in pluginDirs', () => {
+    const result = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'x',
+        pluginDirs: ['/tmp/session-a/claude/plugin', '/tmp/session-b/claude/plugin']
+    });
+    const args = result.args;
+    const indices = [];
+    args.forEach((a, i) => {
+        if (a === '--plugin-dir')
+            indices.push(i);
+    });
+    assert.equal(indices.length, 2);
+    assert.equal(args[indices[0] + 1], '/tmp/session-a/claude/plugin');
+    assert.equal(args[indices[1] + 1], '/tmp/session-b/claude/plugin');
+    assert.deepEqual(result.warnings, []);
+});
+test('claude branch omits --plugin-dir when pluginDirs is empty or absent', () => {
+    const withEmpty = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'x',
+        pluginDirs: []
+    });
+    const without = buildInteractiveSpec({
+        harness: 'claude',
+        personaId: 'test-persona',
+        model: 'claude-opus-4-6',
+        systemPrompt: 'x'
+    });
+    assert.ok(!withEmpty.args.includes('--plugin-dir'));
+    assert.ok(!without.args.includes('--plugin-dir'));
+});
+test('non-claude harnesses warn and ignore pluginDirs', () => {
+    const codex = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'x',
+        systemPrompt: 'x',
+        pluginDirs: ['/tmp/session/plugin']
+    });
+    assert.ok(!codex.args.includes('--plugin-dir'));
+    assert.ok(codex.warnings.some((w) => /pluginDirs is currently claude-only/.test(w)));
+    const opencode = buildInteractiveSpec({
+        harness: 'opencode',
+        personaId: 'test-persona',
+        model: 'x',
+        systemPrompt: 'x',
+        pluginDirs: ['/tmp/session/plugin']
+    });
+    assert.ok(!opencode.args.includes('--plugin-dir'));
+    assert.ok(opencode.warnings.some((w) => /pluginDirs is currently claude-only/.test(w)));
+});
+test('warnings are returned, not printed — library consumers route I/O themselves', () => {
+    // Ensure no side effects on stderr: if the function wrote to stderr, this
+    // test would leak output into the test runner. We just assert the shape.
+    const result = buildInteractiveSpec({
+        harness: 'codex',
+        personaId: 'test-persona',
+        model: 'x',
+        systemPrompt: 'x',
+        mcpServers: { a: { type: 'http', url: 'https://x' } }
+    });
+    assert.ok(Array.isArray(result.warnings));
+    assert.equal(result.warnings.length, 1);
+});
+//# sourceMappingURL=interactive-spec.test.js.map

package/dist/interactive-spec.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive-spec.test.js","sourceRoot":"","sources":["../src/interactive-spec.test.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -0,0 +1,35 @@
+import type { McpServerSpec } from './types.js';
+import { type DroppedRef } from './env-refs.js';
+export interface DroppedMcpServer {
+    name: string;
+    /** Env var names that couldn't be resolved on the server's structural fields. */
+    refs: string[];
+}
+export interface McpResolution {
+    /** Servers that resolved cleanly (or with only droppable-field losses). */
+    servers: Record<string, McpServerSpec> | undefined;
+    /** Non-fatal drops — specific headers / env / args entries whose ref was unset. */
+    dropped: DroppedRef[];
+    /** Whole servers dropped because a structural field (url, command, any arg) had an unset ref. */
+    droppedServers: DroppedMcpServer[];
+}
+/**
+ * Resolve env-var references inside an `mcpServers` block, policy: lenient.
+ *
+ * - Headers / env / args entries with an unresolved ref are **dropped** from
+ *   the result; they surface in `dropped`.
+ * - A server whose `url`, `command`, or any `arg` references an unresolved
+ *   ref is dropped **entirely**; it surfaces in `droppedServers`. Structural
+ *   fields can't be silently skipped — the server wouldn't launch without
+ *   them.
+ *
+ * Literal strings pass through untouched.
+ */
+export declare function resolveMcpServersLenient(servers: Record<string, McpServerSpec> | undefined, processEnv: NodeJS.ProcessEnv): McpResolution;
+/**
+ * Format the dropped-ref tracking from env + MCP resolution into flat,
+ * human-readable lines. Callers print them wherever they want — stderr,
+ * a logger, a UI toast — the helper itself has no I/O.
+ */
+export declare function formatDropWarnings(envDrops: DroppedRef[], mcpDrops: DroppedRef[], mcpServerDrops: DroppedMcpServer[]): string[];
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,KAAK,UAAU,EAAgD,MAAM,eAAe,CAAC;AAE9F,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,CAAC;IACnD,mFAAmF;IACnF,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,iGAAiG;IACjG,cAAc,EAAE,gBAAgB,EAAE,CAAC;CACpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,SAAS,EAClD,UAAU,EAAE,MAAM,CAAC,UAAU,GAC5B,aAAa,CA0Df;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,UAAU,EAAE,EACtB,QAAQ,EAAE,UAAU,EAAE,EACtB,cAAc,EAAE,gBAAgB,EAAE,GACjC,MAAM,EAAE,CAcV"}