productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/researchGate.d.ts

@@ -0,0 +1,86 @@
+import type { DenialText } from "./harnessGates.js";
+/** A PreToolUse-shaped payload. Harness-neutral: only these two fields are read. */
+export interface ToolCall {
+    readonly tool_name?: string;
+    readonly tool_input?: Record<string, unknown>;
+}
+export interface GateDecision {
+    readonly allow: boolean;
+    /**
+     * Present when allow=false. Two readers, two texts: `agent` carries the instruction and
+     * the machinery, `user` is the one line the human sees. See DenialText in harnessGates.ts.
+     */
+    readonly reason?: DenialText;
+    /** Why the gate let this through — for tests and `--json`, never for the agent. */
+    readonly note?: string;
+}
+export declare function isHarnessEnvelope(prompt: string): boolean;
+export declare function researchRequestTopic(prompt: string): string | null;
+/**
+ * Is this call a fan-out to the web for findings?
+ *
+ * Both signals are required. "Spawn a subagent to grep for callers of parseSpec"
+ * has delegation but no web. "WebSearch for the current tsc flag" has web but no
+ * delegation. Neither is research; neither is gated.
+ */
+export declare function isFanOutResearch(call: ToolCall): boolean;
+/**
+ * Is this fan-out one that a live `foo research` run actually planned?
+ *
+ * `foo research` plans the fan-out itself (source classes, page budget, panel) and the agent
+ * executes it by spawning subagents — so without an exemption the gate would block the very
+ * command it routes to.
+ *
+ * The exemption used to be time-only: any `foo research` run held the door open for TWO HOURS,
+ * for ANY topic. It stored the topic and never read it. So one governed run on one subject
+ * bought two hours of ungoverned research on every other subject — which is exactly how a
+ * vendor-docs sweep for an unrelated spec walked straight through a boundary that was working
+ * as designed.
+ *
+ * Now the exemption is CONSUMED. A run authorizes the lanes it planned; each fan-out spends
+ * one; when they are gone the gate closes, whatever the clock says. The TTL stays as a
+ * backstop for the run that is abandoned half-executed.
+ */
+export declare function researchActive(root: string, now?: number): boolean;
+/** True when a run is live but has spent every lane it planned. Earns its own message. */
+export declare function researchLanesSpent(root: string, now?: number): boolean;
+/** Spend one authorized lane. Called when the gate lets a fan-out through on a live run. */
+export declare function consumeResearchLane(root: string): void;
+export interface RunReceipt {
+    readonly run_id: string;
+    readonly topic: string;
+    readonly at: number;
+}
+/** Called by `foo research` when it plans a run. The paper must carry the id it returns. */
+export declare function mintResearchRun(root: string, topic: string, now?: number): RunReceipt;
+/** Does this paper's claimed run actually exist? A forged id has no receipt on disk.
+ * Checks the published (tracked) store first, then the working `.foo/` store, so a receipt
+ * resolves whether it shipped with the repo or was minted here. The `/^r-.../` guard also
+ * stops an id from escaping the dir. */
+export declare function verifyResearchRun(root: string, id: string): RunReceipt | null;
+/** Publish a working-store receipt into the tracked store so its proof travels with the
+ * committed paper. Idempotent. Returns what it did so the caller can speak plainly. */
+export declare function sealResearchRun(root: string, id: string): "sealed" | "already-sealed" | "no-receipt";
+/** Pull the run id a paper claims. Absent = the paper was not produced by a governed run. */
+export declare function paperRunId(paperText: string): string | null;
+/** Called by `foo research` when it hands the agent a research contract to execute. */
+export declare function markResearchActive(root: string, topic: string, now?: number, lanes?: number): void;
+/** Record one web read. Called when the gate lets a lookup through. */
+export declare function recordWebRead(root: string, now?: number): void;
+/** Cleared when a governed run starts — its own reading must not trip its own gate. */
+export declare function clearWebReads(root: string): void;
+/** Has the agent read the web enough times that this is plainly research, unnamed? */
+export declare function webReadsLookLikeResearch(root: string, now?: number): boolean;
+export declare function markResearchRequested(root: string, topic: string, now?: number): void;
+export declare function clearResearchRequest(root: string): void;
+/** A research ask is on the table and `foo research` has not been run for it yet. */
+export declare function researchRequested(root: string, now?: number): string | null;
+/**
+ * The whole policy. Pure except for the marker read, so it is testable and any harness
+ * adapter can call it.
+ *
+ * Note the order: `researchLanesSpent` is checked before the generic deny, so an agent that
+ * over-fans-out inside a real run is told THAT, rather than being told to run the command it
+ * is already executing.
+ */
+export declare function evaluateResearchGate(call: ToolCall, root: string, env?: NodeJS.ProcessEnv): GateDecision;