@inflexa-ai/harness 0.20.0 → 0.21.1

package/dist/tools/report-session/examine-page.d.ts

@@ -9,30 +9,45 @@
  * page lives at `report-sessions/{threadId}/index.html` under the workspace root, which the preview writes.
  * A missed page means that no preview ran, and it is a typed outcome, not a throw.
  *
- * The `file://` URL resolves on the filesystem of the Chrome sidecar, because the connection is out of
- * process. Thus the sidecar must mount the workspace tree of the harness host at the same path. A sidecar
+ * The composition says where a browser comes from, and the eyes seam is that answer. One look acquires one
+ * lease, and the tool captures against the endpoint of that lease.
+ *
+ * The `file://` URL resolves on the filesystem of the browser, because the connection is out of process.
+ * Thus the browser of a lease must hold the workspace tree of the harness host at the same path. A browser
  * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
  *
- * A composition that names no browser and injects no capture seam has no eyes at all. The tool reports that
- * condition once, up front, and it stamps nothing. A per-attempt capture failure would instead read as a
- * transient fault and invite a repeat of a call that can never pass.
+ * The tool releases the lease after the look. The release runs on a pass and on a failed capture alike. That
+ * release is hygiene, and it is not the guarantee against a leak. A process can die between the acquire and
+ * the release, thus the realization bounds the life of what it provisions. As a result a failed release
+ * changes no outcome, and the log is its whole record.
+ *
+ * A composition with no capture seam, no eyes seam, and no configured endpoint has no eyes at all. The tool
+ * reports that condition one time, up front, and it stamps nothing. A per-attempt capture failure would
+ * instead read as a transient fault, and it would invite a repeat of a call that can never pass.
  *
  * On a capture the tool copies the rendered hash onto the seen hash through the gateway. Thus the look
  * counts, and the record tool lets the current draft record. The copy takes the rendered hash and never the
- * current one, thus a later edit makes the look stale and the record refuses.
+ * current one, thus a later edit makes the look stale and the record refuses. A picture of the window alone
+ * is a true picture of the current document, thus it stamps the same and the coverage of the result is what
+ * tells the agent what it saw.
  *
  * The gateway reports whether a rendered hash existed to copy. When the row holds none, no preview stamped
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The chrome navigation and the workspace-root seam each speak the throw protocol. The tool runs the capture
- * inside a guard, thus a genuine fault becomes a typed outcome and a control-flow exception propagates.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
+ * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ *
+ * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
+ * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
+ * and no outcome would ever arrive.
  */
 import { z } from "zod";
 import { type ChromeConfig } from "../../lib/chrome.js";
+import { type AcquireEyes } from "../../lib/eyes.js";
 import { type Logger } from "../../lib/logger.js";
 import { type CapturePage, type FailedRequest, type PageCapture } from "../../lib/page-capture.js";
-import type { ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
 import { type Tool } from "../define-tool.js";
 import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
 export type { CapturePage, FailedRequest, PageCapture };
@@ -41,11 +56,13 @@ declare const examinePageInput: z.ZodObject<{}, z.core.$strip>;
 export type ExaminePageInput = z.infer<typeof examinePageInput>;
 /**
  * The typed outcome of the eyes tool. Each arm is ok-channel data, thus the tool never throws for a
- * degraded condition. `examined` carries the console errors, the failed requests, and the page path. The
- * screenshot does not ride the JSON. It rides the image path of the tool result, thus the model sees the
- * picture and the JSON text holds no bytes. `missed-stamp` means that the row holds no rendered hash, thus
- * no preview stamped one and the agent must run a new preview before the next look. `no-browser` means that
- * the composition gives no browser, thus no look is possible at all and a repeat gives the same answer.
+ * degraded condition. `examined` carries the coverage of the picture, the console errors, the failed
+ * requests, and the page path. The coverage names what the agent saw: the whole document, or the window
+ * alone when the browser refused a full-page bitmap. The screenshot does not ride the JSON. It rides the
+ * image path of the tool result, thus the model sees the picture and the JSON text holds no bytes.
+ * `missed-stamp` means that the row holds no rendered hash, thus no preview stamped one and the agent must
+ * run a new preview before the next look. `no-browser` means that the composition gives no browser, thus no
+ * look is possible at all and a repeat gives the same answer.
  */
 export type ExaminePageResult = {
     outcome: "refused";
@@ -62,6 +79,7 @@ export type ExaminePageResult = {
     detail: string;
 } | {
     outcome: "examined";
+    coverage: PageCapture["coverage"];
     consoleErrors: string[];
     failedRequests: FailedRequest[];
     pagePath: string;
@@ -70,19 +88,31 @@ export type ExaminePageResult = {
  * The construction deps of the eyes tool.
  *
  * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
- * serves every analysis. `chrome` configures the headless browser, and the sidecar that it names must mount
- * the workspace tree at the same path, because the tool navigates to a `file://` URL. `capture` is optional
- * and defaults to the shared capture, thus a test injects a seam that reads no browser.
+ * serves every analysis. `eyes` gives a browser for one look, and the scope of the acquire carries that
+ * analysis and its root. `chrome` carries the connection settings of the capture, and the browser that it
+ * names must hold the workspace tree at the same path, because the tool navigates to a `file://` URL.
+ * `capture` is optional and it replaces the whole transport, thus a test injects a seam that reads no
+ * browser.
  */
 export interface ExaminePageToolDeps {
     readonly gateway: ReportSessionStateGateway;
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     readonly chrome: ChromeConfig;
+    readonly eyes?: AcquireEyes;
     readonly capture?: CapturePage;
     readonly logger?: Logger;
+    /**
+     * The two budgets of one look, in milliseconds. A test seam: it shortens the budgets, thus a hung
+     * realization settles inside one test run. Absent, the tool reads {@link ACQUIRE_DEADLINE_MS} and
+     * {@link RELEASE_DEADLINE_MS}, which no composition tunes.
+     */
+    readonly deadlines?: {
+        readonly acquireMs?: number;
+        readonly releaseMs?: number;
+    };
 }
 /**
- * Make the eyes tool over the session-state gateway, the workspace-root seam, and the chrome config.
+ * Make the eyes tool over the session-state gateway, the workspace-root seam, and the eyes of the composition.
  *
  * The tool reads the thread id from the scope of the call, and it resolves the page path under the workspace
  * root. Thus one factory serves every thread. The tool holds no per-session value.

package/dist/tools/report-session/examine-page.js

@@ -9,68 +9,238 @@
  * page lives at `report-sessions/{threadId}/index.html` under the workspace root, which the preview writes.
  * A missed page means that no preview ran, and it is a typed outcome, not a throw.
  *
- * The `file://` URL resolves on the filesystem of the Chrome sidecar, because the connection is out of
- * process. Thus the sidecar must mount the workspace tree of the harness host at the same path. A sidecar
+ * The composition says where a browser comes from, and the eyes seam is that answer. One look acquires one
+ * lease, and the tool captures against the endpoint of that lease.
+ *
+ * The `file://` URL resolves on the filesystem of the browser, because the connection is out of process.
+ * Thus the browser of a lease must hold the workspace tree of the harness host at the same path. A browser
  * with no such mount reports the page as an unreachable request, and the tool gives back that fault.
  *
- * A composition that names no browser and injects no capture seam has no eyes at all. The tool reports that
- * condition once, up front, and it stamps nothing. A per-attempt capture failure would instead read as a
- * transient fault and invite a repeat of a call that can never pass.
+ * The tool releases the lease after the look. The release runs on a pass and on a failed capture alike. That
+ * release is hygiene, and it is not the guarantee against a leak. A process can die between the acquire and
+ * the release, thus the realization bounds the life of what it provisions. As a result a failed release
+ * changes no outcome, and the log is its whole record.
+ *
+ * A composition with no capture seam, no eyes seam, and no configured endpoint has no eyes at all. The tool
+ * reports that condition one time, up front, and it stamps nothing. A per-attempt capture failure would
+ * instead read as a transient fault, and it would invite a repeat of a call that can never pass.
  *
  * On a capture the tool copies the rendered hash onto the seen hash through the gateway. Thus the look
  * counts, and the record tool lets the current draft record. The copy takes the rendered hash and never the
- * current one, thus a later edit makes the look stale and the record refuses.
+ * current one, thus a later edit makes the look stale and the record refuses. A picture of the window alone
+ * is a true picture of the current document, thus it stamps the same and the coverage of the result is what
+ * tells the agent what it saw.
  *
  * The gateway reports whether a rendered hash existed to copy. When the row holds none, no preview stamped
  * one and the look cannot count. The tool then gives a missed-stamp outcome that directs a new preview,
  * because a repeated look never stamps a marker that no preview wrote.
  *
- * The chrome navigation and the workspace-root seam each speak the throw protocol. The tool runs the capture
- * inside a guard, thus a genuine fault becomes a typed outcome and a control-flow exception propagates.
+ * The eyes seam, the chrome navigation, and the workspace-root seam each speak the throw protocol. The tool
+ * guards each of them, thus a fault of a look becomes a typed outcome and the loop never sees a throw.
+ *
+ * A hang is not a throw, and a guard alone never ends one. Thus the acquire and the release each carry a
+ * deadline. A realization that hangs while it starts a browser would otherwise hold the whole agent turn,
+ * and no outcome would ever arrive.
  */
-import { ok } from "neverthrow";
+import { err, ok } from "neverthrow";
 import { access } from "node:fs/promises";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { z } from "zod";
 import { hasBrowserUrl } from "../../lib/chrome.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
+import { createStaticEyes } from "../../lib/eyes.js";
 import { defaultErrorFields } from "../../lib/logger.js";
 import { capturePage } from "../../lib/page-capture.js";
+import { reportSessionDir } from "../../workspace/paths.js";
 import { defineTool, withToolResultImage } from "../define-tool.js";
 import { openReportThread } from "../report-authoring/authoring-tools.js";
 /** The empty input. The tool examines the current page of the thread, thus it needs no field. */
 const examinePageInput = z.object({});
+/**
+ * Resolve the transport of the tool from its deps, one time.
+ *
+ * The precedence is `capture`, then `eyes`, then the chrome config as static eyes. An injected capture wins
+ * over the two others, because it replaces the whole transport and a test injects it.
+ *
+ * The chrome arm serves a direct construction alone, for example the tests of this file. The assembled
+ * runtime wraps the configured endpoint into the static realization at its composition root. Thus one wrap
+ * serves that runtime, and this arm never fires there.
+ */
+function resolveEyes(deps) {
+    if (deps.capture !== undefined) {
+        return { kind: "capture", capture: deps.capture };
+    }
+    if (deps.eyes !== undefined) {
+        return { kind: "lease", acquire: deps.eyes };
+    }
+    if (hasBrowserUrl(deps.chrome)) {
+        return { kind: "lease", acquire: createStaticEyes(deps.chrome) };
+    }
+    return { kind: "none" };
+}
+/** The log line of each stage. The outcome of the tool is one arm, thus the stage rides in the log alone. */
+const LOOK_FAULT_MESSAGE = {
+    acquire: "the eyes gave no browser for the look",
+    capture: "the page capture failed",
+};
+/**
+ * The deadline of one acquire, in milliseconds.
+ *
+ * A realization can start a container and boot a browser inside it, and that cold start costs seconds. The
+ * budget covers a slow cold start with a wide margin. It also ends a realization that hangs: one look sits
+ * inside one agent turn, and a hung acquire holds that whole turn with no outcome at all.
+ */
+const ACQUIRE_DEADLINE_MS = 60_000;
+/**
+ * The deadline of one release, in milliseconds.
+ *
+ * A release stops what one acquire started, and the look already holds its picture. Thus the budget is short.
+ * A release that runs past the budget costs nothing, because the realization bounds the life of what it
+ * provisions.
+ */
+const RELEASE_DEADLINE_MS = 10_000;
+/** The win of the timer arm. A symbol cannot collide with a value that the operation gives. */
+const EXPIRED = Symbol("expired");
+/**
+ * Run one operation against a deadline, and give the value, the cause, or the expiry.
+ *
+ * The eyes seam takes no abort signal, thus a race is the whole bound. The loser of the race stays in
+ * flight, and the caller of an expired operation owns whatever arrives late.
+ *
+ * Each path clears the timer. `sleep` of `async-utils.ts` holds a timer that nothing can clear. Thus an
+ * operation that wins its race would still keep the process alive for the rest of the budget.
+ */
+async function withDeadline(work, ms) {
+    let timer;
+    // The settled arm never rejects. Thus a fault that arrives after the expiry stays contained here, and it
+    // never reaches the process as an unhandled rejection.
+    const settled = work.then((value) => ok(value), (cause) => err({ kind: "threw", cause }));
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(EXPIRED), ms);
+    });
+    const winner = await Promise.race([settled, expiry]);
+    clearTimeout(timer);
+    return winner === EXPIRED ? err({ kind: "expired" }) : winner;
+}
+/** The cause of one such fault. An expiry names its budget, thus the detail of the outcome names it too. */
+function faultCause(fault, expiry, ms) {
+    return fault.kind === "threw" ? fault.cause : new Error(`${expiry} within ${ms} ms`);
+}
+/**
+ * Start one seam call, and give the promise of its outcome.
+ *
+ * A realization comes from the embedder, and one that is hand-written can throw before it gives its promise.
+ * The catch turns that throw into a rejection. Thus the deadline below reads one shape, and a look keeps the
+ * no-throw contract of the tool.
+ */
+function startSeamCall(call) {
+    try {
+        return call();
+    }
+    catch (cause) {
+        return Promise.reject(cause);
+    }
+}
+/**
+ * Release a lease that arrived after the deadline of its acquire.
+ *
+ * The acquire stays in flight past that deadline, thus a browser can still arrive with no owner. The
+ * realization bounds the life of that browser, and this release ends it sooner. The look already gave its
+ * outcome, thus a fault here reaches the log alone.
+ */
+function releaseLateLease(pending, logger) {
+    void pending
+        .then((lease) => lease.release())
+        .catch((cause) => {
+        logger.warn("the eyes lease did not release", logger.errorFields(cause));
+    });
+}
+/**
+ * Run one look over the resolved transport, and give the picture or the typed fault.
+ *
+ * The lease arm acquires one browser, captures against the endpoint of that lease, and releases in a
+ * `finally`. Thus a failed capture releases too. The shared capture takes a chrome config, thus the endpoint
+ * of the lease replaces the configured one and each other field of the composition stays.
+ *
+ * A failed release changes no outcome of the look. The capture already ran, and the realization bounds the
+ * life of what it provisions. Thus the log is the whole record of a failed release.
+ *
+ * The two seam calls each run against a deadline. An expired acquire reads as an acquire fault, thus a hung
+ * realization gives the same outcome as a refused one. An expired release reads as a failed release, thus it
+ * reaches the log and it changes no outcome.
+ */
+async function runLook(args) {
+    const { transport } = args;
+    if (transport.kind === "capture") {
+        try {
+            return ok(await transport.capture(args.url));
+        }
+        catch (cause) {
+            return err({ stage: "capture", cause });
+        }
+    }
+    // The pending acquire stays apart from its deadline. An expiry leaves the acquire in flight, and a lease
+    // that arrives late still gets a release.
+    const pending = startSeamCall(() => transport.acquire(args.scope));
+    const acquired = await withDeadline(pending, args.acquireMs);
+    if (acquired.isErr()) {
+        if (acquired.error.kind === "expired")
+            releaseLateLease(pending, args.logger);
+        return err({ stage: "acquire", cause: faultCause(acquired.error, "the eyes gave no browser", args.acquireMs) });
+    }
+    const lease = acquired.value;
+    try {
+        return ok(await capturePage({ ...args.chrome, browserUrl: lease.browserUrl }, args.url));
+    }
+    catch (cause) {
+        return err({ stage: "capture", cause });
+    }
+    finally {
+        const released = await withDeadline(startSeamCall(() => lease.release()), args.releaseMs);
+        if (released.isErr()) {
+            const cause = faultCause(released.error, "the eyes lease did not release", args.releaseMs);
+            args.logger.warn("the eyes lease did not release", args.logger.errorFields(cause));
+        }
+    }
+}
 /** The IANA media type of the screenshot. `page.screenshot` gives PNG bytes. */
 const SCREENSHOT_MEDIA_TYPE = "image/png";
 /** The line that the agent reads when the composition gives no browser. */
 const NO_BROWSER_DETAIL = "the composition gives no browser, thus this session cannot look at its page";
 /**
- * Make the eyes tool over the session-state gateway, the workspace-root seam, and the chrome config.
+ * Make the eyes tool over the session-state gateway, the workspace-root seam, and the eyes of the composition.
  *
  * The tool reads the thread id from the scope of the call, and it resolves the page path under the workspace
  * root. Thus one factory serves every thread. The tool holds no per-session value.
  */
 export function createExaminePageTool(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("examine-page");
-    // An injected seam is the eyes of a test. A named browser is the eyes of a deployment. With neither, the
-    // composition has no eyes, and that answer is fixed at construction.
-    const eyesAvailable = deps.capture !== undefined || hasBrowserUrl(deps.chrome);
-    const capture = deps.capture ?? ((url) => capturePage(deps.chrome, url));
+    // The eyes of the composition are fixed here, thus one look reads one resolved transport and never the
+    // precedence again.
+    const transport = resolveEyes(deps);
+    const acquireMs = deps.deadlines?.acquireMs ?? ACQUIRE_DEADLINE_MS;
+    const releaseMs = deps.deadlines?.releaseMs ?? RELEASE_DEADLINE_MS;
     return defineTool({
         id: "examine_page",
         description: "Open the rendered report page in a real headless browser, and report what you see. " +
-            "Give back a screenshot, the console errors, and the failed requests. " +
+            "Give back a screenshot, the coverage of that screenshot, the console errors, and the failed requests. " +
+            "The coverage says whether the picture holds the whole page, or the top window alone. " +
             "Run it after the preview to look at the current page, and to confirm that the layout and the charts read clean. " +
             "The report tool records a version only after you look at the current page. " +
             "If the page has no confirmed render, run the preview again first.",
         inputSchema: examinePageInput,
         executionMode: "inline",
         describeCall: "none",
+        // A look gives a picture, and a picture has no one-line form. Thus the outcome of the look is the
+        // whole line: a watcher reads that the eyes saw the page, or that the page was absent, or that the
+        // capture failed.
+        describeResult: (_input, result) => result.outcome,
         execute: async (_input, ctx) => {
             // The check runs before every read, thus one clear signal replaces a capture failure for each
-            // page. The arm stamps no seen hash, because no eyes saw the page.
-            if (!eyesAvailable) {
+            // page. The arm stamps no seen hash, because no eyes saw the page. It also narrows the transport
+            // for the look below, thus the acquire needs no assertion.
+            if (transport.kind === "none") {
                 logger.warn("the composition gives no browser, thus no look can run");
                 return ok({ outcome: "no-browser", detail: NO_BROWSER_DETAIL });
             }
@@ -87,7 +257,7 @@ export function createExaminePageTool(deps) {
                 logger.warn("the workspace root did not resolve", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: "the workspace root did not resolve" });
             }
-            const relativePagePath = join("report-sessions", threadId, "index.html");
+            const relativePagePath = join(reportSessionDir(threadId), "index.html");
             const pagePath = join(root, relativePagePath);
             try {
                 await access(pagePath);
@@ -100,14 +270,23 @@ export function createExaminePageTool(deps) {
                 logger.warn("the session page could not be read", { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: "the session page could not be read" });
             }
-            let captured;
-            try {
-                captured = await capture(pathToFileURL(pagePath).href);
-            }
-            catch (cause) {
-                logger.warn("the page capture failed", { threadId, analysisId, ...defaultErrorFields(cause) });
+            // The scope of the acquire carries the analysis and the root that this call resolved. Thus a
+            // realization that starts a browser mounts the same tree, and it holds no second resolver.
+            const looked = await runLook({
+                transport,
+                chrome: deps.chrome,
+                scope: { analysisId, workspaceRoot: root },
+                url: pathToFileURL(pagePath).href,
+                acquireMs,
+                releaseMs,
+                logger,
+            });
+            if (looked.isErr()) {
+                const { stage, cause } = looked.error;
+                logger.warn(LOOK_FAULT_MESSAGE[stage], { threadId, analysisId, ...defaultErrorFields(cause) });
                 return ok({ outcome: "capture-failed", detail: cause instanceof Error ? cause.message : String(cause) });
             }
+            const captured = looked.value;
             const stamped = await deps.gateway.stampSeen(threadId);
             if (stamped.outcome === "no-rendered") {
                 // The row holds no rendered hash, thus no preview stamped one and the look cannot count. A
@@ -127,6 +306,7 @@ export function createExaminePageTool(deps) {
             // JSON keeps the faults and the page path only, thus the JSON text holds no bytes.
             return ok(withToolResultImage({
                 outcome: "examined",
+                coverage: captured.coverage,
                 consoleErrors: captured.consoleErrors,
                 failedRequests: captured.failedRequests,
                 pagePath: relativePagePath,

package/dist/tools/report-session/index.d.ts

@@ -8,3 +8,5 @@
 export { createPreviewReportTool, type PreviewReportInput, type PreviewReportResult, type PreviewReportToolDeps, type ResolvePageAsset, } from "./preview-report.js";
 export { createExaminePageTool, type CapturePage, type ExaminePageInput, type ExaminePageResult, type ExaminePageToolDeps, type FailedRequest, type PageCapture, } from "./examine-page.js";
 export { createRecordVersionTool, type RecordVersionInput, type RecordVersionResult, type RecordVersionToolDeps } from "./record-version.js";
+export { createDeriveTableTool, type DeriveTableInput, type DeriveTableResult, type DeriveTableToolDeps } from "./derive-table.js";
+export { createListPinnedArtifactsTool, type ListPinnedArtifactsInput, type ListPinnedArtifactsResult, type ListPinnedArtifactsToolDeps, type PinnedArtifact, type PinnedCitation, } from "./list-artifacts.js";

package/dist/tools/report-session/index.js

@@ -8,3 +8,5 @@
 export { createPreviewReportTool, } from "./preview-report.js";
 export { createExaminePageTool, } from "./examine-page.js";
 export { createRecordVersionTool } from "./record-version.js";
+export { createDeriveTableTool } from "./derive-table.js";
+export { createListPinnedArtifactsTool, } from "./list-artifacts.js";

package/dist/tools/report-session/list-artifacts.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The pinned-artifact listing tool of a report session.
+ *
+ * The tool reads the frozen snapshot of the thread, and it gives the pinned set: the path, the content
+ * hash, the file type, and the header columns of a tabular artifact, plus the pinned citations with the
+ * short citation of each. Thus one call orients the agent, and a reference binds to a path or to a
+ * citation key of that set.
+ *
+ * The order is the code-unit order of the path. Two calls over one snapshot give one listing, thus the
+ * agent reads a stable set. A snapshot can pin many thousands of staged inputs, thus the listing stops at
+ * a cap and it carries the total count and a truncation marker.
+ *
+ * The columns come from a bounded header read of a listed entry. The path of a snapshot entry is
+ * untrusted, thus the read contains it with the one workspace-path resolver first. The extension gates
+ * the read, because a file type states a role and not a data format.
+ *
+ * An absent file, an unreadable file, and an unresolvable workspace root each give no columns and no
+ * error. Absence is a normal condition here: the listing is orientation, and the hash is the evidence.
+ */
+import { z } from "zod";
+import { type ResolveWorkspaceRoot } from "../../workspace/paths.js";
+import { type Logger } from "../../lib/logger.js";
+import { type Tool } from "../define-tool.js";
+import { type ReportSessionStateGateway, type SessionRefusal } from "../report-authoring/authoring-tools.js";
+/** The empty input. The tool lists the pinned set of the thread, thus it needs no field. */
+declare const listPinnedArtifactsInput: z.ZodObject<{}, z.core.$strip>;
+export type ListPinnedArtifactsInput = z.infer<typeof listPinnedArtifactsInput>;
+/**
+ * One pinned artifact of the listing.
+ *
+ * `fileType` states a role, and it does not state a data format. `columns` is present only for a header
+ * that the read recovered, thus an absent `columns` says nothing about the content of the file.
+ */
+export interface PinnedArtifact {
+    path: string;
+    hash: string;
+    fileType?: string;
+    columns?: string[];
+}
+/**
+ * One pinned citation of the listing: the key, and the short citation of its pinned record.
+ *
+ * `citation` names which paper the key is, thus the agent binds a citation block with no guess. A key that
+ * the pin recorded no citation for carries none, because absence is a normal condition. The description of
+ * the record stays out, because the listing is an orientation surface.
+ */
+export interface PinnedCitation {
+    key: string;
+    citation?: string;
+}
+/**
+ * The typed outcome of the listing tool. Each arm is ok-channel data, thus the tool never throws for one
+ * of them.
+ *
+ * `total` counts the whole pinned set, and `truncated` says that the set holds more entries than
+ * `artifacts` names. Thus the agent reads a partial listing as a partial listing.
+ *
+ * `citations` gives the pinned citations in the code-unit order of the keys that the pin stored. A citation
+ * reference binds to one of those keys, thus the agent reads a key here and never out of a refusal.
+ */
+export type ListPinnedArtifactsResult = {
+    outcome: "refused";
+    refusal: SessionRefusal;
+} | {
+    outcome: "listed";
+    artifacts: PinnedArtifact[];
+    total: number;
+    truncated: boolean;
+    citations: PinnedCitation[];
+};
+/**
+ * The construction deps of the listing tool.
+ *
+ * `resolveWorkspaceRoot` maps the analysis of the call onto its workspace root, thus one singleton tool
+ * serves every analysis and it resolves the root per call from the scope.
+ */
+export interface ListPinnedArtifactsToolDeps {
+    readonly gateway: ReportSessionStateGateway;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly logger?: Logger;
+}
+/**
+ * The header columns of a file on disk, or `undefined` when the file gives none.
+ *
+ * `path` decides whether the file carries a header at all, and `absolute` is where the bytes sit. The
+ * derivation tool reads the columns of its own output the same way, thus the two surfaces describe a table
+ * with one rule.
+ */
+export declare function readHeaderColumns(path: string, absolute: string): Promise<string[] | undefined>;
+/**
+ * Make the pinned-artifact listing tool over the session-state gateway.
+ *
+ * The tool reads the thread id from the scope of the call, and it loads the snapshot through the gateway.
+ * Thus one factory serves every thread, and the tool holds no per-session value.
+ */
+export declare function createListPinnedArtifactsTool(deps: ListPinnedArtifactsToolDeps): Tool<ListPinnedArtifactsInput, ListPinnedArtifactsResult>;
+export {};