stageflow 0.40.0 → 0.42.0

package/dist/config/datasetFromSessions.js

@@ -0,0 +1,105 @@
+import { isAgentError } from "../agents/errors.js";
+export class SessionCaseError extends Error {
+}
+const PREVIEW_CHARS = 160;
+const SCRIPT_MAX_MESSAGES = 40;
+const SCRIPT_MAX_CHARS = 4000;
+const SESSION_TAG = "from-session";
+function userMessages(detail) {
+    return detail.messages
+        .filter((m) => m.role === "user" && m.text.trim() !== "")
+        .map((m) => m.text.slice(0, SCRIPT_MAX_CHARS))
+        .slice(0, SCRIPT_MAX_MESSAGES);
+}
+function toolNames(detail) {
+    const names = new Set();
+    for (const span of detail.spans) {
+        if (span.kind !== "tool")
+            continue;
+        const name = span.attributes["gen_ai.tool.name"];
+        if (typeof name === "string" && name !== "")
+            names.add(name);
+    }
+    return [...names];
+}
+function shortId(sessionId) {
+    return sessionId.replace(/^ses_/, "").slice(0, 8);
+}
+function isFinishedStatus(status) {
+    return status === "open" || status === "closed";
+}
+function isFinishedUserSession(detail, agentId) {
+    const { session } = detail;
+    return session.agentId === agentId && session.source !== "eval" && isFinishedStatus(session.status);
+}
+/** Finished (idle or closed), non-eval sessions of the agent that have at least one user message, newest first. */
+export async function listSessionCandidates(input) {
+    const { sessions, projectRoot, agentId, limit } = input;
+    const items = [];
+    let cursor;
+    do {
+        let page;
+        try {
+            page = await sessions.listSessions(projectRoot, agentId, {
+                limit: Math.max(limit, 25),
+                ...(cursor !== undefined ? { cursor } : {}),
+            });
+        }
+        catch (err) {
+            if (isAgentError(err))
+                throw new SessionCaseError(`Agent "${agentId}" was not found`);
+            throw err;
+        }
+        for (const row of page.sessions) {
+            if (row.source === "eval" || !isFinishedStatus(row.status))
+                continue;
+            if (row.lastTurnStatus === "running" || row.lastTurnStatus === "waiting")
+                continue;
+            const detail = await sessions.getSession(projectRoot, row.id);
+            const messages = userMessages(detail);
+            if (messages.length === 0)
+                continue;
+            items.push({
+                session_id: row.id,
+                updated_at: row.updatedAt,
+                preview: messages[0].replace(/\s+/g, " ").slice(0, PREVIEW_CHARS),
+                turns: messages.length,
+                tools: toolNames(detail),
+            });
+            if (items.length >= limit)
+                return items;
+        }
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor !== undefined);
+    return items;
+}
+/** One `script` scenario per session: its user messages, plus the tools it called as the expected tools. */
+export async function casesFromSessions(input) {
+    const { sessions, projectRoot, agentId } = input;
+    const cases = [];
+    for (const sessionId of input.sessionIds) {
+        let detail;
+        try {
+            detail = await sessions.getSession(projectRoot, sessionId);
+        }
+        catch (err) {
+            if (isAgentError(err))
+                throw new SessionCaseError(`Session "${sessionId}" was not found`);
+            throw err;
+        }
+        if (!isFinishedUserSession(detail, agentId)) {
+            throw new SessionCaseError(`Session "${sessionId}" is not a finished session of agent "${agentId}"`);
+        }
+        const script = userMessages(detail);
+        if (script.length === 0)
+            throw new SessionCaseError(`Session "${sessionId}" has no user messages`);
+        cases.push({
+            title: detail.session.title ?? `Session ${shortId(sessionId)}`,
+            input: { mode: "script", script, opening: script[0] },
+            expected: { tools: toolNames(detail) },
+            tags: [SESSION_TAG],
+            metadata: { source_session: sessionId },
+        });
+    }
+    return cases;
+}

package/dist/config/datasetHash.d.ts

@@ -0,0 +1 @@
+export declare function datasetContentHash(cases: readonly unknown[]): string;

package/dist/config/datasetHash.js

@@ -0,0 +1,4 @@
+import { canonicalJson, sha256Hex } from "../evals/canonical.js";
+export function datasetContentHash(cases) {
+    return sha256Hex(cases.map((c) => canonicalJson(c)).join("\n"));
+}

package/dist/config/datasetImport.d.ts

@@ -0,0 +1,21 @@
+import type { DatasetCase } from "./datasetTypes.js";
+export type UploadMappingEntry = {
+    column: string;
+    split?: string;
+} | null;
+export type UploadMapping = Record<string, UploadMappingEntry>;
+export type UploadPreviewRow = {
+    index: number;
+    case: DatasetCase;
+    status: "ready" | "skipped";
+    reason?: string;
+};
+export declare function nextIdNumber(existingIds: Iterable<string>): number;
+export declare function formatId(n: number): string;
+export type UploadMappingOptions = {
+    /** Also map the top-level `title` and `tags` targets (agent datasets). */
+    caseMeta?: boolean;
+    /** Extra check on the built case; a returned text skips the row with that reason. */
+    check?: (draft: DatasetCase) => string | undefined;
+};
+export declare function applyUploadMapping(rows: ReadonlyArray<Record<string, string>>, mapping: UploadMapping, inputSchema: unknown, existingIds: Iterable<string>, options?: UploadMappingOptions): UploadPreviewRow[];

package/dist/config/datasetImport.js

@@ -0,0 +1,120 @@
+import { payloadInstanceMismatch } from "../envelope/payloadSchema.js";
+const REASON_MAX = 160;
+const ID_NUMBER_RE = /^c(\d+)$/;
+function trimReason(message) {
+    const flat = message.replace(/\s+/g, " ").trim();
+    return flat.length > REASON_MAX ? flat.slice(0, REASON_MAX) : flat;
+}
+export function nextIdNumber(existingIds) {
+    let max = 0;
+    for (const id of existingIds) {
+        const m = ID_NUMBER_RE.exec(id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return max + 1;
+}
+export function formatId(n) {
+    return `c${String(n).padStart(3, "0")}`;
+}
+function schemaPropertyType(inputSchema, name) {
+    if (inputSchema === null || typeof inputSchema !== "object")
+        return undefined;
+    const props = inputSchema.properties;
+    if (props === null || typeof props !== "object")
+        return undefined;
+    const prop = props[name];
+    if (prop === null || typeof prop !== "object")
+        return undefined;
+    const type = prop.type;
+    return typeof type === "string" ? type : undefined;
+}
+function parseCell(cell, schemaType, split, name) {
+    if (split !== undefined) {
+        return {
+            value: cell
+                .split(split)
+                .map((part) => part.trim())
+                .filter((part) => part !== ""),
+        };
+    }
+    if (schemaType === "number" || schemaType === "integer") {
+        const trimmed = cell.trim();
+        const n = trimmed === "" ? Number.NaN : Number(trimmed);
+        if (!Number.isFinite(n) || (schemaType === "integer" && !Number.isInteger(n))) {
+            return { error: `${name} is not ${schemaType === "integer" ? "an integer" : "a number"}` };
+        }
+        return { value: n };
+    }
+    if (schemaType === "boolean") {
+        const lowered = cell.trim().toLowerCase();
+        if (lowered === "true")
+            return { value: true };
+        if (lowered === "false")
+            return { value: false };
+        return { error: `${name} is not a boolean` };
+    }
+    return { value: cell };
+}
+export function applyUploadMapping(rows, mapping, inputSchema, existingIds, options = {}) {
+    let nextId = nextIdNumber(existingIds);
+    const entries = Object.entries(mapping).filter((e) => e[1] !== null);
+    return rows.map((row, index) => {
+        const input = {};
+        const expected = {};
+        let parseError;
+        let title;
+        let tags;
+        for (const [target, entry] of entries) {
+            if (options.caseMeta === true && (target === "title" || target === "tags")) {
+                const raw = row[entry.column];
+                if (raw === undefined || raw.trim() === "")
+                    continue;
+                if (target === "title")
+                    title = raw.trim();
+                else
+                    tags = (entry.split !== undefined ? raw.split(entry.split) : raw.split(",")).map((t) => t.trim()).filter((t) => t !== "");
+                continue;
+            }
+            const dot = target.indexOf(".");
+            const base = dot === -1 ? target : target.slice(0, dot);
+            const name = dot === -1 ? "" : target.slice(dot + 1);
+            if ((base !== "input" && base !== "expected") || name === "")
+                continue;
+            const cell = row[entry.column];
+            if (cell === undefined || cell === "")
+                continue;
+            const schemaType = base === "input" ? schemaPropertyType(inputSchema, name) : undefined;
+            const parsed = parseCell(cell, schemaType, entry.split, name);
+            if ("error" in parsed) {
+                parseError ??= parsed.error;
+                continue;
+            }
+            (base === "input" ? input : expected)[name] = parsed.value;
+        }
+        const draft = { id: "", input };
+        if (Object.keys(expected).length > 0)
+            draft.expected = expected;
+        if (title !== undefined)
+            draft.title = title;
+        if (tags !== undefined && tags.length > 0)
+            draft.tags = tags;
+        let reason = parseError;
+        if (reason === undefined && inputSchema !== undefined) {
+            try {
+                reason = payloadInstanceMismatch(input, inputSchema);
+            }
+            catch (err) {
+                reason = err instanceof Error ? err.message : String(err);
+            }
+        }
+        if (reason === undefined && options.check)
+            reason = options.check(draft);
+        if (reason !== undefined) {
+            return { index, case: draft, status: "skipped", reason: trimReason(reason) };
+        }
+        draft.id = formatId(nextId);
+        nextId += 1;
+        return { index, case: draft, status: "ready" };
+    });
+}

package/dist/config/datasetStageCheck.d.ts

@@ -0,0 +1,9 @@
+export type DatasetStageCheckResult = {
+    caseId: string;
+    valid: boolean;
+    message?: string;
+};
+export declare function checkDatasetAgainstStage(cases: ReadonlyArray<{
+    id: string;
+    input: Record<string, unknown>;
+}>, inputSchema: unknown): DatasetStageCheckResult[];

package/dist/config/datasetStageCheck.js

@@ -0,0 +1,17 @@
+import { payloadInstanceMismatch } from "../envelope/payloadSchema.js";
+export function checkDatasetAgainstStage(cases, inputSchema) {
+    return cases.map((c) => {
+        if (inputSchema === undefined)
+            return { caseId: c.id, valid: true };
+        let message;
+        try {
+            message = payloadInstanceMismatch(c.input, inputSchema);
+        }
+        catch (err) {
+            message = err instanceof Error ? err.message : String(err);
+        }
+        return message === undefined
+            ? { caseId: c.id, valid: true }
+            : { caseId: c.id, valid: false, message };
+    });
+}

package/dist/config/datasetTypes.d.ts

@@ -0,0 +1,27 @@
+import type { ValidationFinding } from "./validateCatalog.js";
+export type DatasetFormat = "jsonl" | "json" | "csv";
+export type DatasetCase = {
+    id: string;
+    input: Record<string, unknown>;
+    title?: string;
+    expected?: unknown;
+    tags?: string[];
+    goal?: string;
+    metadata?: Record<string, unknown>;
+};
+export type DatasetLimits = {
+    maxCases: number;
+    maxCaseBytes: number;
+    maxFileBytes: number;
+};
+export type ParseDatasetResult = {
+    cases: DatasetCase[];
+    findings: ValidationFinding[];
+    contentHash: string;
+};
+export type DatasetLoadResult = ParseDatasetResult & {
+    path: string;
+    relPath: string;
+    format: DatasetFormat | undefined;
+    fileBytes: number;
+};

package/dist/config/datasetTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/config/ensureCatalogScanRoot.d.ts

@@ -14,4 +14,5 @@ export declare function catalogScanRootForDirectory(directory: string): string;
  * Make sure `stageflow.yaml` scans `directory` for both pipelines and tasks.
  * Returns true when the manifest changed. Missing or unreadable manifests are left alone.
  */
-export declare function ensureCatalogScanRoot(projectRoot: string, directory: string): Promise<boolean>;
+export type CatalogScanKey = "pipelines" | "tasks" | "evals" | "datasets";
+export declare function ensureCatalogScanRoot(projectRoot: string, directory: string, keys?: readonly CatalogScanKey[]): Promise<boolean>;

package/dist/config/ensureCatalogScanRoot.js

@@ -38,11 +38,7 @@ function isCovered(entries, root) {
         return root === normalized || root.startsWith(`${normalized}/`);
     });
 }
-/**
- * Make sure `stageflow.yaml` scans `directory` for both pipelines and tasks.
- * Returns true when the manifest changed. Missing or unreadable manifests are left alone.
- */
-export async function ensureCatalogScanRoot(projectRoot, directory) {
+export async function ensureCatalogScanRoot(projectRoot, directory, keys = ["pipelines", "tasks"]) {
     const root = catalogScanRootForDirectory(directory);
     if (!root || root.split("/").includes(".."))
         return false;
@@ -56,7 +52,7 @@ export async function ensureCatalogScanRoot(projectRoot, directory) {
     }
     const doc = parseDocument(text);
     let changed = false;
-    for (const key of ["pipelines", "tasks"]) {
+    for (const key of keys) {
         const seq = doc.getIn(["catalog", key]);
         if (!isSeq(seq))
             continue;

package/dist/config/evalCatalog.d.ts

@@ -0,0 +1,22 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import { type LoadedEval } from "./loadEval.js";
+import type { LoadOutcome } from "./loadOutcome.js";
+import type { ValidationFinding } from "./validateCatalog.js";
+import { type DatasetReport } from "./validateEval.js";
+export type CatalogFileRef = {
+    absPath: string;
+    relPath: string;
+};
+export declare function listEvalFiles(manifest: LoadedManifest): Promise<CatalogFileRef[]>;
+export declare function listDatasetFiles(manifest: LoadedManifest): Promise<CatalogFileRef[]>;
+export type EvalCatalogEntry = {
+    absPath: string;
+    relPath: string;
+    outcome: LoadOutcome<LoadedEval>;
+    findings: ValidationFinding[];
+};
+export type LoadEvalCatalogOptions = {
+    isKnownModel?: (id: string) => Promise<boolean>;
+    datasetReportFor?: (loaded: LoadedEval) => Promise<DatasetReport | undefined>;
+};
+export declare function loadEvalCatalog(manifest: LoadedManifest, options?: LoadEvalCatalogOptions): Promise<EvalCatalogEntry[]>;

package/dist/config/evalCatalog.js

@@ -0,0 +1,67 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { getModelCatalog } from "../models/catalog.js";
+import { loadDatasetFile } from "./loadDataset.js";
+import { loadEvalOutcome, resolveEvalPaths } from "./loadEval.js";
+import { scanCatalogPaths } from "./scanCatalogPaths.js";
+import { evalFindingsFromIssues, validateEval, } from "./validateEval.js";
+async function listFiles(manifest, kind) {
+    const absPaths = await scanCatalogPaths(manifest, kind);
+    return absPaths.map((absPath) => ({
+        absPath,
+        relPath: path.relative(manifest.projectRoot, absPath).split(path.sep).join("/"),
+    }));
+}
+export function listEvalFiles(manifest) {
+    return listFiles(manifest, "eval");
+}
+export function listDatasetFiles(manifest) {
+    return listFiles(manifest, "dataset");
+}
+export async function loadEvalCatalog(manifest, options = {}) {
+    const refs = await listEvalFiles(manifest);
+    const { projectRoot } = manifest;
+    const isKnownModel = options.isKnownModel ??
+        (async (id) => {
+            try {
+                const { models } = await getModelCatalog(projectRoot).snapshot();
+                return models.length === 0 || models.includes(id);
+            }
+            catch {
+                return true;
+            }
+        });
+    const datasetReportFor = options.datasetReportFor ??
+        (async (evalFile) => {
+            const { datasetPath } = resolveEvalPaths(evalFile.file, evalFile.path);
+            try {
+                await stat(datasetPath);
+            }
+            catch {
+                return undefined;
+            }
+            return loadDatasetFile(datasetPath, { root: projectRoot });
+        });
+    const loaded = await Promise.all(refs.map(async (ref) => ({ ref, outcome: await loadEvalOutcome(ref.absPath, projectRoot) })));
+    const evals = loaded.flatMap(({ ref, outcome }) => outcome.ok ? [{ id: outcome.value.id, absPath: ref.absPath }] : []);
+    const entries = [];
+    for (const { ref, outcome } of loaded) {
+        let findings;
+        if (outcome.ok) {
+            const datasetReport = await datasetReportFor(outcome.value);
+            findings = await validateEval(outcome.value, {
+                projectRoot,
+                evals,
+                isKnownModel,
+                ...(datasetReport !== undefined ? { datasetReport } : {}),
+            });
+            if (datasetReport !== undefined)
+                findings.push(...datasetReport.findings);
+        }
+        else {
+            findings = evalFindingsFromIssues(ref.relPath, outcome.issues);
+        }
+        entries.push({ absPath: ref.absPath, relPath: ref.relPath, outcome, findings });
+    }
+    return entries;
+}

package/dist/config/evalWriteRoots.d.ts

@@ -0,0 +1,17 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import { type CatalogFileRef } from "./evalCatalog.js";
+export type WriteRootKind = "evals" | "datasets" | "pipelines";
+export declare function manifestForWrite(projectRoot: string): Promise<LoadedManifest>;
+export declare function explicitRoots(manifest: LoadedManifest, kind: WriteRootKind): string[] | undefined;
+export type WriteDir = {
+    absDir: string;
+    relDir: string;
+    explicitDirectory: boolean;
+};
+export declare function resolveWriteDir(projectRoot: string, manifest: LoadedManifest, kind: WriteRootKind, directory?: string): Promise<WriteDir>;
+export declare function assertInsideProject(projectRoot: string, absPath: string, what: string): void;
+export declare function evalStem(fileName: string): string;
+export declare function datasetStem(fileName: string): string;
+export declare function findEvalFile(projectRoot: string, id: string, manifest?: LoadedManifest): Promise<CatalogFileRef | undefined>;
+export declare function datasetIdsFor(refs: readonly CatalogFileRef[]): Map<string, string>;
+export declare function findDatasetFile(projectRoot: string, id: string, manifest?: LoadedManifest): Promise<CatalogFileRef | undefined>;

package/dist/config/evalWriteRoots.js

@@ -0,0 +1,109 @@
+import { realpathSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { CatalogPathError, isInsideProjectRoot } from "./catalogRelativePath.js";
+import { normalizeCatalogDir } from "./ensureCatalogScanRoot.js";
+import { listDatasetFiles, listEvalFiles } from "./evalCatalog.js";
+import { datasetFormatFromPath } from "./loadDataset.js";
+import { loadStageflowManifestOutcome, manifestPathForProject, parseStageflowManifestOutcome, } from "./loadStageflowManifest.js";
+const DEFAULT_DIR = {
+    evals: "evals",
+    datasets: "datasets",
+    pipelines: "pipelines",
+};
+export async function manifestForWrite(projectRoot) {
+    const outcome = await loadStageflowManifestOutcome(projectRoot);
+    if (outcome.ok)
+        return outcome.value;
+    const fallback = parseStageflowManifestOutcome("version: 1\ncatalog:\n  pipelines: [pipelines]\n  tasks: [tasks]\n", manifestPathForProject(projectRoot), projectRoot);
+    if (!fallback.ok)
+        throw new Error("default manifest failed to parse");
+    return fallback.value;
+}
+export function explicitRoots(manifest, kind) {
+    const entries = manifest.manifest.catalog[kind];
+    return entries === undefined ? undefined : entries.map(normalizeCatalogDir);
+}
+async function isFile(abs) {
+    try {
+        return (await stat(abs)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function containedInProject(projectRoot, absPath) {
+    let realRoot = path.resolve(projectRoot);
+    try {
+        realRoot = realpathSync(realRoot);
+    }
+    catch {
+        // project root missing: fall back to the resolved path
+    }
+    const rel = path.relative(path.resolve(projectRoot), absPath);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return false;
+    return isInsideProjectRoot(projectRoot, path.resolve(realRoot, rel));
+}
+export async function resolveWriteDir(projectRoot, manifest, kind, directory) {
+    let relDir;
+    if (directory !== undefined) {
+        if (path.isAbsolute(directory)) {
+            throw new CatalogPathError("Absolute directory is not allowed; use a path relative to the project root", "absolute_path_not_allowed", [projectRoot]);
+        }
+        relDir = normalizeCatalogDir(directory) || ".";
+    }
+    else {
+        relDir = DEFAULT_DIR[kind];
+        for (const entry of explicitRoots(manifest, kind) ?? []) {
+            if (!(await isFile(path.join(projectRoot, entry)))) {
+                relDir = entry;
+                break;
+            }
+        }
+    }
+    const absDir = path.resolve(projectRoot, relDir);
+    if (!containedInProject(projectRoot, absDir)) {
+        throw new CatalogPathError(`directory escapes project root ${projectRoot}`, "path_outside_project_root", [projectRoot]);
+    }
+    return { absDir, relDir, explicitDirectory: directory !== undefined };
+}
+export function assertInsideProject(projectRoot, absPath, what) {
+    if (!containedInProject(projectRoot, absPath)) {
+        throw new CatalogPathError(`${what} escapes project root ${projectRoot}`, "path_outside_project_root", [
+            projectRoot,
+        ]);
+    }
+}
+export function evalStem(fileName) {
+    return fileName.replace(/\.eval\.ya?ml$/, "");
+}
+export function datasetStem(fileName) {
+    return fileName.replace(/\.dataset\.(jsonl|json|csv)$/, "");
+}
+export async function findEvalFile(projectRoot, id, manifest) {
+    const m = manifest ?? (await manifestForWrite(projectRoot));
+    const refs = await listEvalFiles(m);
+    return refs.find((ref) => evalStem(path.basename(ref.absPath)) === id);
+}
+export function datasetIdsFor(refs) {
+    const byStem = new Map();
+    for (const ref of refs) {
+        const stem = datasetStem(path.basename(ref.absPath));
+        byStem.set(stem, [...(byStem.get(stem) ?? []), ref]);
+    }
+    const ids = new Map();
+    for (const [stem, group] of byStem) {
+        for (const ref of group) {
+            const format = datasetFormatFromPath(ref.absPath);
+            ids.set(ref.absPath, group.length > 1 && format !== "jsonl" ? `${stem}.${format ?? "unknown"}` : stem);
+        }
+    }
+    return ids;
+}
+export async function findDatasetFile(projectRoot, id, manifest) {
+    const m = manifest ?? (await manifestForWrite(projectRoot));
+    const refs = await listDatasetFiles(m);
+    const ids = datasetIdsFor(refs);
+    return refs.find((ref) => ids.get(ref.absPath) === id);
+}

package/dist/config/hostConfig.js

@@ -27,6 +27,7 @@ export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_READ_TOKEN",
     "STAGEFLOW_READ_TOKEN_FILE",
     "STAGEFLOW_ALLOW_UNKNOWN_CONFIG",
+    "STAGEFLOW_EVALS_KEEP_WORKDIR",
     "STAGEFLOW_MAX_CONCURRENT_RUNS",
     "STAGEFLOW_MAX_CONCURRENT_RUNS_PER_PROJECT",
     "STAGEFLOW_MAX_QUEUED",

package/dist/config/installEvalSample.d.ts

@@ -0,0 +1,34 @@
+import type { AgentDetail } from "../agents/service.js";
+export declare const EVAL_SAMPLE_FILES: {
+    readonly pipeline: "eval-sample.pipeline.yaml";
+    readonly eval: "critique-sample.eval.yaml";
+    readonly dataset: "critique-sample.dataset.jsonl";
+};
+export declare const EVAL_SAMPLE_ID = "critique-sample";
+export declare const AGENT_EVAL_SAMPLE_FILES: {
+    readonly agent: "support-sample.agent.yaml";
+    readonly eval: "support-sample.eval.yaml";
+    readonly dataset: "support-sample.dataset.jsonl";
+};
+export declare const AGENT_EVAL_SAMPLE_ID = "support-sample";
+export declare const AGENT_EVAL_SAMPLE_AGENT_ID = "support_sample";
+export type EvalSampleKind = "stage" | "agent";
+/** The slice of `AgentService` the agent sample install needs. */
+export type EvalSampleAgents = {
+    get(projectRoot: string, agentId: string): Promise<AgentDetail>;
+    create(projectRoot: string, rawInput: unknown, actor: {
+        source: "api";
+    }): Promise<AgentDetail>;
+    setEnabled(projectRoot: string, agentId: string, enabled: boolean, actor: {
+        source: "api";
+    }): Promise<AgentDetail>;
+};
+export declare function resolveEvalSampleDir(fromUrl?: string, marker?: string): string | undefined;
+export declare function installEvalSample(input: {
+    projectRoot: string;
+    sourceDir?: string;
+    kind?: EvalSampleKind;
+    agents?: EvalSampleAgents;
+}): Promise<{
+    evalId: string;
+}>;