@aiden-ade/sandbox-agent 0.1.59 → 0.1.60

package/dist/lifecycle-logger.js

@@ -0,0 +1,73 @@
+import { AGENT_VERSION } from "./version.js";
+export class AgentLifecycleLogger {
+    context;
+    constructor(context = {}) {
+        this.context = normalizeContext(context);
+    }
+    setContext(context) {
+        this.context = normalizeContext({ ...this.context, ...context });
+    }
+    child(context) {
+        return new AgentLifecycleLogger({ ...this.context, ...context });
+    }
+    debug(event, fields = {}) {
+        this.log("debug", event, fields);
+    }
+    info(event, fields = {}) {
+        this.log("info", event, fields);
+    }
+    warn(event, fields = {}) {
+        this.log("warn", event, fields);
+    }
+    error(event, fields = {}) {
+        this.log("error", event, fields);
+    }
+    log(level, event, fields) {
+        const record = omitUndefined({
+            ts: new Date().toISOString(),
+            level,
+            component: "agent-manager",
+            event,
+            ...this.context,
+            ...normalizeFields(fields),
+        });
+        console[level](JSON.stringify(record));
+    }
+}
+export function lifecycleContextFromEnv(env) {
+    return normalizeContext({
+        taskId: env.ALAN_TASK_ID,
+        conversationId: env.ALAN_SESSION_ID,
+        runId: env.ALAN_RUN_ID,
+        sandboxId: env.ALAN_SANDBOX_ID,
+        provider: env.ALAN_SANDBOX_PROVIDER,
+        backendKind: env.ALAN_BACKEND_KIND,
+        agentVersion: AGENT_VERSION,
+    });
+}
+function normalizeContext(context) {
+    return omitUndefined({
+        ...context,
+        agentVersion: context.agentVersion ?? AGENT_VERSION,
+    });
+}
+function normalizeFields(fields) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value instanceof Error) {
+            normalized[key] = {
+                name: value.name,
+                message: value.message,
+                stack: value.stack,
+            };
+        }
+        else {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+function omitUndefined(record) {
+    return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined));
+}
+//# sourceMappingURL=lifecycle-logger.js.map

package/dist/lifecycle-logger.js.map

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

package/dist/local-skill-scan.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Local (desktop) skill filesystem scan.
+ *
+ * TypeScript mirror of the cloud sandbox scan
+ * (apps/api/src/services/skills/cloud-skill-scan.ts): same directory roots
+ * (SKILL_DIRECTORY_ROOTS), same 8KiB head-read limit, same shared
+ * normalize/dedupe contract (packages/shared/src/agent/skill-discovery.ts) so
+ * a skill scanned locally and one scanned in a cloud sandbox produce
+ * identical identity keys, repo attribution, and descriptions.
+ */
+import { type SkillEntry } from "@alan-ai/shared/agent";
+export interface LocalSkillScanResult {
+    skills: SkillEntry[];
+    errors: string[];
+}
+export declare function scanLocalSkills(homeDir: string, projectPath?: string | null): LocalSkillScanResult;
+/** Cached wrapper — mirrors the cloud scan's per-machine result cache. */
+export declare function scanLocalSkillsCached(homeDir: string, projectPath: string | null | undefined, options?: {
+    refresh?: boolean;
+}): LocalSkillScanResult;
+//# sourceMappingURL=local-skill-scan.d.ts.map

package/dist/local-skill-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-skill-scan.d.ts","sourceRoot":"","sources":["../src/local-skill-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAM/B,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAiED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,GAC1B,oBAAoB,CAiBtB;AAID,0EAA0E;AAC1E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9B,oBAAoB,CAUtB"}

package/dist/local-skill-scan.js

@@ -0,0 +1,109 @@
+/**
+ * Local (desktop) skill filesystem scan.
+ *
+ * TypeScript mirror of the cloud sandbox scan
+ * (apps/api/src/services/skills/cloud-skill-scan.ts): same directory roots
+ * (SKILL_DIRECTORY_ROOTS), same 8KiB head-read limit, same shared
+ * normalize/dedupe contract (packages/shared/src/agent/skill-discovery.ts) so
+ * a skill scanned locally and one scanned in a cloud sandbox produce
+ * identical identity keys, repo attribution, and descriptions.
+ */
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { normalizeSkillEntries, SKILL_DIRECTORY_ROOTS, } from "@alan-ai/shared/agent";
+/** Matches the cloud scan's `head -c 8192` — autocomplete only needs frontmatter. */
+const SKILL_READ_LIMIT_BYTES = 8192;
+const SKILL_CACHE_TTL_MS = 30_000;
+function readSkillHead(path) {
+    const fd = openSync(path, "r");
+    try {
+        const buffer = Buffer.alloc(SKILL_READ_LIMIT_BYTES);
+        const bytesRead = readSync(fd, buffer, 0, SKILL_READ_LIMIT_BYTES, 0);
+        return buffer.subarray(0, bytesRead).toString("utf-8");
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function scanSkillDir(dirPath, source, repoRoot, entries, errors) {
+    if (!existsSync(dirPath))
+        return;
+    let names;
+    try {
+        names = readdirSync(dirPath);
+    }
+    catch (error) {
+        errors.push(`Failed to scan ${dirPath}: ${error instanceof Error ? error.message : error}`);
+        return;
+    }
+    for (const name of names) {
+        const skillPath = join(dirPath, name, "SKILL.md");
+        let isDirectory = false;
+        try {
+            isDirectory = statSync(join(dirPath, name)).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDirectory || !existsSync(skillPath))
+            continue;
+        try {
+            entries.push({ content: readSkillHead(skillPath), source, sourcePath: skillPath, repoRoot });
+        }
+        catch (error) {
+            errors.push(`Failed to read ${skillPath}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+}
+/** Immediate, non-hidden child directories — sibling repos in a workspace root. */
+function discoverChildRepos(parentPath) {
+    let names;
+    try {
+        names = readdirSync(parentPath);
+    }
+    catch {
+        return [];
+    }
+    const children = [];
+    for (const name of names) {
+        if (name.startsWith("."))
+            continue;
+        const childPath = join(parentPath, name);
+        try {
+            if (statSync(childPath).isDirectory())
+                children.push(childPath);
+        }
+        catch { }
+    }
+    return children;
+}
+export function scanLocalSkills(homeDir, projectPath) {
+    const rawEntries = [];
+    const errors = [];
+    for (const root of SKILL_DIRECTORY_ROOTS) {
+        scanSkillDir(join(homeDir, root), "global", undefined, rawEntries, errors);
+    }
+    if (projectPath) {
+        for (const dir of [projectPath, ...discoverChildRepos(projectPath)]) {
+            for (const root of SKILL_DIRECTORY_ROOTS) {
+                scanSkillDir(join(dir, root), "team", dir, rawEntries, errors);
+            }
+        }
+    }
+    return { skills: normalizeSkillEntries(rawEntries, "team"), errors };
+}
+const skillScanCache = new Map();
+/** Cached wrapper — mirrors the cloud scan's per-machine result cache. */
+export function scanLocalSkillsCached(homeDir, projectPath, options) {
+    const key = projectPath ?? "";
+    const now = Date.now();
+    if (!options?.refresh) {
+        const cached = skillScanCache.get(key);
+        if (cached && cached.expiresAt > now)
+            return cached.result;
+    }
+    const result = scanLocalSkills(homeDir, projectPath);
+    skillScanCache.set(key, { expiresAt: now + SKILL_CACHE_TTL_MS, result });
+    return result;
+}
+//# sourceMappingURL=local-skill-scan.js.map

package/dist/local-skill-scan.js.map

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

package/dist/local-workspace-migration.d.ts

@@ -0,0 +1,68 @@
+export type GitExecutor = (cwd: string, args: string[]) => string;
+export type DirtyWorkspaceAction = "move_via_stash" | "commit_wip" | "discard" | "leave";
+export type WorkspaceMigrationDirection = "checkout_to_worktree" | "worktree_to_checkout";
+export interface GitTreePreflight {
+    currentBranch: string | null;
+    dirtyFileCount: number;
+    isDirty: boolean;
+}
+export interface WorkspaceMigrationPreflight {
+    direction: WorkspaceMigrationDirection;
+    source: GitTreePreflight;
+    destination: GitTreePreflight | null;
+}
+export interface MigrationStash {
+    oid: string;
+    label: string;
+    createdAt: string;
+}
+export interface DirtyTreeResolution {
+    action: DirtyWorkspaceAction;
+    before: GitTreePreflight;
+    after: GitTreePreflight;
+    stash: MigrationStash | null;
+    commitOid: string | null;
+}
+export interface MigrationGitDependencies {
+    git: GitExecutor;
+    now?: () => Date;
+    createId?: () => string;
+}
+export declare class MigrationStashApplyError extends Error {
+    readonly stash: MigrationStash;
+    readonly stashPreserved = true;
+    constructor(stash: MigrationStash, cause: unknown);
+}
+/**
+ * Count porcelain-v1 NUL records without returning paths to callers. Rename and
+ * copy entries contain an extra path record, which must not be counted as a
+ * second dirty file.
+ */
+export declare function countPorcelainEntries(output: string): number;
+export declare function preflightGitTree(cwd: string, git: GitExecutor): GitTreePreflight;
+export declare function preflightWorkspaceMigration(input: {
+    direction: WorkspaceMigrationDirection;
+    sourcePath: string;
+    destinationPath?: string;
+}, git: GitExecutor): WorkspaceMigrationPreflight;
+export declare function createMigrationStash(input: {
+    cwd: string;
+    operation: string;
+}, dependencies: MigrationGitDependencies): MigrationStash | null;
+export declare function dropMigrationStash(cwd: string, stash: MigrationStash, git: GitExecutor): boolean;
+/**
+ * Apply a transferred stash to the migration destination. A failed apply never
+ * drops the stash, so the caller can surface the stash handle for recovery.
+ */
+export declare function applyMigrationStash(input: {
+    cwd: string;
+    stash: MigrationStash;
+    dropOnSuccess?: boolean;
+}, git: GitExecutor): GitTreePreflight;
+export declare function resolveDirtyTree(input: {
+    cwd: string;
+    action: DirtyWorkspaceAction;
+    operation: string;
+    confirmDiscard?: boolean;
+}, dependencies: MigrationGitDependencies): DirtyTreeResolution;
+//# sourceMappingURL=local-workspace-migration.d.ts.map

package/dist/local-workspace-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-workspace-migration.d.ts","sourceRoot":"","sources":["../src/local-workspace-migration.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;AAElE,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzF,MAAM,MAAM,2BAA2B,GAAG,sBAAsB,GAAG,sBAAsB,CAAC;AAE1F,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,2BAA2B,CAAC;IACvC,MAAM,EAAE,gBAAgB,CAAC;IACzB,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,WAAW,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,cAAc,QAAQ;gBAEnB,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO;CAKlD;AA0BD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAgB5D;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,gBAAgB,CAWhF;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE;IACL,SAAS,EAAE,2BAA2B,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,EACD,GAAG,EAAE,WAAW,GACf,2BAA2B,CAM7B;AAoBD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EACzC,YAAY,EAAE,wBAAwB,GACrC,cAAc,GAAG,IAAI,CAYvB;AASD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAKhG;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,cAAc,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,EACD,GAAG,EAAE,WAAW,GACf,gBAAgB,CAWlB;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE;IACL,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,EACD,YAAY,EAAE,wBAAwB,GACrC,mBAAmB,CAqCrB"}

package/dist/local-workspace-migration.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+export class MigrationStashApplyError extends Error {
+    stash;
+    stashPreserved = true;
+    constructor(stash, cause) {
+        super(`Could not apply migration stash ${stash.oid}; the stash was preserved`, { cause });
+        this.name = "MigrationStashApplyError";
+        this.stash = stash;
+    }
+}
+const BRANCH_LABEL_MAX_LENGTH = 256;
+function stripControlCharacters(value) {
+    return Array.from(value)
+        .filter((character) => {
+        const code = character.charCodeAt(0);
+        return code >= 32 && code !== 127;
+    })
+        .join("");
+}
+function sanitizeLabel(value, fallback) {
+    const sanitized = stripControlCharacters(value)
+        .replace(/[^a-zA-Z0-9._/-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, BRANCH_LABEL_MAX_LENGTH);
+    return sanitized || fallback;
+}
+function sanitizeBranch(value) {
+    const sanitized = stripControlCharacters(value.trim()).slice(0, BRANCH_LABEL_MAX_LENGTH);
+    return sanitized || null;
+}
+/**
+ * Count porcelain-v1 NUL records without returning paths to callers. Rename and
+ * copy entries contain an extra path record, which must not be counted as a
+ * second dirty file.
+ */
+export function countPorcelainEntries(output) {
+    const records = output.split("\0");
+    let count = 0;
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index];
+        if (!record)
+            continue;
+        count += 1;
+        const status = record.slice(0, 2);
+        if (status.includes("R") || status.includes("C")) {
+            index += 1;
+        }
+    }
+    return count;
+}
+export function preflightGitTree(cwd, git) {
+    const currentBranch = sanitizeBranch(git(cwd, ["branch", "--show-current"]));
+    const dirtyFileCount = countPorcelainEntries(git(cwd, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]));
+    return {
+        currentBranch,
+        dirtyFileCount,
+        isDirty: dirtyFileCount > 0,
+    };
+}
+export function preflightWorkspaceMigration(input, git) {
+    return {
+        direction: input.direction,
+        source: preflightGitTree(input.sourcePath, git),
+        destination: input.destinationPath ? preflightGitTree(input.destinationPath, git) : null,
+    };
+}
+function uniqueOperationLabel(operation, dependencies) {
+    const now = (dependencies.now ?? (() => new Date()))();
+    const createdAt = now.toISOString();
+    const id = (dependencies.createId ?? randomUUID)();
+    return {
+        label: [
+            "alan-migration",
+            sanitizeLabel(operation, "workspace"),
+            createdAt.replace(/[:.]/g, "-"),
+            sanitizeLabel(id, "operation"),
+        ].join("/"),
+        createdAt,
+    };
+}
+export function createMigrationStash(input, dependencies) {
+    const before = preflightGitTree(input.cwd, dependencies.git);
+    if (!before.isDirty)
+        return null;
+    const { label, createdAt } = uniqueOperationLabel(input.operation, dependencies);
+    dependencies.git(input.cwd, ["stash", "push", "--include-untracked", "--message", label]);
+    const oid = dependencies.git(input.cwd, ["rev-parse", "--verify", "refs/stash"]).trim();
+    if (!oid) {
+        throw new Error("Git did not return the created migration stash");
+    }
+    return { oid, label, createdAt };
+}
+function findStashRef(cwd, oid, git) {
+    const matchingLine = git(cwd, ["stash", "list", "--format=%H %gd"])
+        .split("\n")
+        .find((line) => line.startsWith(`${oid} `));
+    return matchingLine?.slice(oid.length + 1).trim() || null;
+}
+export function dropMigrationStash(cwd, stash, git) {
+    const stashRef = findStashRef(cwd, stash.oid, git);
+    if (!stashRef)
+        return false;
+    git(cwd, ["stash", "drop", stashRef]);
+    return true;
+}
+/**
+ * Apply a transferred stash to the migration destination. A failed apply never
+ * drops the stash, so the caller can surface the stash handle for recovery.
+ */
+export function applyMigrationStash(input, git) {
+    try {
+        git(input.cwd, ["stash", "apply", "--index", input.stash.oid]);
+    }
+    catch (cause) {
+        throw new MigrationStashApplyError(input.stash, cause);
+    }
+    if (input.dropOnSuccess !== false) {
+        dropMigrationStash(input.cwd, input.stash, git);
+    }
+    return preflightGitTree(input.cwd, git);
+}
+export function resolveDirtyTree(input, dependencies) {
+    if (input.action === "discard" && input.confirmDiscard !== true) {
+        throw new Error("Discarding workspace changes requires explicit confirmation");
+    }
+    const before = preflightGitTree(input.cwd, dependencies.git);
+    let stash = null;
+    let commitOid = null;
+    if (before.isDirty) {
+        switch (input.action) {
+            case "leave":
+                break;
+            case "move_via_stash":
+                stash = createMigrationStash({ cwd: input.cwd, operation: input.operation }, dependencies);
+                break;
+            case "commit_wip": {
+                const { label } = uniqueOperationLabel(input.operation, dependencies);
+                dependencies.git(input.cwd, ["add", "--all"]);
+                dependencies.git(input.cwd, ["commit", "--message", `WIP: ${label}`]);
+                commitOid = dependencies.git(input.cwd, ["rev-parse", "HEAD"]).trim() || null;
+                break;
+            }
+            case "discard":
+                dependencies.git(input.cwd, ["reset", "--hard", "HEAD"]);
+                dependencies.git(input.cwd, ["clean", "-fd"]);
+                break;
+        }
+    }
+    return {
+        action: input.action,
+        before,
+        after: preflightGitTree(input.cwd, dependencies.git),
+        stash,
+        commitOid,
+    };
+}
+//# sourceMappingURL=local-workspace-migration.js.map

package/dist/local-workspace-migration.js.map

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

package/dist/mcp-readiness.d.ts

@@ -0,0 +1,59 @@
+import { type AlanMcpRegistration } from "@alan-ai/shared/agent";
+import type { ProviderMcpLoadStatus } from "./mcp-registration.js";
+export type McpReadinessMode = "off" | "observe" | "enforce";
+export type McpReadinessStage = "config" | "connect" | "protocol" | "tools";
+export type McpReadinessFailureCode = "app.mcp.config_invalid" | "app.mcp.auth_invalid" | "app.mcp.endpoint_unavailable" | "app.mcp.protocol_invalid" | "app.mcp.tools_missing";
+export interface McpReadinessFailure {
+    ok: false;
+    code: McpReadinessFailureCode;
+    stage: McpReadinessStage;
+    message: string;
+    retryable: boolean;
+    paths: string[];
+    missingTools?: string[];
+}
+export interface McpReadinessSuccess {
+    ok: true;
+    paths: string[];
+    /**
+     * How the run was cleared. `legacy` is distinct from `off` on purpose: it
+     * means the API did not send a readiness contract, which is the number to
+     * watch before turning `enforce` on for a deployment.
+     */
+    verification: "off" | "legacy" | "observed" | "enforced";
+    providerLoadStatus?: ProviderMcpLoadStatus;
+    durationMs?: number;
+    toolCount?: number;
+}
+export type McpReadinessResult = McpReadinessSuccess | McpReadinessFailure;
+export interface McpReadinessClient {
+    listTools(request?: undefined, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        tools?: Array<{
+            name: string;
+        }>;
+    }>;
+    close(): void | Promise<void>;
+}
+export type McpReadinessClientFactory = (input: {
+    registration: AlanMcpRegistration;
+    signal: AbortSignal;
+}) => Promise<McpReadinessClient>;
+export declare function probeAlanMcpReadiness(registration: AlanMcpRegistration, options?: {
+    paths?: string[];
+    timeoutMs?: number;
+    clientFactory?: McpReadinessClientFactory;
+}): Promise<McpReadinessResult>;
+export declare function prepareAlanMcpForRun(backendKind: string, registration: AlanMcpRegistration, options?: {
+    mode?: McpReadinessMode;
+    home?: string;
+    clientFactory?: McpReadinessClientFactory;
+    timeoutMs?: number;
+    /**
+     * Called with the detached probe's verdict in `observe` mode, after the run
+     * has already been allowed to start. Never called in `off` or `enforce`.
+     */
+    onObservedResult?: (failure: McpReadinessFailure) => void;
+}): Promise<McpReadinessResult>;
+//# sourceMappingURL=mcp-readiness.d.ts.map

package/dist/mcp-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-readiness.d.ts","sourceRoot":"","sources":["../src/mcp-readiness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,mBAAmB,EAAoC,MAAM,uBAAuB,CAAC;AAMnG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGnE,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAC7D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAC5E,MAAM,MAAM,uBAAuB,GAC/B,wBAAwB,GACxB,sBAAsB,GACtB,8BAA8B,GAC9B,0BAA0B,GAC1B,uBAAuB,CAAC;AAE5B,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,uBAAuB,CAAC;IAC9B,KAAK,EAAE,iBAAiB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;OAIG;IACH,YAAY,EAAE,KAAK,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IACzD,kBAAkB,CAAC,EAAE,qBAAqB,CAAC;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AAE3E,MAAM,WAAW,kBAAkB;IACjC,SAAS,CACP,OAAO,CAAC,EAAE,SAAS,EACnB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjC,OAAO,CAAC;QAAE,KAAK,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAAC;IAChD,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,MAAM,yBAAyB,GAAG,CAAC,KAAK,EAAE;IAC9C,YAAY,EAAE,mBAAmB,CAAC;IAClC,MAAM,EAAE,WAAW,CAAC;CACrB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAkFlC,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,mBAAmB,EACjC,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,yBAAyB,CAAC;CACtC,GACL,OAAO,CAAC,kBAAkB,CAAC,CAqD7B;AAED,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,mBAAmB,EACjC,OAAO,GAAE;IACP,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,yBAAyB,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACtD,GACL,OAAO,CAAC,kBAAkB,CAAC,CAgF7B"}