stageflow 0.23.0 → 0.27.0

package/dist/config/configOrigin.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+export function bindingKindForOrigin(kind) {
+    if (kind === "repository" || kind === "checkout")
+        return kind;
+    return "none";
+}
+/**
+ * Decide whether workspace-sourced config (.mcp.json / skills under checkout)
+ * is permitted. Default: refuse for repository bindings; allow for checkout;
+ * host trust_workspace_config can allowlisted roots.
+ */
+export function decideWorkspaceConfigTrust(options) {
+    if (options.source !== "workspace") {
+        return { allow: true, origin: options.source };
+    }
+    const trusted = (options.trustWorkspaceConfig ?? []).some((root) => root === options.projectRoot);
+    if (trusted) {
+        return { allow: true, origin: "workspace" };
+    }
+    if (options.bindingKind === "checkout") {
+        return { allow: true, origin: "workspace" };
+    }
+    if (options.bindingKind === "repository") {
+        return {
+            allow: false,
+            origin: "workspace",
+            code: "untrusted_config_origin",
+            message: `Workspace config is not trusted for repository binding at ${options.projectRoot}; set trust_workspace_config in HostConfig to allowlist this root`,
+        };
+    }
+    return {
+        allow: false,
+        origin: "workspace",
+        code: "untrusted_config_origin",
+        message: `Workspace config is not trusted at ${options.projectRoot}`,
+    };
+}
+function isUnderRoot(candidate, root) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(candidate);
+    const rel = path.relative(resolvedRoot, resolved);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+export function skillOriginKind(scope, filePath, checkoutRoot) {
+    if (scope === "temporary")
+        return "inline";
+    if (scope === "project" &&
+        checkoutRoot !== undefined &&
+        isUnderRoot(filePath, checkoutRoot)) {
+        return "workspace";
+    }
+    return "catalog";
+}
+export function catalogOrSeededOrigin(projectRoot, seededRoots) {
+    if (projectRoot !== undefined && seededRoots.some((root) => root === projectRoot)) {
+        return "seeded";
+    }
+    return "catalog";
+}

package/dist/config/hostConfig.d.ts

@@ -0,0 +1,55 @@
+export declare class HostConfigError extends Error {
+    readonly code: "config_unknown_key" | "config_invalid";
+    readonly key?: string;
+    constructor(message: string, code: "config_unknown_key" | "config_invalid", key?: string);
+}
+/** Env keys that are known STAGEFLOW_* (or dynamic families) so unknown-key check accepts them. */
+export declare const KNOWN_STAGEFLOW_ENV_KEYS: Set<string>;
+/** Per-caller concurrent-active quota from host `callers:` config. */
+export type CallerQuotaConfig = {
+    maxConcurrent: number;
+};
+export type HostConfig = {
+    maxConcurrentRuns: number;
+    maxConcurrentRunsPerProject: number | undefined;
+    maxQueued: number;
+    requireProviders: string[];
+    trustWorkspaceConfig: string[];
+    allowUnknownConfig: boolean;
+    controlToken: string | undefined;
+    readToken: string | undefined;
+    /** caller_id → quota; empty when unset. */
+    callers: Record<string, CallerQuotaConfig>;
+    /** Absolute path of config.yaml when loaded; undefined if absent. */
+    configFilePath: string | undefined;
+    warnings: string[];
+    /** True when maxConcurrentRuns came from override, env, or file (not bare default). */
+    maxConcurrentRunsExplicit: boolean;
+};
+export type HostConfigOverrides = {
+    maxConcurrentRuns?: number;
+};
+export type HostConfigSecretsEcho = {
+    controlToken: "set" | "unset";
+    readToken: "set" | "unset";
+};
+export type HostConfigPublicEcho = {
+    maxConcurrentRuns: number;
+    maxConcurrentRunsPerProject: number | undefined;
+    maxQueued: number;
+    requireProviders: string[];
+    trustWorkspaceConfig: string[];
+    allowUnknownConfig: boolean;
+    callers: Record<string, CallerQuotaConfig>;
+    secrets: HostConfigSecretsEcho;
+};
+/**
+ * Assemble HostConfig once at boot. Precedence: overrides (CLI flags) > env > file > default.
+ */
+export declare function loadHostConfig(options?: {
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    overrides?: HostConfigOverrides;
+    configFilePath?: string | null;
+}): HostConfig;
+export declare function redactHostConfig(config: HostConfig): HostConfigPublicEcho;

package/dist/config/hostConfig.js

@@ -0,0 +1,333 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { readSecretFromEnvOrFile } from "./secretFromEnvOrFile.js";
+export class HostConfigError extends Error {
+    code;
+    key;
+    constructor(message, code, key) {
+        super(message);
+        this.name = "HostConfigError";
+        this.code = code;
+        this.key = key;
+    }
+}
+/** Env keys that are known STAGEFLOW_* (or dynamic families) so unknown-key check accepts them. */
+export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
+    "STAGEFLOW_HOME",
+    "STAGEFLOW_BIND",
+    "STAGEFLOW_ALLOWED_HOSTS",
+    "STAGEFLOW_CONTROL_TOKEN",
+    "STAGEFLOW_CONTROL_TOKEN_FILE",
+    "STAGEFLOW_READ_TOKEN",
+    "STAGEFLOW_READ_TOKEN_FILE",
+    "STAGEFLOW_ALLOW_UNKNOWN_CONFIG",
+    "STAGEFLOW_MAX_CONCURRENT_RUNS",
+    "STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT",
+    "STAGEFLOW_MAX_QUEUED",
+    "STAGEFLOW_REQUIRE_PROVIDERS",
+    "STAGEFLOW_A2A_CONFIG",
+    "STAGEFLOW_ACTIVITY_TEXT_LIMIT",
+    "STAGEFLOW_ACTIVITY_VERBOSE",
+    "STAGEFLOW_CURSOR_EXTENSION",
+    "STAGEFLOW_NO_OPEN",
+    "STAGEFLOW_OPERATOR_CWD",
+    "STAGEFLOW_OPERATOR_AGENT_DIR",
+    "STAGEFLOW_LEGACY_YAML",
+    "STAGEFLOW_LOG_FORMAT",
+    "STAGEFLOW_LOG_LEVEL",
+    "STAGEFLOW_LOG_MAX_LINE_BYTES",
+    "STAGEFLOW_MCP_STATELESS",
+    "STAGEFLOW_DISK_WARN_BYTES",
+    "STAGEFLOW_MIN_FREE_DISK_BYTES",
+    "STAGEFLOW_BARE_CACHE_TTL_MS",
+    "STAGEFLOW_SLIM_ARTIFACT_MAX_BYTES",
+    "STAGEFLOW_SQLITE_BUSY_TIMEOUT_MS",
+    "STAGEFLOW_RUN_BRANCH_TEMPLATE",
+    "STAGEFLOW_AUTO_RESUME_INTERRUPTED",
+    "STAGEFLOW_MAX_AUTO_RESUMES",
+    "STAGEFLOW_RETRY_ROOT_WAIT_TIMEOUT_MS",
+    "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN",
+    "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES",
+    "STAGEFLOW_STAGE_EXECUTION",
+    "STAGEFLOW_STAGE_ENV_ALLOW",
+    "STAGEFLOW_STAGE_ENV_PASSTHROUGH",
+    "STAGEFLOW_GC_INTERVAL_MS",
+    "STAGEFLOW_MAX_CONNECTIONS",
+    "STAGEFLOW_REQUEST_TIMEOUT_MS",
+    "STAGEFLOW_AUTOSTART_TIMEOUT_MS",
+    "STAGEFLOW_NO_AUTOSTART",
+    "STAGEFLOW_SERVICE_PORT",
+    "STAGEFLOW_SHUTDOWN_GRACE_MS",
+    "STAGEFLOW_TOOLCHAIN_MANIFEST",
+    "STAGEFLOW_SECRET_REGISTRY",
+    "STAGEFLOW_BUILD_SHA",
+]);
+const KNOWN_ENV_PREFIXES = [
+    "STAGEFLOW_PROVIDER_",
+    "STAGEFLOW_SLIM_",
+    "STAGEFLOW_PURGE_",
+    "STAGEFLOW_CONTROL_TOKEN_",
+];
+const FILE_KEY_TO_FIELD = {
+    max_concurrent_runs: "maxConcurrentRuns",
+    max_concurrent_runs_per_project: "maxConcurrentRunsPerProject",
+    max_queued: "maxQueued",
+    require_providers: "requireProviders",
+    trust_workspace_config: "trustWorkspaceConfig",
+    allow_unknown_config: "allowUnknownConfig",
+    callers: "callers",
+};
+const DEFAULT_MAX_CONCURRENT = 3;
+const DEFAULT_MAX_QUEUED = 32;
+function isKnownStageflowEnvKey(key) {
+    if (KNOWN_STAGEFLOW_ENV_KEYS.has(key))
+        return true;
+    return KNOWN_ENV_PREFIXES.some((prefix) => key.startsWith(prefix));
+}
+function parsePositiveInt(raw, key, opts) {
+    const n = Number.parseInt(raw, 10);
+    const min = opts?.allowZero ? 0 : 1;
+    if (!Number.isFinite(n) || n < min || String(n) !== raw.trim()) {
+        throw new HostConfigError(`Invalid value for ${key}: ${JSON.stringify(raw)}`, "config_invalid", key);
+    }
+    return n;
+}
+function parseStringList(raw) {
+    return raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function parseBool(raw, key) {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "1" || normalized === "true")
+        return true;
+    if (normalized === "0" || normalized === "false" || normalized === "") {
+        return false;
+    }
+    throw new HostConfigError(`Invalid boolean for ${key}: ${JSON.stringify(raw)}`, "config_invalid", key);
+}
+function assertUnknownEnvKeys(env, allowUnknown, warnings) {
+    for (const key of Object.keys(env)) {
+        if (!key.startsWith("STAGEFLOW_"))
+            continue;
+        if (isKnownStageflowEnvKey(key))
+            continue;
+        const message = `Unknown environment variable ${key}`;
+        if (allowUnknown) {
+            warnings.push(message);
+            continue;
+        }
+        throw new HostConfigError(message, "config_unknown_key", key);
+    }
+}
+function loadFileLayers(filePath) {
+    const warnings = [];
+    if (filePath === undefined || !existsSync(filePath)) {
+        return { values: {}, warnings };
+    }
+    let raw;
+    try {
+        raw = parseYaml(readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new HostConfigError(`Invalid config file ${filePath}: ${detail}`, "config_invalid");
+    }
+    if (raw === null || raw === undefined) {
+        return { values: {}, warnings };
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        throw new HostConfigError(`config.yaml must be a mapping`, "config_invalid");
+    }
+    const values = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const field = FILE_KEY_TO_FIELD[key];
+        if (field === undefined) {
+            throw new HostConfigError(`Unknown config key "${key}" in ${filePath}`, "config_unknown_key", key);
+        }
+        values[field] = value;
+    }
+    return { values, warnings };
+}
+function coerceFileNumber(value, key) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return parsePositiveInt(value, key, {
+            allowZero: key.includes("queued") || key.includes("per_project"),
+        });
+    }
+    throw new HostConfigError(`Invalid value for ${key}`, "config_invalid", key);
+}
+function coerceFileStringList(value, key) {
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return value.map((v) => v.trim()).filter((v) => v.length > 0);
+    }
+    if (typeof value === "string")
+        return parseStringList(value);
+    throw new HostConfigError(`Invalid value for ${key}; expected string list`, "config_invalid", key);
+}
+function coerceFileBool(value, key) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string")
+        return parseBool(value, key);
+    throw new HostConfigError(`Invalid boolean for ${key}`, "config_invalid", key);
+}
+function coerceCallers(value, key) {
+    if (value === null || value === undefined)
+        return {};
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new HostConfigError(`Invalid value for ${key}; expected mapping of caller_id → { max_concurrent }`, "config_invalid", key);
+    }
+    const out = {};
+    for (const [rawId, rawEntry] of Object.entries(value)) {
+        const callerId = rawId.trim().toLowerCase();
+        if (callerId.length === 0) {
+            throw new HostConfigError(`Invalid empty caller id in ${key}`, "config_invalid", key);
+        }
+        if (rawEntry === null ||
+            typeof rawEntry !== "object" ||
+            Array.isArray(rawEntry)) {
+            throw new HostConfigError(`Invalid value for ${key}.${rawId}; expected { max_concurrent }`, "config_invalid", key);
+        }
+        const entry = rawEntry;
+        if (entry.max_concurrent === undefined) {
+            throw new HostConfigError(`Missing max_concurrent for ${key}.${rawId}`, "config_invalid", key);
+        }
+        const n = coerceFileNumber(entry.max_concurrent, `${key}.${rawId}.max_concurrent`);
+        if (!Number.isInteger(n) || n < 1) {
+            throw new HostConfigError(`Invalid max_concurrent for ${key}.${rawId}`, "config_invalid", key);
+        }
+        for (const sub of Object.keys(entry)) {
+            if (sub !== "max_concurrent") {
+                throw new HostConfigError(`Unknown key "${sub}" under ${key}.${rawId}`, "config_unknown_key", sub);
+            }
+        }
+        out[callerId] = { maxConcurrent: n };
+    }
+    return out;
+}
+/**
+ * Assemble HostConfig once at boot. Precedence: overrides (CLI flags) > env > file > default.
+ */
+export function loadHostConfig(options) {
+    const env = options?.env ?? process.env;
+    const warnings = [];
+    const homeDir = options?.homeDir ?? globalStageflowHome();
+    const configFilePath = options?.configFilePath === null
+        ? undefined
+        : (options?.configFilePath ?? path.join(homeDir, "config.yaml"));
+    const allowUnknownFromEnv = env.STAGEFLOW_ALLOW_UNKNOWN_CONFIG;
+    const allowUnknownConfig = allowUnknownFromEnv !== undefined && allowUnknownFromEnv.length > 0
+        ? parseBool(allowUnknownFromEnv, "STAGEFLOW_ALLOW_UNKNOWN_CONFIG")
+        : false;
+    if (allowUnknownConfig) {
+        warnings.push("STAGEFLOW_ALLOW_UNKNOWN_CONFIG=1: unknown STAGEFLOW_* keys will warn instead of failing boot");
+    }
+    assertUnknownEnvKeys(env, allowUnknownConfig, warnings);
+    const file = loadFileLayers(configFilePath !== undefined && existsSync(configFilePath)
+        ? configFilePath
+        : undefined);
+    warnings.push(...file.warnings);
+    let maxConcurrentRuns = DEFAULT_MAX_CONCURRENT;
+    let maxConcurrentRunsExplicit = false;
+    if (file.values.maxConcurrentRuns !== undefined) {
+        const n = coerceFileNumber(file.values.maxConcurrentRuns, "max_concurrent_runs");
+        if (!Number.isInteger(n) || n < 1) {
+            throw new HostConfigError(`Invalid value for max_concurrent_runs`, "config_invalid", "max_concurrent_runs");
+        }
+        maxConcurrentRuns = n;
+        maxConcurrentRunsExplicit = true;
+    }
+    if (env.STAGEFLOW_MAX_CONCURRENT_RUNS !== undefined) {
+        maxConcurrentRuns = parsePositiveInt(env.STAGEFLOW_MAX_CONCURRENT_RUNS, "STAGEFLOW_MAX_CONCURRENT_RUNS");
+        maxConcurrentRunsExplicit = true;
+    }
+    if (options?.overrides?.maxConcurrentRuns !== undefined) {
+        maxConcurrentRuns = options.overrides.maxConcurrentRuns;
+        maxConcurrentRunsExplicit = true;
+    }
+    let maxConcurrentRunsPerProject;
+    if (file.values.maxConcurrentRunsPerProject !== undefined) {
+        const n = coerceFileNumber(file.values.maxConcurrentRunsPerProject, "max_concurrent_runs_per_project");
+        if (!Number.isInteger(n) || n < 1) {
+            throw new HostConfigError(`Invalid value for max_concurrent_runs_per_project`, "config_invalid", "max_concurrent_runs_per_project");
+        }
+        maxConcurrentRunsPerProject = n;
+    }
+    if (env.STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT !== undefined) {
+        maxConcurrentRunsPerProject = parsePositiveInt(env.STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT, "STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT");
+    }
+    let maxQueued = DEFAULT_MAX_QUEUED;
+    if (file.values.maxQueued !== undefined) {
+        const n = coerceFileNumber(file.values.maxQueued, "max_queued");
+        if (!Number.isInteger(n) || n < 0) {
+            throw new HostConfigError(`Invalid value for max_queued`, "config_invalid", "max_queued");
+        }
+        maxQueued = n;
+    }
+    if (env.STAGEFLOW_MAX_QUEUED !== undefined) {
+        maxQueued = parsePositiveInt(env.STAGEFLOW_MAX_QUEUED, "STAGEFLOW_MAX_QUEUED", {
+            allowZero: true,
+        });
+    }
+    let requireProviders = [];
+    if (file.values.requireProviders !== undefined) {
+        requireProviders = coerceFileStringList(file.values.requireProviders, "require_providers");
+    }
+    if (env.STAGEFLOW_REQUIRE_PROVIDERS !== undefined) {
+        requireProviders = parseStringList(env.STAGEFLOW_REQUIRE_PROVIDERS);
+    }
+    let trustWorkspaceConfig = [];
+    if (file.values.trustWorkspaceConfig !== undefined) {
+        trustWorkspaceConfig = coerceFileStringList(file.values.trustWorkspaceConfig, "trust_workspace_config");
+    }
+    let allowUnknownFromFile = allowUnknownConfig;
+    if (file.values.allowUnknownConfig !== undefined) {
+        allowUnknownFromFile = coerceFileBool(file.values.allowUnknownConfig, "allow_unknown_config");
+    }
+    // Env already applied above for the unknown-key scan; file cannot enable after the fact.
+    void allowUnknownFromFile;
+    const controlToken = readSecretFromEnvOrFile(env, "STAGEFLOW_CONTROL_TOKEN");
+    const readToken = readSecretFromEnvOrFile(env, "STAGEFLOW_READ_TOKEN");
+    let callers = {};
+    if (file.values.callers !== undefined) {
+        callers = coerceCallers(file.values.callers, "callers");
+    }
+    return {
+        maxConcurrentRuns,
+        maxConcurrentRunsPerProject,
+        maxQueued,
+        requireProviders,
+        trustWorkspaceConfig,
+        allowUnknownConfig,
+        controlToken,
+        readToken,
+        callers,
+        configFilePath: configFilePath !== undefined && existsSync(configFilePath)
+            ? configFilePath
+            : undefined,
+        warnings,
+        maxConcurrentRunsExplicit,
+    };
+}
+export function redactHostConfig(config) {
+    return {
+        maxConcurrentRuns: config.maxConcurrentRuns,
+        maxConcurrentRunsPerProject: config.maxConcurrentRunsPerProject,
+        maxQueued: config.maxQueued,
+        requireProviders: [...config.requireProviders],
+        trustWorkspaceConfig: [...config.trustWorkspaceConfig],
+        allowUnknownConfig: config.allowUnknownConfig,
+        callers: { ...config.callers },
+        secrets: {
+            controlToken: config.controlToken ? "set" : "unset",
+            readToken: config.readToken ? "set" : "unset",
+        },
+    };
+}

package/dist/config/listSkills.d.ts

@@ -1,4 +1,6 @@
 export type SkillScope = "user" | "project" | "temporary";
+/** Skill resolution origin — separate from ConfigOriginKind. */
+export type SkillOrigin = "run" | "checkout" | "host";
 export type SkillListing = {
     name: string;
     description: string;
@@ -7,6 +9,7 @@ export type SkillListing = {
     scope: SkillScope;
     source: string;
     disableModelInvocation: boolean;
+    origin?: SkillOrigin;
 };
 export type SkillDiagnostic = {
     message: string;
@@ -19,11 +22,34 @@ export type SkillCatalog = {
 export type ListSkillsOptions = {
     cwd: string;
     agentDir: string;
+    /** Materialized run skills root: `$STAGEFLOW_HOME/runs/<runId>/skills`. */
+    runSkillsDir?: string;
+    /** Checkout / worktree root whose `.pi/skills` is the checkout tier. */
+    checkoutRoot?: string;
 };
 export type ResolvedSkill = {
     name: string;
     filePath: string;
     baseDir: string;
+    scope: SkillScope;
+    source: string;
+    origin: SkillOrigin;
+};
+export type SkillOriginListing = {
+    name: string;
+    description: string;
+    origin: SkillOrigin;
 };
+/**
+ * Resolve a skill by name. Search order: run skills → checkout `.pi/skills` → host agentDir.
+ */
 export declare function resolveSkillByName(name: string, options: ListSkillsOptions): Promise<ResolvedSkill | undefined>;
 export declare function listSkills(options: ListSkillsOptions): Promise<SkillCatalog>;
+/**
+ * List skills with SkillOrigin. When runSkillsDir is set, run-tier skills win on name.
+ * Precedence for the merged view: run → checkout → host.
+ */
+export declare function listSkillsWithOrigin(options: ListSkillsOptions): Promise<{
+    skills: SkillOriginListing[];
+    diagnostics: SkillDiagnostic[];
+}>;