@inflexa-ai/harness 0.1.1

package/dist/tools/research/literature-reviewer.js

@@ -0,0 +1,84 @@
+/**
+ * literatureReviewer — a sub-agent packaged as a loop-driving tool.
+ *
+ * The conversation agent delegates batch literature/biology research by
+ * calling this tool. `execute` derives a child `Session` (`forSubAgent`)
+ * and runs `runAgent` over a focused literature-reviewer agent: a research
+ * brief in, a structured evidence report out. The child's transcript is
+ * ephemeral — it lives only for this call and is never persisted (see the harness-thread-store spec).
+ *
+ * This is the whole of sub-agent delegation in the harness. There is no
+ * `agents: {}` config, no `messageFilter`, no `stripParentToolParts`: the
+ * child cannot see the parent's tool history because it is simply handed
+ * none — only the brief. The child loop uses `passthroughStep` because the
+ * entire tool call is one step in the parent loop (PR #3 caches it whole,
+ * so the child never replays).
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { finalText, runAgent } from "../../loop/run-agent.js";
+import { passthroughStep } from "../../loop/run-step.js";
+import { literatureReviewerPrompt } from "../../prompts/literature-reviewer.js";
+import { forSubAgent } from "../../auth/types.js";
+import { defineTool } from "../define-tool.js";
+import { createNcbiTools } from "../bio/keys.js";
+import { getImpcKoProfileTool } from "../bio/get-impc-ko-profile.js";
+import { lookupGoTermTool } from "../bio/lookup-go-term.js";
+import { searchBgeeExpressionTool } from "../bio/search-bgee-expression.js";
+import { searchDgidbTool } from "../bio/search-dgidb.js";
+import { searchGeneTool } from "../bio/search-gene.js";
+import { searchInteractionsTool } from "../bio/search-interactions.js";
+import { searchPathwayTool } from "../bio/search-pathway.js";
+/** Sub-agent identity — appended to `callPath`, set as `agentId`. */
+const AGENT_ID = "literature-reviewer";
+/** Multi-tool research budget — search → read → synthesize over many genes. */
+const REVIEWER_MAX_ITERATIONS = 30;
+/** Build the `literature_reviewer` delegation tool bound to its provider. */
+export function createLiteratureReviewerTool(deps) {
+    const ncbi = createNcbiTools(deps.bioKeys);
+    const reviewerTools = [
+        searchGeneTool,
+        searchPathwayTool,
+        lookupGoTermTool,
+        searchInteractionsTool,
+        ncbi.searchPubMed,
+        ncbi.getArticleDetails,
+        ncbi.getArticleFullText,
+        searchDgidbTool,
+        searchBgeeExpressionTool,
+        getImpcKoProfileTool,
+    ];
+    const agent = {
+        id: AGENT_ID,
+        systemPrompt: literatureReviewerPrompt,
+        model: deps.model,
+        tools: reviewerTools,
+        maxIterations: REVIEWER_MAX_ITERATIONS,
+    };
+    return defineTool({
+        id: "literature_reviewer",
+        description: "Delegate batch literature/biology research: looking up multiple " +
+            "genes or pathways, validating findings against published knowledge, " +
+            "or building evidence profiles. Pass a self-contained brief — the " +
+            "reviewer has no access to this conversation. Returns a structured " +
+            "evidence report. Do NOT delegate simple single-gene lookups; handle " +
+            "those directly with your own bio-lookup tools.",
+        inputSchema: z.object({
+            brief: z
+                .string()
+                .min(1)
+                .describe("A self-contained research brief: the genes, pathways, or " +
+                "biological features to investigate and the experimental " +
+                "context. The reviewer sees only this — include everything it needs."),
+        }),
+        execute: async ({ brief }, ctx) => {
+            const { messages: transcript } = await runAgent(agent, [{ role: "user", content: brief }], forSubAgent(ctx.session, AGENT_ID), {
+                provider: deps.provider,
+                signal: ctx.signal,
+                emit: ctx.emit,
+                runStep: passthroughStep,
+            });
+            return ok({ report: finalText(transcript) });
+        },
+    });
+}

package/dist/tools/research/search-arxiv.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Search arXiv for preprints. Returns Atom XML which we parse without a
+ * dependency. arXiv is the primary source for ML / physics / math /
+ * control-theory preprints; Semantic Scholar lags it by months.
+ *
+ * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
+ */
+type SearchArxivOutput = {
+    success: false;
+    error: string;
+    papers: ArxivPaper[];
+} | {
+    success: true;
+    papers: ArxivPaper[];
+};
+export interface ArxivPaper {
+    id: string;
+    title: string;
+    abstract: string;
+    authors: string[];
+    published: string;
+    categories: string[];
+    url: string;
+    pdfUrl?: string;
+}
+export declare function parseArxivAtom(xml: string): ArxivPaper[];
+export declare const searchArxivTool: import("../define-tool.js").Tool<{
+    query: string;
+    limit: number;
+    categories?: string[] | undefined;
+}, SearchArxivOutput>;
+export {};

package/dist/tools/research/search-arxiv.js

@@ -0,0 +1,123 @@
+/**
+ * Search arXiv for preprints. Returns Atom XML which we parse without a
+ * dependency. arXiv is the primary source for ML / physics / math /
+ * control-theory preprints; Semantic Scholar lags it by months.
+ *
+ * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetch, describeApiError } from "../lib/api-utils.js";
+const BASE_URL = "https://export.arxiv.org/api/query";
+const stripCdata = (s) => s.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1");
+const decodeXmlEntities = (s) => s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(parseInt(d, 10)))
+    .replace(/&amp;/g, "&"); // amp last so we don't double-decode
+const collapseWs = (s) => decodeXmlEntities(stripCdata(s)).replace(/\s+/g, " ").trim();
+const extractEntries = (xml) => {
+    const re = /<entry\b[^>]*>([\s\S]*?)<\/entry>/g;
+    const out = [];
+    let m;
+    while ((m = re.exec(xml)) !== null)
+        out.push(m[1]);
+    return out;
+};
+const firstMatch = (entry, tag) => {
+    const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`);
+    const m = entry.match(re);
+    return m?.[1];
+};
+const allMatches = (entry, tag) => {
+    const re = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`, "g");
+    const out = [];
+    let m;
+    while ((m = re.exec(entry)) !== null)
+        out.push(m[1]);
+    return out;
+};
+const linkAttr = (entry, predicate) => {
+    const re = /<link\b([^>]*)\/>/g;
+    let m;
+    while ((m = re.exec(entry)) !== null) {
+        if (predicate(m[1])) {
+            const hrefMatch = m[1].match(/href="([^"]+)"/);
+            if (hrefMatch)
+                return hrefMatch[1];
+        }
+    }
+    return undefined;
+};
+const categoryTerms = (entry) => {
+    const re = /<category\b([^>]*)\/>/g;
+    const out = [];
+    let m;
+    while ((m = re.exec(entry)) !== null) {
+        const termMatch = m[1].match(/term="([^"]+)"/);
+        if (termMatch)
+            out.push(termMatch[1]);
+    }
+    return out;
+};
+export function parseArxivAtom(xml) {
+    return extractEntries(xml).flatMap((entry) => {
+        const idRaw = firstMatch(entry, "id");
+        const title = firstMatch(entry, "title");
+        if (!idRaw || !title)
+            return [];
+        const idMatch = idRaw.match(/abs\/(.+)$/);
+        const authors = allMatches(entry, "author")
+            .map((a) => firstMatch(a, "name"))
+            .filter((n) => !!n)
+            .map(collapseWs);
+        const htmlUrl = linkAttr(entry, (a) => /rel="alternate"/.test(a) && /type="text\/html"/.test(a));
+        const pdfUrl = linkAttr(entry, (a) => /title="pdf"/.test(a));
+        return [
+            {
+                id: idMatch?.[1] ?? collapseWs(idRaw),
+                title: collapseWs(title),
+                abstract: collapseWs(firstMatch(entry, "summary") ?? ""),
+                authors,
+                published: collapseWs(firstMatch(entry, "published") ?? ""),
+                categories: categoryTerms(entry),
+                url: htmlUrl ?? collapseWs(idRaw),
+                pdfUrl,
+            },
+        ];
+    });
+}
+export const searchArxivTool = defineTool({
+    id: "search_arxiv",
+    description: "Search arXiv for preprints in ML, physics, math, control theory, " +
+        "economics, and related quantitative fields. Returns id, title, " +
+        "abstract, authors, publication date, arXiv categories, and URLs.",
+    inputSchema: z.object({
+        query: z.string().describe('Free-text query. Example: "adaptive control feedback stabilization".'),
+        categories: z
+            .array(z.string())
+            .optional()
+            .describe('Optional arXiv category filters (e.g., ["cs.LG", "math.OC"]). ' + "Combined with the query using AND."),
+        limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
+    }),
+    execute: async ({ query, categories, limit }) => {
+        const catPart = categories && categories.length > 0 ? ` AND (${categories.map((c) => `cat:${c}`).join(" OR ")})` : "";
+        const params = new URLSearchParams({
+            search_query: `all:${query}${catPart}`,
+            max_results: String(limit),
+            sortBy: "relevance",
+            sortOrder: "descending",
+        });
+        const res = await apiFetch(`${BASE_URL}?${params}`, {
+            parseAs: "text",
+        });
+        if (res.isErr()) {
+            return ok({ success: false, error: describeApiError(res.error), papers: [] });
+        }
+        return ok({ success: true, papers: parseArxivAtom(res.value) });
+    },
+});

package/dist/tools/research/search-github-repos.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Search GitHub for code repositories. Used by the analogical-reasoner to
+ * find implementations of cross-domain methods. Works unauthenticated
+ * (lower rate limit); `GITHUB_TOKEN` raises the limit.
+ *
+ * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
+ */
+type SearchGithubReposOutput = {
+    success: false;
+    error: string;
+    repos: GithubRepo[];
+} | {
+    success: true;
+    repos: GithubRepo[];
+};
+export interface GithubRepo {
+    url: string;
+    fullName: string;
+    description?: string;
+    stars: number;
+    language?: string;
+    lastUpdated?: string;
+}
+export declare function parseGithubReposResponse(raw: unknown): GithubRepo[];
+export declare function createSearchGithubReposTool(deps: {
+    githubToken?: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    limit: number;
+    language?: string | undefined;
+}, SearchGithubReposOutput>;
+export {};

package/dist/tools/research/search-github-repos.js

@@ -0,0 +1,86 @@
+/**
+ * Search GitHub for code repositories. Used by the analogical-reasoner to
+ * find implementations of cross-domain methods. Works unauthenticated
+ * (lower rate limit); `GITHUB_TOKEN` raises the limit.
+ *
+ * Same wire call and envelope as the legacy tool. Stateless HTTP; no deps.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+const BASE_URL = "https://api.github.com/search/repositories";
+// Raw GitHub search wire shape, validated at the fetch boundary. Every field is
+// optional — `parseGithubReposResponse` already filters out items missing the
+// fields it needs, so an over-strict schema would drop otherwise-usable pages.
+// `description` and `language` are also `.nullable()` because GitHub sends an
+// explicit JSON `null` (not omission) for repos lacking them — the common case,
+// which a bare `.optional()` would reject and take the whole page down with it.
+const GithubReposResponseSchema = z.object({
+    items: z
+        .array(z.object({
+        html_url: z.string().optional(),
+        full_name: z.string().optional(),
+        description: z.string().nullable().optional(),
+        stargazers_count: z.number().optional(),
+        language: z.string().nullable().optional(),
+        updated_at: z.string().optional(),
+    }))
+        .optional(),
+});
+export function parseGithubReposResponse(raw) {
+    const items = raw?.items;
+    if (!Array.isArray(items))
+        return [];
+    return items
+        .filter((i) => typeof i === "object" &&
+        i !== null &&
+        typeof i.html_url === "string" &&
+        typeof i.full_name === "string")
+        .map((i) => ({
+        url: String(i.html_url),
+        fullName: String(i.full_name),
+        description: typeof i.description === "string" ? i.description : undefined,
+        stars: typeof i.stargazers_count === "number" ? i.stargazers_count : 0,
+        language: typeof i.language === "string" ? i.language : undefined,
+        lastUpdated: typeof i.updated_at === "string" ? i.updated_at : undefined,
+    }));
+}
+export function createSearchGithubReposTool(deps) {
+    return defineTool({
+        id: "search_github_repos",
+        description: "Search GitHub for code repositories matching a free-text query, " +
+            "optionally filtered by programming language. Returns URL, full " +
+            "name (owner/repo), description, star count, primary language, " +
+            "and last-updated timestamp. Use to find implementations of " +
+            "cross-domain methods cited in analogical-reasoning results.",
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("GitHub search syntax. Plain text matches anywhere; qualifiers " + 'like "topic:bioinformatics" or "stars:>100" are supported.'),
+            language: z.string().optional().describe('Optional language filter (e.g., "python").'),
+            limit: z.number().int().min(1).max(20).default(10).describe("Maximum results (1–20, default 10)."),
+        }),
+        execute: async ({ query, language, limit }) => {
+            const q = language ? `${query} language:${language}` : query;
+            const params = new URLSearchParams({
+                q,
+                per_page: String(limit),
+                sort: "stars",
+                order: "desc",
+            });
+            const headers = {
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+            };
+            if (deps.githubToken) {
+                headers.Authorization = `Bearer ${deps.githubToken}`;
+            }
+            const res = await apiFetchValidated(`${BASE_URL}?${params}`, GithubReposResponseSchema, { headers });
+            if (res.isErr()) {
+                return ok({ success: false, error: describeApiError(res.error), repos: [] });
+            }
+            return ok({ success: true, repos: parseGithubReposResponse(res.value) });
+        },
+    });
+}

package/dist/tools/research/search-semantic-scholar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Search Semantic Scholar Graph API for academic papers across all
+ * sciences. No API key required; rate-limited but reasonable for agent
+ * use. Used by the analogical-reasoner for cross-domain analogical search.
+ *
+ * Same wire call and envelope as the legacy tool, packaged as `defineTool`.
+ * Stateless HTTP; no deps.
+ */
+export interface SemanticScholarPaper {
+    id: string;
+    title: string;
+    abstract?: string;
+    year?: number;
+    venue?: string;
+    citationCount?: number;
+    url?: string;
+    authors: string[];
+    externalIds?: Record<string, string>;
+}
+type SearchSemanticScholarOutput = {
+    success: false;
+    error: string;
+    papers: SemanticScholarPaper[];
+} | {
+    success: true;
+    papers: SemanticScholarPaper[];
+};
+export declare function parseSemanticScholarResponse(raw: unknown): SemanticScholarPaper[];
+export declare const searchSemanticScholarTool: import("../define-tool.js").Tool<{
+    query: string;
+    limit: number;
+}, SearchSemanticScholarOutput>;
+export {};

package/dist/tools/research/search-semantic-scholar.js

@@ -0,0 +1,93 @@
+/**
+ * Search Semantic Scholar Graph API for academic papers across all
+ * sciences. No API key required; rate-limited but reasonable for agent
+ * use. Used by the analogical-reasoner for cross-domain analogical search.
+ *
+ * Same wire call and envelope as the legacy tool, packaged as `defineTool`.
+ * Stateless HTTP; no deps.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+const BASE_URL = "https://api.semanticscholar.org/graph/v1";
+const DEFAULT_FIELDS = "paperId,title,abstract,year,venue,citationCount,url,authors,externalIds";
+// Raw Semantic Scholar wire shape, validated at the fetch boundary. Every field
+// is optional — `parseSemanticScholarResponse` already filters/coerces defensively,
+// so a partial-but-valid response must still parse; `externalIds` values stay
+// unconstrained (`z.unknown`) since the mapper only checks the container is an object.
+// The scalar fields are also `.nullable()`: Semantic Scholar sends an explicit
+// `null` for a missing abstract/year/venue/url/externalIds (very common), which a
+// bare `.optional()` would reject — failing the whole `data` array on one such paper.
+const SemanticScholarResponseSchema = z.object({
+    data: z
+        .array(z.object({
+        paperId: z.string().optional(),
+        title: z.string().optional(),
+        abstract: z.string().nullable().optional(),
+        year: z.number().nullable().optional(),
+        venue: z.string().nullable().optional(),
+        citationCount: z.number().nullable().optional(),
+        url: z.string().nullable().optional(),
+        authors: z.array(z.object({ name: z.string().nullable().optional() })).optional(),
+        externalIds: z.record(z.string(), z.unknown()).nullable().optional(),
+    }))
+        .optional(),
+});
+export function parseSemanticScholarResponse(raw) {
+    const data = raw?.data;
+    if (!Array.isArray(data))
+        return [];
+    return data
+        .filter((p) => typeof p === "object" && p !== null && "paperId" in p && "title" in p)
+        .map((p) => {
+        const authors = Array.isArray(p.authors)
+            ? p.authors.map((a) => a?.name).filter((n) => typeof n === "string")
+            : [];
+        return {
+            id: String(p.paperId),
+            title: String(p.title),
+            abstract: typeof p.abstract === "string" ? p.abstract : undefined,
+            year: typeof p.year === "number" ? p.year : undefined,
+            venue: typeof p.venue === "string" ? p.venue : undefined,
+            citationCount: typeof p.citationCount === "number" ? p.citationCount : undefined,
+            url: typeof p.url === "string" ? p.url : undefined,
+            authors,
+            externalIds: p.externalIds && typeof p.externalIds === "object" ? p.externalIds : undefined,
+        };
+    });
+}
+export const searchSemanticScholarTool = defineTool({
+    id: "search_semantic_scholar",
+    description: "Search Semantic Scholar for academic papers across all sciences " +
+        "(biology, ML, physics, math, economics, engineering, etc.). Returns " +
+        "paper id, title, abstract, year, venue, citation count, authors, and " +
+        "external IDs (DOI, ArXiv). Best for cross-domain analogical search.",
+    inputSchema: z.object({
+        query: z
+            .string()
+            .describe("Free-text query. Use natural language phrases such as " + '"reinforcement learning for control" or "feedback stabilisation in oscillators".'),
+        limit: z.number().int().min(1).max(20).default(10).describe("Maximum number of results to return (1–20, default 10)."),
+    }),
+    execute: async ({ query, limit }) => {
+        const params = new URLSearchParams({
+            query,
+            limit: String(limit),
+            fields: DEFAULT_FIELDS,
+        });
+        const apiKey = process.env.SEMANTIC_SCHOLAR_API_KEY;
+        const headers = {};
+        if (apiKey)
+            headers["x-api-key"] = apiKey;
+        const res = await apiFetchValidated(`${BASE_URL}/paper/search?${params}`, SemanticScholarResponseSchema, {
+            headers,
+        });
+        if (res.isErr()) {
+            return ok({ success: false, error: describeApiError(res.error), papers: [] });
+        }
+        return ok({
+            success: true,
+            papers: parseSemanticScholarResponse(res.value),
+        });
+    },
+});

package/dist/tools/run-ephemeral.d.ts

@@ -0,0 +1,33 @@
+/**
+ * run_ephemeral — ad-hoc data exploration in a read-only sandbox.
+ *
+ * Authorizes the run at the async edge via the RunAuthorizer seam, then starts
+ * the ephemeral workflow through the RunLauncher seam and awaits its result
+ * inline within the chat turn. Chat disconnect cancels the run; the
+ * authorization is revoked on every terminal path. The workflow is never
+ * recovered — a turn-scoped exploration outliving its turn has no value.
+ *
+ * Available to: conversation-agent.
+ */
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { RunLauncher } from "../execution/run-launcher.js";
+import { type EphemeralResult, type EphemeralWorkflowInput } from "../execution/ephemeral-runner.js";
+export interface RunEphemeralToolDeps {
+    /** Registered ephemeral workflow callable. */
+    readonly workflow: (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
+    /** Authorizes the run at the async edge and revokes on the terminal path. */
+    readonly runAuthorizer: RunAuthorizer;
+    /** Starts the durable run — the durability engine stays behind this seam. */
+    readonly runLauncher: RunLauncher;
+}
+export interface RunEphemeralToolOutput {
+    readonly text: string;
+    readonly durationMs: number;
+}
+/** Build the `run_ephemeral` tool bound to the registered workflow + mint deps. */
+export declare function createRunEphemeralTool(deps: RunEphemeralToolDeps): import("./define-tool.js").Tool<{
+    prompt: string;
+}, {
+    text: string;
+    durationMs: number;
+}>;

package/dist/tools/run-ephemeral.js

@@ -0,0 +1,65 @@
+/**
+ * run_ephemeral — ad-hoc data exploration in a read-only sandbox.
+ *
+ * Authorizes the run at the async edge via the RunAuthorizer seam, then starts
+ * the ephemeral workflow through the RunLauncher seam and awaits its result
+ * inline within the chat turn. Chat disconnect cancels the run; the
+ * authorization is revoked on every terminal path. The workflow is never
+ * recovered — a turn-scoped exploration outliving its turn has no value.
+ *
+ * Available to: conversation-agent.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { EPHEMERAL_WORKFLOW_PREFIX } from "../execution/ephemeral-runner.js";
+import { generateExecutionId } from "../sandbox/execution-id.js";
+import { defineTool } from "./define-tool.js";
+const inputSchema = z.object({
+    prompt: z
+        .string()
+        .min(1)
+        .describe("What to compute. Be specific: which files to read, what analysis to " + "run, what output format to return (table, statistics, base64 plot)."),
+});
+/** Build the `run_ephemeral` tool bound to the registered workflow + mint deps. */
+export function createRunEphemeralTool(deps) {
+    return defineTool({
+        id: "run_ephemeral",
+        description: "Run a quick computation on the analysis data in a read-only sandbox. " +
+            "Use for ad-hoc data exploration: inspect a CSV, compute statistics, " +
+            "generate plot data, preview transformations. The sandbox cannot " +
+            "create or save files — results are returned inline. For persistent " +
+            "analyses that produce artifacts, use generate_plan + executePlan instead.",
+        inputSchema,
+        execute: async (input, ctx) => {
+            const { session } = ctx;
+            if (session.scope.kind !== "analysis") {
+                throw new Error("run_ephemeral requires an analysis-scoped session — got " + session.scope.kind);
+            }
+            if (!session.auth) {
+                throw new Error("run_ephemeral: session is missing its auth capability");
+            }
+            const authorization = await deps.runAuthorizer.authorize({
+                auth: session.auth,
+                scope: session.scope,
+                provenance: session.provenance,
+                frame: { runId: "ephemeral", stepId: "ephemeral" },
+            });
+            const { runSession } = authorization;
+            const execId = generateExecutionId("ephemeral-executor");
+            const workflowId = `${EPHEMERAL_WORKFLOW_PREFIX}${execId}`;
+            try {
+                const outcome = await deps.runLauncher.launchAndAwait(deps.workflow, { workflowId }, { runSession, prompt: input.prompt }, { signal: ctx.signal });
+                if (outcome.status === "cancelled") {
+                    return ok({ text: "(ephemeral exploration cancelled)", durationMs: 0 });
+                }
+                return ok({
+                    text: outcome.result.text,
+                    durationMs: outcome.result.durationMs,
+                });
+            }
+            finally {
+                await deps.runAuthorizer.revoke(authorization, "ephemeral-completed").catch(() => { });
+            }
+        },
+    });
+}

package/dist/tools/sandbox/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Sandbox barrel — sandbox-environment introspection (available lib-store
+ * packages and reference datasets). Consumed by sandbox agents.
+ */
+export * from "./list-available-packages.js";
+export * from "./list-available-refs.js";
+export * from "./report-blocker.js";

package/dist/tools/sandbox/index.js

@@ -0,0 +1,7 @@
+/**
+ * Sandbox barrel — sandbox-environment introspection (available lib-store
+ * packages and reference datasets). Consumed by sandbox agents.
+ */
+export * from "./list-available-packages.js";
+export * from "./list-available-refs.js";
+export * from "./report-blocker.js";

package/dist/tools/sandbox/list-available-packages.d.ts

@@ -0,0 +1,7 @@
+/**
+ * listAvailablePackages — list R/Python/CLI packages available in the sandbox.
+ */
+export declare const listAvailablePackagesTool: import("../define-tool.js").Tool<Record<string, never>, {
+    available: boolean;
+    content: string;
+}>;

package/dist/tools/sandbox/list-available-packages.js

@@ -0,0 +1,27 @@
+/**
+ * listAvailablePackages — list R/Python/CLI packages available in the sandbox.
+ */
+import { readFile } from "node:fs/promises";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+const PACKAGES_FILE = "/mnt/libs/current/packages.txt";
+export const listAvailablePackagesTool = defineTool({
+    id: "list_available_packages",
+    description: "List all R, Python, and CLI packages available in the sandbox environment. Use this before writing analysis scripts to verify which packages you can import. No packages can be installed at runtime — only what this tool returns is available.",
+    inputSchema: z.object({}),
+    execute: async () => {
+        // A missing library-store mount is an expected environment state — model
+        // it as an `available: false` data variant with a helpful fallback note.
+        try {
+            const content = await readFile(PACKAGES_FILE, "utf-8");
+            return ok({ available: true, content });
+        }
+        catch {
+            return ok({
+                available: false,
+                content: "Package list not available. The library store may not be mounted. Assume standard bioinformatics packages (numpy, pandas, scanpy, DESeq2, etc.) are available, but do not attempt to install anything.",
+            });
+        }
+    },
+});

package/dist/tools/sandbox/list-available-refs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * listAvailableRefs — list reference data available in the sandbox.
+ */
+export declare const listAvailableRefsTool: import("../define-tool.js").Tool<Record<string, never>, {
+    available: boolean;
+    content: string;
+}>;