@sweny-ai/core 0.1.125 → 0.1.127

package/dist/agent-env.d.ts

@@ -58,11 +58,48 @@ export interface BuildAgentEnvOpts {
 export declare function resolveEnvScope(env: Record<string, string | undefined>, explicit?: boolean, logger?: Pick<Logger, "warn">): boolean;
 /** Max names listed in the withheld-vars warning before "and N more". */
 export declare const WITHHELD_WARNING_CAP = 30;
+/**
+ * Runner baseline: exact names set by common CI images (GitHub-hosted runner
+ * image, Actions runner context, Debian-based containers). They are present on
+ * every run, so listing them as "withheld" is noise. Names only; none of these
+ * is a credential the operator supplied. Secrets such as `GITHUB_TOKEN`,
+ * `NPM_TOKEN`, or `AWS_*` are deliberately absent, so withholding them still
+ * warns.
+ */
+export declare const RUNNER_BASELINE_VARS: ReadonlySet<string>;
+/**
+ * Runner baseline: name patterns for families the CI images set in bulk
+ * (Actions runner internals, Android/Java/.NET/Go/Python toolchains, browsers
+ * and webdrivers, Azure CLI, vcpkg, ghcup, ...). `AWS_*`, `NPM_*` and
+ * `GITHUB_TOKEN`-style names are intentionally not matched.
+ */
+export declare const RUNNER_BASELINE_PATTERNS: readonly RegExp[];
+/** True when `name` is set by the CI image itself, not by the workflow author. */
+export declare function isRunnerBaselineVar(name: string): boolean;
+/** Split withheld names into the runner baseline and everything else. */
+export declare function classifyWithheld(withheld: readonly string[]): {
+    baseline: string[];
+    other: string[];
+};
 /**
  * One-line warning naming the withheld variables. Names only, never values;
  * sorted; capped at {@link WITHHELD_WARNING_CAP}.
  */
 export declare function formatWithheldWarning(withheld: readonly string[]): string;
+/** Plain-log summary: counts only, no names. */
+export declare function formatScopeSummary(total: number, baseline: number): string;
+/** Test seam: forget that the withheld notice was already emitted. */
+export declare function resetWithheldReport(): void;
+/**
+ * Report withheld env names, once per process (not per node or per client).
+ *
+ * - always: one plain `info` line with counts (not a `::warning::` annotation);
+ * - only when non-baseline names were withheld: a `warn` listing just those
+ *   (capped), as a `::warning title=SWEny agent env::` annotation under GitHub
+ *   Actions;
+ * - `debug` (shown with `--verbose`): every withheld name.
+ */
+export declare function reportWithheldEnv(withheld: readonly string[], logger: Pick<Logger, "info" | "warn" | "debug">, env?: Record<string, string | undefined>): void;
 /**
  * Scope the agent env and report which variable names were withheld.
  * `withheld` holds names only; values never leave `source`.

package/dist/agent-env.js

@@ -159,6 +159,100 @@ export function resolveEnvScope(env, explicit, logger) {
 }
 /** Max names listed in the withheld-vars warning before "and N more". */
 export const WITHHELD_WARNING_CAP = 30;
+/**
+ * Runner baseline: exact names set by common CI images (GitHub-hosted runner
+ * image, Actions runner context, Debian-based containers). They are present on
+ * every run, so listing them as "withheld" is noise. Names only; none of these
+ * is a credential the operator supplied. Secrets such as `GITHUB_TOKEN`,
+ * `NPM_TOKEN`, or `AWS_*` are deliberately absent, so withholding them still
+ * warns.
+ */
+export const RUNNER_BASELINE_VARS = new Set([
+    // image / OS
+    "ImageOS",
+    "ImageVersion",
+    "ACCEPT_EULA",
+    "DEBIAN_FRONTEND",
+    "AGENT_TOOLSDIRECTORY",
+    "CONDA",
+    "SWIFT_PATH",
+    "LEIN_HOME",
+    "LEIN_JAR",
+    "ANT_HOME",
+    "GRADLE_HOME",
+    "M2_HOME",
+    "SELENIUM_JAR_PATH",
+    "ENABLE_RUNNER_TRACING",
+    "INVOCATION_ID",
+    "JOURNAL_STREAM",
+    "SYSTEMD_EXEC_PID",
+    "MANAGERPID",
+    "OLDPWD",
+    "PWD",
+    "SHLVL",
+    "_",
+    // GitHub Actions context (never GITHUB_TOKEN)
+    "GITHUB_ACTION",
+    "GITHUB_ACTION_PATH",
+    "GITHUB_ACTION_REF",
+    "GITHUB_ACTION_REPOSITORY",
+    "GITHUB_ACTOR",
+    "GITHUB_ACTOR_ID",
+    "GITHUB_ENV",
+    "GITHUB_EVENT_PATH",
+    "GITHUB_GRAPHQL_URL",
+    "GITHUB_JOB",
+    "GITHUB_OUTPUT",
+    "GITHUB_PATH",
+    "GITHUB_REF_PROTECTED",
+    "GITHUB_REF_TYPE",
+    "GITHUB_REPOSITORY_ID",
+    "GITHUB_REPOSITORY_OWNER_ID",
+    "GITHUB_RETENTION_DAYS",
+    "GITHUB_RUN_ATTEMPT",
+    "GITHUB_STATE",
+    "GITHUB_STEP_SUMMARY",
+    "GITHUB_TRIGGERING_ACTOR",
+    "GITHUB_WORKFLOW",
+    "GITHUB_WORKFLOW_REF",
+    "GITHUB_WORKFLOW_SHA",
+]);
+/**
+ * Runner baseline: name patterns for families the CI images set in bulk
+ * (Actions runner internals, Android/Java/.NET/Go/Python toolchains, browsers
+ * and webdrivers, Azure CLI, vcpkg, ghcup, ...). `AWS_*`, `NPM_*` and
+ * `GITHUB_TOKEN`-style names are intentionally not matched.
+ */
+export const RUNNER_BASELINE_PATTERNS = [
+    /^ACTIONS_/,
+    /^RUNNER_/,
+    /^ANDROID_/,
+    /^JAVA_HOME(_|$)/,
+    /^CHROME/,
+    /WEBDRIVER$/,
+    /^DOTNET_/,
+    /^GOROOT(_|$)/,
+    /^PIPX_/,
+    /^POWERSHELL_/,
+    /^VCPKG_/,
+    /^GHCUP_/,
+    /^BOOTSTRAP_HASKELL_/,
+    /^AZURE_(EXTENSION_DIR|HTTP_USER_AGENT|CONFIG_DIR)$/,
+    /^HOMEBREW_/,
+    /^STATS_/,
+];
+/** True when `name` is set by the CI image itself, not by the workflow author. */
+export function isRunnerBaselineVar(name) {
+    return RUNNER_BASELINE_VARS.has(name) || RUNNER_BASELINE_PATTERNS.some((re) => re.test(name));
+}
+/** Split withheld names into the runner baseline and everything else. */
+export function classifyWithheld(withheld) {
+    const baseline = [];
+    const other = [];
+    for (const n of withheld)
+        (isRunnerBaselineVar(n) ? baseline : other).push(n);
+    return { baseline: baseline.sort(), other: other.sort() };
+}
 /**
  * One-line warning naming the withheld variables. Names only, never values;
  * sorted; capped at {@link WITHHELD_WARNING_CAP}.
@@ -171,6 +265,37 @@ export function formatWithheldWarning(withheld) {
         `If a node's commands need any of them, add the names to env-passthrough ` +
         `(SWENY_ENV_PASSTHROUGH), or set env-scope: off (SWENY_ENV_SCOPE=off).`);
 }
+/** Plain-log summary: counts only, no names. */
+export function formatScopeSummary(total, baseline) {
+    return (`sweny: agent env scoped (${total} withheld, ${baseline} from the CI image). ` +
+        `Add names to env-passthrough if a node needs them; --verbose lists them.`);
+}
+let withheldReported = false;
+/** Test seam: forget that the withheld notice was already emitted. */
+export function resetWithheldReport() {
+    withheldReported = false;
+}
+/**
+ * Report withheld env names, once per process (not per node or per client).
+ *
+ * - always: one plain `info` line with counts (not a `::warning::` annotation);
+ * - only when non-baseline names were withheld: a `warn` listing just those
+ *   (capped), as a `::warning title=SWEny agent env::` annotation under GitHub
+ *   Actions;
+ * - `debug` (shown with `--verbose`): every withheld name.
+ */
+export function reportWithheldEnv(withheld, logger, env = process.env) {
+    if (withheld.length === 0 || withheldReported)
+        return;
+    withheldReported = true;
+    const { baseline, other } = classifyWithheld(withheld);
+    logger.info(formatScopeSummary(withheld.length, baseline.length));
+    if (other.length > 0) {
+        const prefix = env.GITHUB_ACTIONS === "true" ? "::warning title=SWEny agent env::" : "";
+        logger.warn(`${prefix}${formatWithheldWarning(other)}`);
+    }
+    logger.debug(`sweny: agent env withheld: ${[...withheld].sort().join(", ")}`);
+}
 /**
  * Scope the agent env and report which variable names were withheld.
  * `withheld` holds names only; values never leave `source`.

package/dist/claude.d.ts

@@ -78,7 +78,9 @@ export interface ClaudeClientOptions {
     logger?: Logger;
     /** Default tool context for standalone usage (not via executor) */
     defaultContext?: ToolContext;
-    /** External MCP servers (GitHub, Linear, Sentry, etc.) — merged with core skill tools */
+    /** Catalog defaults, overridden by per-run skill servers and explicit mcpServers. */
+    defaultMcpServers?: Record<string, McpServerConfig>;
+    /** Explicit external MCP servers, overriding defaults and per-run skill servers. */
     mcpServers?: Record<string, McpServerConfig>;
     /**
      * Extra env var names passed to the agent subprocess on top of the
@@ -123,13 +125,13 @@ export declare class ClaudeClient implements Claude {
     private logger;
     private defaultContext;
     private mcpServers;
+    private defaultMcpServers;
     private envPassthrough;
     private sandboxMode;
     private sandboxAllowedDomains;
     private sandboxProbe;
     private sandboxWarned;
     private envScope;
-    private envWarned;
     constructor(opts?: ClaudeClientOptions);
     /**
      * Build env for the Claude Code subprocess (#360). Applies auth precedence
@@ -137,8 +139,8 @@ export declare class ClaudeClient implements Claude {
      * `SWENY_AUTH`). When env scoping is on (default in CI, see
      * {@link resolveEnvScope}) the result is narrowed to the allowlist plus
      * `extraVars` (the node's declared skill env vars) and the operator
-     * passthrough list, and the withheld names (never values) are warned once
-     * per client. When off, the full env passes through as before.
+     * passthrough list, and the withheld names (never values) are reported once
+     * per process ({@link reportWithheldEnv}). When off, the full env passes through as before.
      */
     private buildEnv;
     run(opts: {
@@ -154,6 +156,8 @@ export declare class ClaudeClient implements Claude {
         timeoutMs?: number;
         /** Caller-supplied abort signal. Aborting it interrupts the query. */
         signal?: AbortSignal;
+        /** MCP servers declared by the current node's skills. */
+        mcpServers?: Record<string, McpServerConfig>;
         /** Dry run (#380): no external MCP servers, no write-capable built-ins. */
         readOnly?: boolean;
         /** Env var names + sandbox hosts this node's skills need (#360). */

package/dist/claude.js

@@ -11,7 +11,7 @@
 import { query, createSdkMcpServer, tool as sdkTool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
 import { consoleLogger } from "./types.js";
-import { formatWithheldWarning, parseList, resolveEnvScope, scopeAgentEnv, resolveAgentSandbox, } from "./agent-env.js";
+import { reportWithheldEnv, parseList, resolveEnvScope, scopeAgentEnv, resolveAgentSandbox, } from "./agent-env.js";
 import { fenceUntrustedJson } from "./untrusted.js";
 const SYSTEM_PROMPT = `You are a step in an automated workflow. Execute the instruction precisely using the tools available to you. Be thorough but concise. When you're done, summarize your findings and results.`;
 /**
@@ -211,13 +211,13 @@ export class ClaudeClient {
     logger;
     defaultContext;
     mcpServers;
+    defaultMcpServers;
     envPassthrough;
     sandboxMode;
     sandboxAllowedDomains;
     sandboxProbe;
     sandboxWarned = false;
     envScope;
-    envWarned = false;
     constructor(opts = {}) {
         this.model = opts.model;
         this.maxTurns = opts.maxTurns ?? 20;
@@ -225,6 +225,7 @@ export class ClaudeClient {
         this.logger = opts.logger ?? consoleLogger;
         this.defaultContext = opts.defaultContext ?? { config: {}, logger: this.logger };
         this.mcpServers = opts.mcpServers ?? {};
+        this.defaultMcpServers = opts.defaultMcpServers ?? {};
         this.envPassthrough = opts.envPassthrough;
         this.envScope = opts.envScope;
         this.sandboxMode = opts.sandbox;
@@ -237,8 +238,8 @@ export class ClaudeClient {
      * `SWENY_AUTH`). When env scoping is on (default in CI, see
      * {@link resolveEnvScope}) the result is narrowed to the allowlist plus
      * `extraVars` (the node's declared skill env vars) and the operator
-     * passthrough list, and the withheld names (never values) are warned once
-     * per client. When off, the full env passes through as before.
+     * passthrough list, and the withheld names (never values) are reported once
+     * per process ({@link reportWithheldEnv}). When off, the full env passes through as before.
      */
     buildEnv(extraVars = []) {
         const full = Object.fromEntries(Object.entries(process.env).filter((e) => e[1] != null));
@@ -250,11 +251,7 @@ export class ClaudeClient {
             passthrough: this.envPassthrough ?? parseList(process.env.SWENY_ENV_PASSTHROUGH),
             logger: this.logger,
         });
-        if (withheld.length > 0 && !this.envWarned) {
-            this.envWarned = true;
-            const prefix = process.env.GITHUB_ACTIONS === "true" ? "::warning title=SWEny agent env::" : "";
-            this.logger.warn(`${prefix}${formatWithheldWarning(withheld)}`);
-        }
+        reportWithheldEnv(withheld, this.logger);
         return env;
     }
     async run(opts) {
@@ -344,7 +341,9 @@ export class ClaudeClient {
         const abort = makeAbort(timeoutMs, signal);
         let stream;
         try {
-            const allMcpServers = readOnly ? {} : { ...this.mcpServers };
+            const allMcpServers = readOnly
+                ? {}
+                : { ...this.defaultMcpServers, ...opts.mcpServers, ...this.mcpServers };
             if (sdkTools.length > 0)
                 allMcpServers["sweny-core"] = mcpServer;
             stream = query({

package/dist/cli/main.js

@@ -204,7 +204,8 @@ triageCmd.action(async (options) => {
         maxTurns: config.maxInvestigateTurns || 50,
         cwd: process.cwd(),
         logger: consoleLogger,
-        mcpServers,
+        defaultMcpServers: mcpServers,
+        mcpServers: config.mcpServers,
     });
     // ── Progress display state ─────────────────────────────────
     const FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
@@ -513,7 +514,8 @@ implementCmd.action(async (issueId, options) => {
         maxTurns: config.maxImplementTurns || 40,
         cwd: process.cwd(),
         logger: consoleLogger,
-        mcpServers,
+        defaultMcpServers: mcpServers,
+        mcpServers: config.mcpServers,
     });
     console.log(chalk.cyan(`\n  sweny implement ${issueId}\n`));
     const implRunStart = Date.now();
@@ -756,7 +758,8 @@ export async function workflowRunAction(file, options) {
         maxTurns: config.maxInvestigateTurns || 50,
         cwd: process.cwd(),
         logger: runLogger,
-        mcpServers,
+        defaultMcpServers: mcpServers,
+        mcpServers: config.mcpServers,
         model: workflow.model,
     });
     // Track per-node entry time to compute elapsed on exit

package/dist/executor.js

@@ -148,12 +148,16 @@ export async function execute(workflow, input, options) {
             logger.info(`  dry run: withheld write tools: ${skippedWrites.join(", ")}`, { node: currentId });
         }
         const skillInstructions = resolveSkillInstructions(node.skills, skills);
+        const skillMcpServers = resolveSkillMcpServers(node.skills, skills);
         // Runtime guard: if this node declares skills but none resolved, the node
         // cannot do its job (e.g. "create a Linear issue" with no linear skill).
         // The startup validate() warns about this possibility, but only throw when
         // the node is actually reached — unreachable nodes with missing skills are fine.
-        // Instruction-only skills (no tools) are valid — they inject context into the prompt.
-        if (node.skills.length > 0 && resolvedSkillTools.length === 0 && skillInstructions.length === 0) {
+        // Instruction-only and resolved MCP-only skills are valid capabilities.
+        if (node.skills.length > 0 &&
+            resolvedSkillTools.length === 0 &&
+            skillInstructions.length === 0 &&
+            Object.keys(skillMcpServers).length === 0) {
             throw new Error(`Node "${currentId}" requires skills [${node.skills.join(", ")}] but none are configured. ` +
                 `Set the required environment variables and try again.`);
         }
@@ -241,6 +245,7 @@ export async function execute(workflow, input, options) {
                 signal,
                 timeoutMs,
                 agentAccess: resolveAgentAccess(node.skills, skills),
+                ...(dryRun ? {} : { mcpServers: skillMcpServers }),
                 ...(dryRun ? { readOnly: true } : {}),
                 onProgress: (message) => {
                     safeObserve(observer, { type: "node:progress", node: currentId, message }, logger);
@@ -721,6 +726,13 @@ function dryRunNotice(skippedWrites) {
         `Do not create, modify, post, or send anything. Do the analysis, and where this step would ` +
         `normally write, describe exactly what it would have written instead.`);
 }
+/** Only this node's resolved skills contribute external servers. */
+function resolveSkillMcpServers(skillIds, skills) {
+    return Object.fromEntries(skillIds.flatMap((id) => {
+        const mcp = skills.get(id)?.mcp;
+        return mcp ? [[id, { ...mcp, type: mcp.type ?? (mcp.command ? "stdio" : "http") }]] : [];
+    }));
+}
 function resolveTools(skillIds, skills) {
     return skillIds
         .map((id) => skills.get(id))
@@ -1023,6 +1035,14 @@ async function resolveNext(workflow, current, results, input, claude, observer,
  * Validate a workflow definition before execution.
  */
 function validate(workflow, skills) {
+    for (const [id, def] of Object.entries(workflow.skills ?? {})) {
+        if (!def.instruction?.trim()) {
+            throw new Error(`Inline skill "${id}" must provide a non-empty instruction`);
+        }
+        if (id === "sweny-core" && def.mcp) {
+            throw new Error(`Skill "sweny-core" is reserved for the engine MCP server; use a different skill ID`);
+        }
+    }
     if (!workflow.nodes[workflow.entry]) {
         throw new Error(`Entry node "${workflow.entry}" not found`);
     }
@@ -1036,6 +1056,12 @@ function validate(workflow, skills) {
     for (const [nodeId, node] of Object.entries(workflow.nodes)) {
         if (node.skills.length === 0)
             continue;
+        for (const id of node.skills) {
+            const skill = skills.get(id);
+            if (id === "sweny-core" && skill?.mcp) {
+                throw new Error(`Skill "sweny-core" is reserved for the engine MCP server; use a different skill ID (node "${nodeId}")`);
+            }
+        }
         const available = node.skills.filter((id) => skills.has(id));
         if (available.length === 0) {
             consoleLogger.warn(`Node "${nodeId}" has no available skills (needs one of: ${node.skills.join(", ")})`);

package/dist/schema.d.ts

@@ -3357,11 +3357,7 @@ export declare const workflowJsonSchema: {
             readonly description: "Inline skill definitions scoped to this workflow";
             readonly additionalProperties: {
                 readonly type: "object";
-                readonly anyOf: readonly [{
-                    readonly required: readonly ["instruction"];
-                }, {
-                    readonly required: readonly ["mcp"];
-                }];
+                readonly required: readonly ["instruction"];
                 readonly additionalProperties: false;
                 readonly properties: {
                     readonly name: {
@@ -3372,6 +3368,7 @@ export declare const workflowJsonSchema: {
                     };
                     readonly instruction: {
                         readonly type: "string";
+                        readonly pattern: "\\S";
                         readonly description: "Natural language expertise injected into the node prompt";
                     };
                     readonly mcp: {

package/dist/schema.js

@@ -63,8 +63,8 @@ export const skillDefinitionZ = z
     mcp: mcpServerConfigZ.optional(),
 })
     .strict()
-    .refine((s) => s.instruction || s.mcp, {
-    message: "Inline skill must provide instruction, mcp, or both",
+    .refine((s) => Boolean(s.instruction?.trim()), {
+    message: "Inline skill must provide a non-empty instruction",
 });
 export const skillZ = z
     .object({
@@ -489,12 +489,18 @@ export function validateWorkflow(workflow, knownSkills) {
             });
         }
     }
-    // Inline skill definitions must have instruction or mcp
+    // Inline skills need usage instructions; the engine server name is reserved.
     for (const [skillId, def] of Object.entries(workflow.skills ?? {})) {
-        if (!def.instruction && !def.mcp) {
+        if (!def.instruction?.trim()) {
             errors.push({
                 code: "INVALID_INLINE_SKILL",
-                message: `Inline skill "${skillId}" must provide at least instruction or mcp`,
+                message: `Inline skill "${skillId}" must provide a non-empty instruction`,
+            });
+        }
+        if (skillId === "sweny-core" && def.mcp) {
+            errors.push({
+                code: "INVALID_INLINE_SKILL",
+                message: `Skill "sweny-core" is reserved for the engine MCP server; use a different skill ID`,
             });
         }
     }
@@ -945,14 +951,18 @@ export const workflowJsonSchema = {
             description: "Inline skill definitions scoped to this workflow",
             additionalProperties: {
                 type: "object",
-                // Fix #4: an inline skill must provide instruction, mcp, or both.
-                anyOf: [{ required: ["instruction"] }, { required: ["mcp"] }],
+                // Inline skills need usable instructions, including when they declare MCP.
+                required: ["instruction"],
                 // Round 2: reject unknown keys to match Zod skillDefinitionZ.strict().
                 additionalProperties: false,
                 properties: {
                     name: { type: "string" },
                     description: { type: "string" },
-                    instruction: { type: "string", description: "Natural language expertise injected into the node prompt" },
+                    instruction: {
+                        type: "string",
+                        pattern: "\\S",
+                        description: "Natural language expertise injected into the node prompt",
+                    },
                     mcp: {
                         type: "object",
                         description: "External MCP server definition",

package/dist/types.d.ts

@@ -604,6 +604,8 @@ export interface Claude {
         outputSchema?: JSONSchema;
         /** Called with status messages while Claude is working (tool name, etc.) */
         onProgress?: (message: string) => void;
+        /** MCP servers declared by this node's resolved skills. Explicit client configs win. */
+        mcpServers?: Record<string, McpServerConfig>;
         /** Per-node turn limit. Overrides the client default when set. */
         maxTurns?: number;
         /** Built-in SDK tool names to disallow for this node (e.g. ["Bash"]). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sweny-ai/core",
-  "version": "0.1.125",
+  "version": "0.1.127",
   "type": "module",
   "bin": {
     "sweny": "./dist/cli/main.js"