stageflow 0.25.0 → 0.30.0

package/dist/runtime/runRetentionSweep.d.ts

@@ -0,0 +1,31 @@
+import type { A2aStore } from "../a2a/store.js";
+import { type RetentionWindows } from "../runstore/retention.js";
+import type { RunStore } from "../runstore/port.js";
+export type RetentionSweepReport = {
+    slimmed: string[];
+    purged: string[];
+    bareCachesEvicted: string[];
+};
+export type RunRetentionSweepOptions = {
+    now?: Date;
+    /** When false (default), compute candidates but skip mutating calls. */
+    execute?: boolean;
+    windows?: RetentionWindows;
+    env?: NodeJS.ProcessEnv;
+    artifactMaxBytes?: number;
+    bareCacheTtlMs?: number;
+};
+export declare function getSlimWalkCallCount(): number;
+export declare function resetSlimWalkCallCount(): void;
+/**
+ * Walk attempt + legacy artifact trees and remove SLIM-eligible paths.
+ * Never removes envelope.json, log.jsonl, or under-threshold artifacts.
+ */
+export declare function slimRunWorkspaceArtifacts(workspaceDir: string, maxBytes: number): Promise<void>;
+/**
+ * Two-stage retention: SLIM then PURGE, then bare-cache eviction.
+ * Dry-run (`execute: false`) computes the same candidates and skips mutations.
+ */
+export declare function runRetentionSweep(store: RunStore, a2aStore: A2aStore | undefined, options?: RunRetentionSweepOptions): Promise<RetentionSweepReport>;
+/** Test helper: expose bare-cache path resolution used by the eviction pass. */
+export declare function bareCachePathForRepository(repository: string): string;

package/dist/runtime/runRetentionSweep.js

@@ -0,0 +1,328 @@
+import { readdir, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { bareCachePath } from "../git/cache.js";
+import { globalStageflowHome } from "../project/globalHome.js";
+import { bareCacheTtlFromEnv, isTerminalRunStatus, retentionDecision, retentionWindowsFromEnv, slimArtifactMaxBytesFromEnv, } from "../runstore/retention.js";
+import { reclaimWorkspaceBinding, worktreePathForRun, } from "./repositoryMaterialize.js";
+import { deleteRunEverywhere } from "./runDeletion.js";
+const SLIM_ATTEMPT_FILES = ["pi-session.jsonl", "stream.log"];
+const SLIM_ATTEMPT_DIRS = [".pi-agent"];
+let slimWalkCallCount = 0;
+export function getSlimWalkCallCount() {
+    return slimWalkCallCount;
+}
+export function resetSlimWalkCallCount() {
+    slimWalkCallCount = 0;
+}
+async function pathExists(target) {
+    try {
+        await stat(target);
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+async function rmForce(target) {
+    try {
+        await rm(target, { recursive: true, force: true });
+    }
+    catch (err) {
+        console.error(`runRetentionSweep: rm failed for ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function removeOversizedArtifacts(artifactsDir, maxBytes) {
+    if (!(await pathExists(artifactsDir)))
+        return;
+    async function walk(current) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            let st;
+            try {
+                st = await stat(full);
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+            if (st.size > maxBytes) {
+                await rmForce(full);
+            }
+        }
+    }
+    await walk(artifactsDir);
+}
+async function slimAttemptDir(attemptDir, maxBytes) {
+    for (const name of SLIM_ATTEMPT_DIRS) {
+        await rmForce(path.join(attemptDir, name));
+    }
+    for (const name of SLIM_ATTEMPT_FILES) {
+        await rmForce(path.join(attemptDir, name));
+    }
+    await removeOversizedArtifacts(path.join(attemptDir, "artifacts"), maxBytes);
+}
+/**
+ * Walk attempt + legacy artifact trees and remove SLIM-eligible paths.
+ * Never removes envelope.json, log.jsonl, or under-threshold artifacts.
+ */
+export async function slimRunWorkspaceArtifacts(workspaceDir, maxBytes) {
+    slimWalkCallCount += 1;
+    const stagesRoot = path.join(workspaceDir, "stages");
+    if (!(await pathExists(stagesRoot)))
+        return;
+    let stageEntries;
+    try {
+        stageEntries = await readdir(stagesRoot, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    for (const stageEntry of stageEntries) {
+        if (!stageEntry.isDirectory())
+            continue;
+        const stageDir = path.join(stagesRoot, stageEntry.name);
+        const attemptsRoot = path.join(stageDir, "attempts");
+        if (await pathExists(attemptsRoot)) {
+            let attemptEntries;
+            try {
+                attemptEntries = await readdir(attemptsRoot, { withFileTypes: true });
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    continue;
+                throw err;
+            }
+            for (const attemptEntry of attemptEntries) {
+                if (!attemptEntry.isDirectory())
+                    continue;
+                await slimAttemptDir(path.join(attemptsRoot, attemptEntry.name), maxBytes);
+            }
+        }
+        await removeOversizedArtifacts(path.join(stageDir, "artifacts"), maxBytes);
+    }
+}
+async function slimOneRun(store, meta, now, artifactMaxBytes) {
+    try {
+        await reclaimWorkspaceBinding(meta, { keepRunBranch: true });
+    }
+    catch (err) {
+        console.error(`runRetentionSweep: worktree reclaim failed for ${meta.run_id}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+    const workspaceDir = store.getWorkspaceDir(meta.run_id);
+    try {
+        await slimRunWorkspaceArtifacts(workspaceDir, artifactMaxBytes);
+    }
+    catch (err) {
+        console.error(`runRetentionSweep: artifact slim failed for ${meta.run_id}: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+    await store.setSlimmedAt(meta.run_id, now.toISOString());
+    return true;
+}
+async function listBareCachePaths(reposRoot) {
+    if (!(await pathExists(reposRoot)))
+        return [];
+    const out = [];
+    async function walk(current) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return;
+            throw err;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const full = path.join(current, entry.name);
+            if (entry.name.endsWith(".git")) {
+                out.push(full);
+            }
+            else {
+                await walk(full);
+            }
+        }
+    }
+    await walk(reposRoot);
+    return out;
+}
+function repositoryForCachePath(cachePath) {
+    const reposRoot = path.join(globalStageflowHome(), "repos");
+    const rel = path.relative(reposRoot, cachePath);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return undefined;
+    const parts = rel.split(path.sep);
+    if (parts.length < 3)
+        return undefined;
+    const owner = parts[parts.length - 2];
+    const repoGit = parts[parts.length - 1];
+    if (!repoGit.endsWith(".git"))
+        return undefined;
+    return `${owner}/${repoGit.slice(0, -".git".length)}`;
+}
+function repositoryOf(run) {
+    if ("binding" in run && run.binding?.repository) {
+        return run.binding.repository;
+    }
+    if ("repository" in run && run.repository) {
+        return run.repository;
+    }
+    return undefined;
+}
+function runsForRepository(runs, repository) {
+    return runs.filter((r) => repositoryOf(r) === repository);
+}
+async function hasLiveWorktree(runs) {
+    for (const run of runs) {
+        const checkout = "checkout_root" in run && typeof run.checkout_root === "string"
+            ? run.checkout_root
+            : undefined;
+        const candidates = [
+            ...(checkout ? [checkout] : []),
+            worktreePathForRun(run.run_id),
+        ];
+        for (const candidate of candidates) {
+            if (candidate !== "" && (await pathExists(candidate)))
+                return true;
+        }
+    }
+    return false;
+}
+function allReferencingRunsPastBareTtl(runs, now, ttlMs) {
+    if (runs.length === 0)
+        return true;
+    for (const run of runs) {
+        if (!isTerminalRunStatus(run.status))
+            return false;
+        if (run.finished_at === undefined || run.finished_at === "")
+            return false;
+        const finishedMs = Date.parse(run.finished_at);
+        if (!Number.isFinite(finishedMs))
+            return false;
+        if (now.getTime() - finishedMs < ttlMs)
+            return false;
+    }
+    return true;
+}
+async function evictBareCaches(options) {
+    const reposRoot = path.join(globalStageflowHome(), "repos");
+    const caches = await listBareCachePaths(reposRoot);
+    const evicted = [];
+    for (const cachePath of caches) {
+        const repository = repositoryForCachePath(cachePath);
+        if (repository === undefined)
+            continue;
+        // Prefer store-based live-worktree check (cheaper than `git worktree list`).
+        const referencing = runsForRepository(options.runs, repository);
+        if (await hasLiveWorktree(referencing))
+            continue;
+        if (!allReferencingRunsPastBareTtl(referencing, options.now, options.ttlMs)) {
+            continue;
+        }
+        evicted.push(cachePath);
+        if (options.execute) {
+            await rmForce(cachePath);
+        }
+    }
+    return evicted;
+}
+/**
+ * Two-stage retention: SLIM then PURGE, then bare-cache eviction.
+ * Dry-run (`execute: false`) computes the same candidates and skips mutations.
+ */
+export async function runRetentionSweep(store, a2aStore, options = {}) {
+    const now = options.now ?? new Date();
+    const execute = options.execute === true;
+    const env = options.env ?? process.env;
+    const windows = options.windows ?? retentionWindowsFromEnv(env);
+    const artifactMaxBytes = options.artifactMaxBytes ?? slimArtifactMaxBytesFromEnv(env);
+    const bareCacheTtlMs = options.bareCacheTtlMs ?? bareCacheTtlFromEnv(env);
+    const runs = await store.listRuns();
+    const slimmed = [];
+    const purged = [];
+    const metas = new Map();
+    async function metaFor(runId) {
+        let meta = metas.get(runId);
+        if (meta === undefined) {
+            meta = await store.readRunMeta(runId);
+            metas.set(runId, meta);
+        }
+        return meta;
+    }
+    // Decide from durable meta (status/finished_at/slimmed_at), not listRuns'
+    // derived status — stage rows can make a terminal run look "running".
+    const decisions = [];
+    for (const summary of runs) {
+        const meta = await metaFor(summary.run_id);
+        const decision = retentionDecision(meta, now, windows);
+        if (decision === "slim" || decision === "purge") {
+            decisions.push({ runId: summary.run_id, decision });
+        }
+    }
+    const purgeCandidates = decisions.filter((d) => d.decision === "purge");
+    if (execute && a2aStore === undefined && purgeCandidates.length > 0) {
+        throw new Error("runRetentionSweep: a2aStore is required when execute is true and PURGE candidates exist");
+    }
+    for (const { runId, decision } of decisions) {
+        if (decision !== "slim")
+            continue;
+        const meta = await metaFor(runId);
+        if (execute) {
+            const ok = await slimOneRun(store, meta, now, artifactMaxBytes);
+            if (!ok)
+                continue;
+            slimmed.push(runId);
+            metas.set(runId, {
+                ...meta,
+                slimmed_at: now.toISOString(),
+            });
+        }
+        else {
+            slimmed.push(runId);
+        }
+    }
+    for (const { runId, decision } of decisions) {
+        if (decision !== "purge")
+            continue;
+        purged.push(runId);
+        if (execute) {
+            await deleteRunEverywhere(store, a2aStore, runId);
+        }
+    }
+    // Re-list for bare-cache decisions after PURGE removed rows when execute.
+    const runsForBare = execute ? await store.listRuns() : runs;
+    const bareCachesEvicted = await evictBareCaches({
+        runs: runsForBare,
+        now,
+        ttlMs: bareCacheTtlMs,
+        execute,
+    });
+    return { slimmed, purged, bareCachesEvicted };
+}
+/** Test helper: expose bare-cache path resolution used by the eviction pass. */
+export function bareCachePathForRepository(repository) {
+    return bareCachePath(repository);
+}

package/dist/runtime/runRetryCoordinator.d.ts

@@ -3,6 +3,7 @@ import { type RunDetail, type RunPipelineDagSnapshot, type RunStatus, type RunSt
 import type { PipelineRunResult } from "./pipelineRunner.js";
 import { type SchedulerPreparedPipeline } from "./pipelineScheduler.js";
 import type { StageExecutionMode } from "./stageConcurrency.js";
+import type { StageBrowserSupport } from "../browser/browserHost.js";
 import type { StageProcessLauncher } from "./stageProcessLauncher.js";
 import type { StageHitlController } from "./stageHitl.js";
 import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
@@ -34,6 +35,7 @@ export type RetryStageResult = {
     ok: false;
     reason: string;
     status?: number;
+    code?: string;
 };
 export type RetryTrackingPort = {
     ensureResumeTracked(runId: string): Promise<{
@@ -57,6 +59,7 @@ export type RetryStageRequest = {
     agent: AgentPort;
     cwd: string;
     operatorCatalog?: OperatorCatalog;
+    browser?: StageBrowserSupport;
     maxActiveStagesPerRun: number;
     executionMode: StageExecutionMode;
     stageProcessLauncher?: StageProcessLauncher;
@@ -77,6 +80,7 @@ export declare function assertStageRetryEligible(detail: RunDetail, stageId: str
     ok: false;
     reason: string;
     status: number;
+    code: string;
 };
 export declare function readRetryRootWaitTimeoutMs(): number;
 export declare class RunRetryCoordinator {

package/dist/runtime/runRetryCoordinator.js

@@ -37,6 +37,7 @@ export function assertStageRetryEligible(detail, stageId, opts) {
             ok: false,
             reason: `Stage not found: ${stageId}`,
             status: 404,
+            code: "stage_not_found",
         };
     }
     if (stageSnap.status === "waiting_for_input") {
@@ -44,6 +45,7 @@ export function assertStageRetryEligible(detail, stageId, opts) {
             ok: false,
             reason: `Stage is waiting for input and cannot be retried`,
             status: 409,
+            code: "hitl_not_retriable",
         };
     }
     const runStatus = opts?.persistedStatus ?? detail.status;
@@ -58,6 +60,7 @@ export function assertStageRetryEligible(detail, stageId, opts) {
                 ok: false,
                 reason: `Run is not failed or succeeded (status=${runStatus})`,
                 status: 409,
+                code: "run_not_retryable",
             };
         }
     }
@@ -66,12 +69,18 @@ export function assertStageRetryEligible(detail, stageId, opts) {
             ok: false,
             reason: `Stage is not failed or succeeded (status=${stageSnap.status})`,
             status: 409,
+            code: "stage_not_failed",
         };
     }
     if (stageSnap.status === "succeeded") {
         const blocker = succeededStageRetryBlocker(stageSnap);
         if (blocker !== undefined) {
-            return { ok: false, reason: blocker, status: 409 };
+            return {
+                ok: false,
+                reason: blocker,
+                status: 409,
+                code: "run_not_retryable",
+            };
         }
     }
     return { ok: true };
@@ -256,7 +265,12 @@ export class RunRetryCoordinator {
             dag = meta.pipeline_dag;
         }
         catch {
-            return { ok: false, reason: `Run not found: ${runId}`, status: 404 };
+            return {
+                ok: false,
+                reason: `Run not found: ${runId}`,
+                status: 404,
+                code: "run_not_found",
+            };
         }
         const recoveryActive = this.isActive(runId);
         const eligibility = assertStageRetryEligible(detail, stageId, {
@@ -269,6 +283,7 @@ export class RunRetryCoordinator {
                 ok: false,
                 reason: eligibility.reason,
                 status: eligibility.status,
+                code: eligibility.code,
             };
         }
         if (recoveryActive) {
@@ -277,6 +292,7 @@ export class RunRetryCoordinator {
                     ok: false,
                     reason: `Retry already in progress for run ${runId} stage ${stageId}`,
                     status: 409,
+                    code: "retry_in_progress",
                 };
             }
         }
@@ -285,6 +301,7 @@ export class RunRetryCoordinator {
                 ok: false,
                 reason: `Run ${runId} already has active orchestration`,
                 status: 409,
+                code: "run_not_retryable",
             };
         }
         const priorRunStatus = metaStatus;
@@ -327,6 +344,7 @@ export class RunRetryCoordinator {
                 checkoutRoot: meta.checkout_root,
                 hitl: req.hitl,
                 operatorCatalog: req.operatorCatalog,
+                ...(req.browser !== undefined ? { browser: req.browser } : {}),
             };
             if (this.isActive(runId)) {
                 await this.addRoot(runId, stageId, execution.attempt);

package/dist/runtime/runSkills.d.ts

@@ -0,0 +1,40 @@
+export declare const SKILLS_INVALID_NAME: "skills_invalid_name";
+export declare const SKILLS_INVALID_PATH: "skills_invalid_path";
+export declare const SKILLS_MISSING_SKILL_MD: "skills_missing_skill_md";
+export declare const SKILLS_PAYLOAD_TOO_LARGE: "skills_payload_too_large";
+export type SkillsPayloadErrorCode = typeof SKILLS_INVALID_NAME | typeof SKILLS_INVALID_PATH | typeof SKILLS_MISSING_SKILL_MD | typeof SKILLS_PAYLOAD_TOO_LARGE;
+/** name → relativePath → utf-8 file contents */
+export type SkillsPayload = Record<string, Record<string, string>>;
+export type SkillsValidationOk = {
+    ok: true;
+    skills: SkillsPayload;
+    bytes: number;
+};
+export type SkillsValidationErr = {
+    ok: false;
+    code: SkillsPayloadErrorCode;
+    reason: string;
+    bytes?: number;
+    maxBytes?: number;
+};
+export type SkillsValidationResult = SkillsValidationOk | SkillsValidationErr;
+export declare function runSkillsDir(workspaceDir: string): string;
+export declare function skillPackDir(workspaceDir: string, skillName: string): string;
+export declare function assertValidSkillName(name: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function assertValidSkillRelativePath(relPath: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function measureSkillsPayloadBytes(skills: SkillsPayload): number;
+export declare function validateSkillsPayload(skills: unknown, options?: {
+    pipelineBytes?: number;
+    maxBytes?: number;
+}): SkillsValidationResult;
+export declare function materializeRunSkills(workspaceDir: string, skills: SkillsPayload): Promise<void>;

package/dist/runtime/runSkills.js

@@ -0,0 +1,173 @@
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { START_PAYLOAD_MAX_BYTES } from "./startPayload.js";
+import { isInsideDir } from "../runstore/workspaceLayout.js";
+export const SKILLS_INVALID_NAME = "skills_invalid_name";
+export const SKILLS_INVALID_PATH = "skills_invalid_path";
+export const SKILLS_MISSING_SKILL_MD = "skills_missing_skill_md";
+export const SKILLS_PAYLOAD_TOO_LARGE = "skills_payload_too_large";
+const SKILL_MD = "SKILL.md";
+export function runSkillsDir(workspaceDir) {
+    return path.join(workspaceDir, "skills");
+}
+export function skillPackDir(workspaceDir, skillName) {
+    return path.join(runSkillsDir(workspaceDir), skillName);
+}
+function hasForbiddenNameChars(name) {
+    return (name.includes("/") ||
+        name.includes("\\") ||
+        name.includes("\0") ||
+        name.includes("\u0000"));
+}
+function hasDotDotSegment(rel) {
+    const normalized = rel.replace(/\\/g, "/");
+    return normalized.split("/").some((segment) => segment === "..");
+}
+export function assertValidSkillName(name) {
+    if (typeof name !== "string" || name.length === 0) {
+        return { ok: false, reason: "Skill name must be a non-empty string" };
+    }
+    if (hasForbiddenNameChars(name)) {
+        return {
+            ok: false,
+            reason: `Skill name "${name}" must not contain "/", "\\\\", or NUL`,
+        };
+    }
+    if (path.isAbsolute(name) || hasDotDotSegment(name) || name === "..") {
+        return {
+            ok: false,
+            reason: `Skill name "${name}" must not be absolute or contain ".."`,
+        };
+    }
+    return { ok: true };
+}
+export function assertValidSkillRelativePath(relPath) {
+    if (typeof relPath !== "string" || relPath.length === 0) {
+        return { ok: false, reason: "Skill file path must be a non-empty string" };
+    }
+    if (path.isAbsolute(relPath) || hasDotDotSegment(relPath)) {
+        return {
+            ok: false,
+            reason: `Skill file path "${relPath}" must be relative and must not contain ".."`,
+        };
+    }
+    return { ok: true };
+}
+export function measureSkillsPayloadBytes(skills) {
+    let bytes = 0;
+    for (const files of Object.values(skills)) {
+        for (const content of Object.values(files)) {
+            bytes += Buffer.byteLength(content, "utf8");
+        }
+    }
+    return bytes;
+}
+export function validateSkillsPayload(skills, options) {
+    if (skills === undefined || skills === null) {
+        return { ok: true, skills: {}, bytes: 0 };
+    }
+    if (typeof skills !== "object" || Array.isArray(skills)) {
+        return {
+            ok: false,
+            code: SKILLS_INVALID_NAME,
+            reason: "skills must be a map of name → { relativePath: contents }",
+        };
+    }
+    const maxBytes = options?.maxBytes ?? START_PAYLOAD_MAX_BYTES;
+    const pipelineBytes = options?.pipelineBytes ?? 0;
+    const out = {};
+    for (const [name, files] of Object.entries(skills)) {
+        const nameCheck = assertValidSkillName(name);
+        if (!nameCheck.ok) {
+            return { ok: false, code: SKILLS_INVALID_NAME, reason: nameCheck.reason };
+        }
+        if (files === null || typeof files !== "object" || Array.isArray(files)) {
+            return {
+                ok: false,
+                code: SKILLS_MISSING_SKILL_MD,
+                reason: `Skill "${name}" must map to a files object including ${SKILL_MD}`,
+            };
+        }
+        const fileMap = {};
+        let hasSkillMd = false;
+        for (const [relPath, content] of Object.entries(files)) {
+            const pathCheck = assertValidSkillRelativePath(relPath);
+            if (!pathCheck.ok) {
+                return {
+                    ok: false,
+                    code: SKILLS_INVALID_PATH,
+                    reason: pathCheck.reason,
+                };
+            }
+            if (typeof content !== "string") {
+                return {
+                    ok: false,
+                    code: SKILLS_INVALID_PATH,
+                    reason: `Skill "${name}" file "${relPath}" content must be a UTF-8 string`,
+                };
+            }
+            if (relPath === SKILL_MD || relPath.replace(/\\/g, "/") === SKILL_MD) {
+                hasSkillMd = true;
+            }
+            fileMap[relPath] = content;
+        }
+        if (!hasSkillMd) {
+            return {
+                ok: false,
+                code: SKILLS_MISSING_SKILL_MD,
+                reason: `Skill "${name}" requires ${SKILL_MD}`,
+            };
+        }
+        out[name] = fileMap;
+    }
+    const bytes = measureSkillsPayloadBytes(out);
+    if (pipelineBytes + bytes > maxBytes) {
+        return {
+            ok: false,
+            code: SKILLS_PAYLOAD_TOO_LARGE,
+            reason: `Start payload (pipeline + skills) is ${pipelineBytes + bytes} bytes; max is ${maxBytes}`,
+            bytes: pipelineBytes + bytes,
+            maxBytes,
+        };
+    }
+    return { ok: true, skills: out, bytes };
+}
+export async function materializeRunSkills(workspaceDir, skills) {
+    if (Object.keys(skills).length === 0)
+        return;
+    const skillsRoot = runSkillsDir(workspaceDir);
+    await mkdir(skillsRoot, { recursive: true });
+    const skillsRootReal = await realpath(skillsRoot);
+    for (const [name, files] of Object.entries(skills)) {
+        const nameCheck = assertValidSkillName(name);
+        if (!nameCheck.ok) {
+            throw new Error(nameCheck.reason);
+        }
+        const destDir = skillPackDir(workspaceDir, name);
+        await mkdir(destDir, { recursive: true });
+        const destDirResolved = path.resolve(destDir);
+        if (!isInsideDir(destDirResolved, path.resolve(skillsRoot))) {
+            throw new Error(`Skill "${name}" destination escapes run skills directory`);
+        }
+        const destDirReal = await realpath(destDir);
+        if (!isInsideDir(destDirReal, skillsRootReal)) {
+            throw new Error(`Skill "${name}" destination realpath escapes run skills directory`);
+        }
+        for (const [relPath, content] of Object.entries(files)) {
+            const pathCheck = assertValidSkillRelativePath(relPath);
+            if (!pathCheck.ok) {
+                throw new Error(pathCheck.reason);
+            }
+            const dest = path.resolve(destDir, relPath);
+            if (!isInsideDir(dest, destDirResolved)) {
+                throw new Error(`Skill "${name}" file "${relPath}" escapes skill pack directory`);
+            }
+            await mkdir(path.dirname(dest), { recursive: true });
+            await writeFile(dest, content, "utf8");
+            const fileReal = await realpath(dest);
+            if (!isInsideDir(fileReal, destDirReal)) {
+                throw new Error(`Skill "${name}" file "${relPath}" realpath escapes skill pack directory`);
+            }
+        }
+    }
+}