@rackbops/docket-types 0.7.0 → 0.9.0

package/dist/research.d.ts

@@ -1,5 +1,6 @@
-import { type JobSpec } from "@rackbops/docket-core";
-import { type ResearchAnswer } from "./research-answer.js";
+import { type JobSpec, type TaskType } from "@rackbops/docket-core";
+import { type BlockedPage, type ResearchAnswer } from "./research-answer.js";
+import { type GatheredPage, type ReadSources } from "./research-sources.js";
 /**
  * Category 5 (plan section 1.2 row 5): "look into X and report back once". Execute lane, a `once`
  * schedule, tier 0 only. Two model runs per request, both `claude -p` Jobs the runner executes
@@ -16,6 +17,28 @@ import { type ResearchAnswer } from "./research-answer.js";
  * An optional `deadline` (plan 1.2 row 5) goes into the prompt; a research run that would start
  * after it makes no model call and tells the owner the deadline was missed.
  *
+ * With `sources: "sent"` (0.8.0, rackbops-bot-plugins#125), the request answers from pages the
+ * person's own browser gathered and the host stored (`research-sources.ts`): each run reads them
+ * through the host's `ReadSources` (`researchType({ readSources })`) and quotes them into its
+ * prompt, and neither run may fetch BoardGameGeek or eBay. When the run starts is the host's: it
+ * moves the run to now once the pages are in. A run that finds no usable page makes no model call
+ * and tells the owner so, and so does a host that cannot read them.
+ *
+ * **A second pass on pages the run could not open** (0.9.0): a research run lists in `blocked` the
+ * pages it needed and could not open (BoardGameGeek refuses the runner; eBay is never opened). When
+ * the reviewed answer passes, the research run's own draft lists any, the request is a `web` one,
+ * and the host can read gathered pages (`readSources`), the owner gets the answer now with a short
+ * "Couldn't open:" list. With at least `MIN_SOURCES_WAIT_MS` (an hour) before `sourcesExpiry` (14
+ * days, or 10 minutes before a sooner deadline), the DM also says a fuller pass is queued, and the
+ * task waits (`awaiting-pages`) on a follow-up at that expiry, so the wait sends nothing, runs
+ * nothing and charges nothing; with less, the task ends there. The findings are saved either way.
+ * The host's `ready` (README: the contract) moves the once task to now and deletes that follow-up.
+ * Then a second research run gets the pages and the earlier answer and returns only new or
+ * corrected findings; its reviewer checks them as an update to the earlier answer, against the
+ * pages, and the owner gets an "Update to" DM (one line when it adds nothing), its findings tagged
+ * `update` beside the first pass's. With no pages, past the deadline, or on a second-pass failure,
+ * the task ends with one short line: the first answer stands, uncharged when no run was made.
+ *
  * Failures (a usage limit never reaches `finish`: the dispatcher requeues the run):
  *
  * - `schema_miss`, a malformed answer, `timeout`, `error`: retried once in the same phase, at once.
@@ -36,14 +59,31 @@ export interface ResearchConfig {
     context?: string;
     /** When the person needs the answer by, an ISO-8601 instant; past it, nothing is run. */
     deadline?: string;
+    /**
+     * Where the pages come from: `web` (the default), the runs search and fetch them; `sent`, the
+     * person's own browser gathers them and the host stores them (`ReadSources`).
+     */
+    sources?: "web" | "sent";
 }
-export type ResearchPhase = "research" | "review" | "done";
+/** True when `config` asks for gathered pages. */
+export declare function usesSentSources(config: ResearchConfig): boolean;
+/**
+ * `awaiting-pages` (0.9.0): the first answer went out, and the task waits for gathered pages for a
+ * second pass; its run is the second pass's research run.
+ */
+export type ResearchPhase = "research" | "review" | "awaiting-pages" | "done";
 /** The current row: which run is next, how often it failed, and the draft once there is one. */
 export interface ResearchState {
     phase: ResearchPhase;
     /** Failed tries in the current phase. */
     failures: number;
     draft: ResearchAnswer | null;
+    /** Which pass (0.9.0): 2 once the second pass's research run has answered. Absent: the first. */
+    pass?: 1 | 2;
+    /** The pages the first pass could not open, as its research run listed them. */
+    blocked?: BlockedPage[];
+    /** The first pass's reviewed answer, as sent: what the second pass builds on. */
+    earlier?: ResearchAnswer;
 }
 export declare const MAX_QUESTION_CHARS = 1000;
 export declare const MAX_CONTEXT_CHARS = 2000;
@@ -70,7 +110,11 @@ export declare const RESEARCH_TIMEOUT_MS = 600000;
 export declare const REVIEW_MAX_TURNS = 8;
 export declare const REVIEW_MAX_BUDGET_USD = 0.5;
 export declare const REVIEW_TIMEOUT_MS = 300000;
-/** The state as stored, or a fresh one; a review phase with no readable draft starts over. */
+/**
+ * The state as stored, or a fresh one; a review phase with no readable draft starts over (in the
+ * second pass, from the wait for pages). A wait for pages with no readable earlier answer has
+ * nothing to build on, so it is done. A state stored before 0.9.0 reads as it did.
+ */
 export declare function researchState(value: unknown): ResearchState;
 /** The deadline as an instant, or null when there is none or it does not parse. */
 export declare function deadlineOf(config: ResearchConfig): Date | null;
@@ -79,9 +123,32 @@ export declare function deadlineOf(config: ResearchConfig): Date | null;
  * it or open anything that looks like markup; a JSON parser reads it back unchanged.
  */
 export declare function draftJson(draft: ResearchAnswer): string;
-/** The research run: the spike's prompt (docket-runner spike/cases.json, case `research`). */
-export declare function researchJob(config: ResearchConfig): JobSpec;
-/** The reviewer run: the question, and the draft as escaped JSON between markers. */
-export declare function reviewJob(config: ResearchConfig, draft: ResearchAnswer): JobSpec;
-export declare const research: import("@rackbops/docket-core").TaskType<ResearchConfig>;
+/**
+ * The research run: the spike's prompt (docket-runner spike/cases.json, case `research`), with the
+ * gathered pages when `pages` is given (`sources: "sent"`, or a second pass). With `earlier`, the
+ * second pass (0.9.0): the answer already sent goes in as escaped JSON between markers, and the
+ * run answers with only what the pages add or correct.
+ */
+export declare function researchJob(config: ResearchConfig, pages?: readonly GatheredPage[], earlier?: ResearchAnswer): JobSpec;
+/**
+ * The reviewer run: the question, and the draft as escaped JSON between markers; with `pages`
+ * (`sources: "sent"`), the same gathered pages the research run had, to check its claims against.
+ */
+export declare function reviewJob(config: ResearchConfig, draft: ResearchAnswer, pages?: readonly GatheredPage[], earlier?: ResearchAnswer): JobSpec;
+/**
+ * The shortest wait for pages worth starting (0.9.0): with less than this before the expiry, a
+ * person has no real chance to gather pages, so the answer goes out as it is.
+ */
+export declare const MIN_SOURCES_WAIT_MS = 3600000;
+export interface ResearchOptions {
+    /** The host's store of gathered pages; without it, a `sources: "sent"` request is not run. */
+    readSources?: ReadSources;
+}
+/**
+ * The research type over a host's options: `research` itself has none, so it runs `web` requests
+ * only and tells the owner a `sent` one cannot be run here.
+ */
+export declare function researchType(options?: ResearchOptions): TaskType<ResearchConfig>;
+/** The research type with no host options: `web` requests only. */
+export declare const research: TaskType<ResearchConfig>;
 //# sourceMappingURL=research.d.ts.map

package/dist/research.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../src/research.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,OAAO,EAIb,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAOL,KAAK,cAAc,EAEpB,MAAM,sBAAsB,CAAA;AAE7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAA;AAE1D,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,aAAa,CAAA;IACpB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,cAAc,GAAG,IAAI,CAAA;CAC7B;AAED,eAAO,MAAM,kBAAkB,OAAO,CAAA;AACtC,eAAO,MAAM,iBAAiB,OAAO,CAAA;AACrC,iDAAiD;AACjD,eAAO,MAAM,SAAS,IAAI,CAAA;AAC1B,2DAA2D;AAC3D,eAAO,MAAM,aAAa,UAAY,CAAA;AAEtC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAA;AACpC,eAAO,MAAM,uBAAuB,IAAI,CAAA;AACxC,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,SAAU,CAAA;AAC1C;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAA;AACjC,eAAO,MAAM,qBAAqB,MAAM,CAAA;AACxC,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAYxC,8FAA8F;AAC9F,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa,CAU3D;AAQD,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAI9D;AAWD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEvD;AAED,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAyB3D;AAED,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAoChF;AAyHD,eAAO,MAAM,QAAQ,0DA4CnB,CAAA"}
+{"version":3,"file":"research.d.ts","sourceRoot":"","sources":["../src/research.ts"],"names":[],"mappings":"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"}