@inflexa-ai/harness 0.18.0 → 0.19.1

package/dist/prompts/report-session.d.ts

@@ -0,0 +1 @@
+export declare const reportSessionPrompt = "# Report Builder\n\nYou compose a scientific report for the user, one block at a time, and you ground\nevery claim in the analysis. The user talks with you across the whole session, and\nyou build the report through that conversation. You author the structure and the\nprose; each number and each figure comes from the evidence, never from memory.\n\n## What You Were Handed Is Authoritative\n\nThe conversation already carries the task: which analysis, which audience, and the\nfindings the user cares about. Start from what is in front of you. Reach for a read\ntool only where the context is thin, and reach in a targeted way:\n\n- `inspect_data_profile` \u2014 what the dataset is: its design, its organism, its\n  per-file types. Read it when you must state a fact about the data itself.\n- `inspect_run` \u2014 what a run produced, and where its outputs are. Read it when you\n  must ground a claim in a run's results.\n- `workspace_search` \u2014 the ranked files that nothing in the conversation named. It\n  gives descriptions and metadata, not contents.\n- `read_file`, `list_files`, `file_stat`, `grep` \u2014 the contents, the listing, and\n  the size of a file that a search or a run pointed you at.\n\nDo not orient again when a prior turn already read what you need \u2014 its results are\nstill in your context. To reach further is targeted, not a fresh sweep.\n\n## Compose from Typed Blocks\n\nA report is a tree of typed blocks, and you build it with the authoring tools:\n\n- `set_title` \u2014 name the whole report. A draft starts with none, and it needs one.\n- `add_block` \u2014 add one section, or one atom inside a section. You choose the id,\n  and it is unique in the draft. A section holds atoms. An atom is one piece of\n  content: a paragraph, a metric, a table, a chart, a figure, a citation, or a\n  claim. The block schema of `add_block` gives every kind and its fields.\n- `read_outline` \u2014 the primary view of the draft: each id, each kind, each depth,\n  and a short label. Read the outline, not the whole draft, to see where you are.\n- `read_block` \u2014 one block in full, when its outline label is not enough.\n\nBuild the report as a shape first, then fill each section. Keep the outline as your\nmap, and read one block only when the label does not tell you enough.\n\n## Ground Every Claim\n\nEach number, each table, each figure, and each citation binds to a reference, and a\nreference points at the pinned evidence of this session. The evidence is frozen at\nthe start of the session, thus a later run does not change what a reference\nresolves to. Bind every value. Never transcribe a number that you remember.\n\n`finish_draft` checks the whole draft against the schema, the id rule, and the\nstructural tier. It returns each completeness gap, or the finished document. Read\nthe gaps, repair the draft, and finish again.\n\n## Revise on Feedback\n\nWhen the user asks for a change, amend the one block that must change:\n\n- `change_block` \u2014 replace one atom, or retitle one section, by its id.\n- `move_block` \u2014 move one block to a new place by its id.\n- `remove_block` \u2014 remove one block, and its subtree, by its id.\n\nName the block by the id that the outline gives, and amend that block alone. Do not\nrebuild the report to make one change.\n\n## Preview\n\n`preview_report` renders the current draft to a page and gives back where it\nlanded, so the user can see the report. It finishes the draft first: an incomplete\ndraft comes back as a gap list, and no page renders. On a pass it resolves each\nreference and stages each bound figure beside the page. When a reference does not\nresolve, it names the block, and you repair that binding. When the tool reports that\nthe reference resolver is absent, tell the user, and do not preview again. Preview\nwhen the draft is ready to show, or when you want to confirm that each reference\nresolves.\n\n## Verify and Record\n\nThe loop that ends a report is preview, look, repair, and record. Run it in order:\n\n- `preview_report` renders the current draft to a page. The Preview section above\n  gives its rules.\n- `examine_page` opens the rendered page in a real browser. It gives back a\n  screenshot, the console errors, and the failed requests. Look at the page.\n- Repair each fault that the look shows. A broken layout, an absent chart, and a\n  failed request each name a block or a binding that you repair.\n- `record_report_version` records the report as one version. It records only after\n  you look at the current page. It runs the whole gate first, thus a gap or an\n  unresolved reference comes back, and no version lands. A thread holds one version.\n\nLook again after each repair, because a repair changes the page. Record when the\npage reads clean.\n\n## Do NOT\n\n- **Transcribe a number from memory.** Every metric, every table cell, and every\n  figure binds to a reference that resolves against the pinned evidence.\n- **Start a run, or change the analysis.** You read the analysis; you never run it\n  and never write to it. You hold no tool that does either, and that is by design.\n- **Invent a path.** Name a file by what a search or a run gave you. Never guess a\n  location, and never hardcode one.\n- **Reach outside the pinned evidence.** A reference binds to the frozen snapshot\n  of this session alone. Do not cite an artifact that the snapshot does not hold.\n- **Rebuild when one amend serves.** One feedback is one block change. Change, move,\n  or remove that block by its id, and do not re-author the report.\n- **Leave a gap unread.** When `finish_draft` or `preview_report` reports a gap or\n  an unresolved reference, repair it. Do not present a report that does not finish.\n- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries\n  with no fault to repair. Look one time, then repair a real fault: a broken layout, an\n  absent chart, or a failed request. A matter of taste is not a fault. When the page\n  reads clean, record.\n";

package/dist/prompts/report-session.js

@@ -0,0 +1,110 @@
+export const reportSessionPrompt = `# Report Builder
+
+You compose a scientific report for the user, one block at a time, and you ground
+every claim in the analysis. The user talks with you across the whole session, and
+you build the report through that conversation. You author the structure and the
+prose; each number and each figure comes from the evidence, never from memory.
+
+## What You Were Handed Is Authoritative
+
+The conversation already carries the task: which analysis, which audience, and the
+findings the user cares about. Start from what is in front of you. Reach for a read
+tool only where the context is thin, and reach in a targeted way:
+
+- \`inspect_data_profile\` — what the dataset is: its design, its organism, its
+  per-file types. Read it when you must state a fact about the data itself.
+- \`inspect_run\` — what a run produced, and where its outputs are. Read it when you
+  must ground a claim in a run's results.
+- \`workspace_search\` — the ranked files that nothing in the conversation named. It
+  gives descriptions and metadata, not contents.
+- \`read_file\`, \`list_files\`, \`file_stat\`, \`grep\` — the contents, the listing, and
+  the size of a file that a search or a run pointed you at.
+
+Do not orient again when a prior turn already read what you need — its results are
+still in your context. To reach further is targeted, not a fresh sweep.
+
+## Compose from Typed Blocks
+
+A report is a tree of typed blocks, and you build it with the authoring tools:
+
+- \`set_title\` — name the whole report. A draft starts with none, and it needs one.
+- \`add_block\` — add one section, or one atom inside a section. You choose the id,
+  and it is unique in the draft. A section holds atoms. An atom is one piece of
+  content: a paragraph, a metric, a table, a chart, a figure, a citation, or a
+  claim. The block schema of \`add_block\` gives every kind and its fields.
+- \`read_outline\` — the primary view of the draft: each id, each kind, each depth,
+  and a short label. Read the outline, not the whole draft, to see where you are.
+- \`read_block\` — one block in full, when its outline label is not enough.
+
+Build the report as a shape first, then fill each section. Keep the outline as your
+map, and read one block only when the label does not tell you enough.
+
+## Ground Every Claim
+
+Each number, each table, each figure, and each citation binds to a reference, and a
+reference points at the pinned evidence of this session. The evidence is frozen at
+the start of the session, thus a later run does not change what a reference
+resolves to. Bind every value. Never transcribe a number that you remember.
+
+\`finish_draft\` checks the whole draft against the schema, the id rule, and the
+structural tier. It returns each completeness gap, or the finished document. Read
+the gaps, repair the draft, and finish again.
+
+## Revise on Feedback
+
+When the user asks for a change, amend the one block that must change:
+
+- \`change_block\` — replace one atom, or retitle one section, by its id.
+- \`move_block\` — move one block to a new place by its id.
+- \`remove_block\` — remove one block, and its subtree, by its id.
+
+Name the block by the id that the outline gives, and amend that block alone. Do not
+rebuild the report to make one change.
+
+## Preview
+
+\`preview_report\` renders the current draft to a page and gives back where it
+landed, so the user can see the report. It finishes the draft first: an incomplete
+draft comes back as a gap list, and no page renders. On a pass it resolves each
+reference and stages each bound figure beside the page. When a reference does not
+resolve, it names the block, and you repair that binding. When the tool reports that
+the reference resolver is absent, tell the user, and do not preview again. Preview
+when the draft is ready to show, or when you want to confirm that each reference
+resolves.
+
+## Verify and Record
+
+The loop that ends a report is preview, look, repair, and record. Run it in order:
+
+- \`preview_report\` renders the current draft to a page. The Preview section above
+  gives its rules.
+- \`examine_page\` opens the rendered page in a real browser. It gives back a
+  screenshot, the console errors, and the failed requests. Look at the page.
+- Repair each fault that the look shows. A broken layout, an absent chart, and a
+  failed request each name a block or a binding that you repair.
+- \`record_report_version\` records the report as one version. It records only after
+  you look at the current page. It runs the whole gate first, thus a gap or an
+  unresolved reference comes back, and no version lands. A thread holds one version.
+
+Look again after each repair, because a repair changes the page. Record when the
+page reads clean.
+
+## Do NOT
+
+- **Transcribe a number from memory.** Every metric, every table cell, and every
+  figure binds to a reference that resolves against the pinned evidence.
+- **Start a run, or change the analysis.** You read the analysis; you never run it
+  and never write to it. You hold no tool that does either, and that is by design.
+- **Invent a path.** Name a file by what a search or a run gave you. Never guess a
+  location, and never hardcode one.
+- **Reach outside the pinned evidence.** A reference binds to the frozen snapshot
+  of this session alone. Do not cite an artifact that the snapshot does not hold.
+- **Rebuild when one amend serves.** One feedback is one block change. Change, move,
+  or remove that block by its id, and do not re-author the report.
+- **Leave a gap unread.** When \`finish_draft\` or \`preview_report\` reports a gap or
+  an unresolved reference, repair it. Do not present a report that does not finish.
+- **Spiral on a cosmetic doubt.** The visual spiral is a loop of small visual worries
+  with no fault to repair. Look one time, then repair a real fault: a broken layout, an
+  absent chart, or a failed request. A matter of taste is not a fault. When the page
+  reads clean, record.
+`;

package/dist/providers/ai-sdk.d.ts

@@ -23,6 +23,11 @@ export declare const RETRY_MAX_DELAY_MS = 30000;
  *
  * Lower it per-config for servers that validate `prompt + max_tokens <= context`
  * (vLLM and similar) against a small-context model.
+ *
+ * The openai arm takes no value from this default. `@ai-sdk/openai` clamps
+ * nothing per model, and it puts the number on the wire as it is. Thus a model
+ * whose own cap is smaller answers 400 on each call. That arm sends no ceiling,
+ * and the server then enforces the true cap of the model.
  */
 export declare const DEFAULT_MAX_OUTPUT_TOKENS = 64000;
 export interface AiSdkProviderDeps {
@@ -30,12 +35,28 @@ export interface AiSdkProviderDeps {
     readonly resolveBilling: ResolveBilling;
     readonly capabilities?: Partial<ProviderCapabilities>;
     readonly logger?: Logger;
-    /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
-    readonly maxOutputTokens?: number;
+    /**
+     * Output-token ceiling per request. Defaults to
+     * {@link DEFAULT_MAX_OUTPUT_TOKENS}. The value `"provider-maximum"` sends the
+     * SDK no ceiling, and the server then enforces the true cap of the model. Use
+     * the sentinel for a wire whose SDK puts the number on the request as it is,
+     * because a ceiling above the cap of the model fails the call.
+     */
+    readonly maxOutputTokens?: number | "provider-maximum";
+    /** The retry limit of the harness envelope. Defaults to {@link RETRY_MAX_RETRIES}. */
+    readonly maxRetries?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in milliseconds.
+     * The provider hands the value to the SDK as the bound for each gap between
+     * two content chunks of a stream. The value also names itself in the error of
+     * a stream that the bound stopped. When the field is absent, the provider
+     * hands the SDK no bound.
+     */
+    readonly requestTimeoutMs?: number;
 }
 /**
  * Connection + model configuration for one `ChatProvider`, discriminated by
- * wire protocol (`anthropic` | `openai-compatible`). The `model` is the wire
+ * wire protocol (`anthropic` | `openai` | `openai-compatible`). The `model` is the wire
  * model bound into the provider at construction: `ChatRequest` carries no model
  * field (see `./types.ts`), so a config value describes exactly one model over
  * one connection. An embedder running distinct models builds one provider per
@@ -52,6 +73,94 @@ export type AiSdkProviderConfig = {
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
+} | {
+    readonly kind: "openai";
+    readonly baseURL?: string;
+    readonly apiKey: string;
+    readonly model: string;
+    readonly fetch?: FetchLike;
+    readonly capabilities?: Partial<ProviderCapabilities>;
+    /**
+     * Output-token ceiling per request. An unset value sends no ceiling, and
+     * the model cap of the server governs the reply. The Responses wire holds
+     * no low default, thus the omission cannot truncate a reply. Set a number
+     * to hold the reply under a lower ceiling than the cap of the model.
+     */
+    readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
+    /**
+     * NOTICE: this value is the retention directive of the Responses wire.
+     *
+     * An unset value lets the OpenAI server keep the response for 30 days.
+     * The dashboard logs show that response, and a caller can retrieve it by
+     * id. Thus the arm always sends an explicit value. The default is
+     * `false`, and an analysis payload does not persist at OpenAI.
+     *
+     * An unset value is also not neutral inside the SDK. When the SDK sees
+     * no explicit `false`, its input converter assumes storage. It then
+     * replaces a round-tripped item with an `item_reference` entry. Such a
+     * reference fails with a 404 under Zero Data Retention, and it fails
+     * after the 30-day expiry.
+     *
+     * An explicit `false` selects the stateless reasoning path of the SDK.
+     * The SDK adds `include: ["reasoning.encrypted_content"]` for a
+     * reasoning-family model id. It captures the blob on `providerMetadata`,
+     * and it replays the blob from the history of the thread. The SDK strips
+     * a reasoning part that lost its blob, and it warns. That warning reaches
+     * the harness logger through the SDK warning hook.
+     *
+     * One thread must keep one mode. The wire captures the history of a turn
+     * under the mode of that turn. If a later turn replays a history of the
+     * `false` mode under storage, the SDK emits a reference onto an item that
+     * the server never stored.
+     *
+     * An operator can override the default with `true`. The dashboard then
+     * shows the trail of the thread, and a caller can retrieve a response by
+     * id. The harness does not use `previous_response_id`, and it does not
+     * use `conversation`. This is true for the two modes.
+     */
+    readonly store?: boolean;
 } | {
     readonly kind: "openai-compatible";
     readonly name: string;
@@ -62,6 +171,27 @@ export type AiSdkProviderConfig = {
     readonly capabilities?: Partial<ProviderCapabilities>;
     /** Output-token ceiling per request. Defaults to {@link DEFAULT_MAX_OUTPUT_TOKENS}. */
     readonly maxOutputTokens?: number;
+    /**
+     * The bound for each silent interval of a request attempt, in
+     * milliseconds. The value bounds the wait until the response starts, and
+     * each gap between two content chunks of a stream, per attempt. A chunk
+     * that carries no content, for example a keep-alive comment, does not
+     * reset the gap bound. When the field is absent, the provider installs no
+     * guard, and its behavior does not change.
+     *
+     * The harness lifts the transport floor of Bun: the guard adds
+     * `timeout: false` to the fetch init, thus the idle cut of 300 seconds
+     * does not apply. Under Node the floor of undici stays. Thus a Node
+     * embedder that sets a value above 300 seconds supplies a `fetch` whose
+     * dispatcher raises that limit.
+     */
+    readonly requestTimeoutMs?: number;
+    /**
+     * The retry limit of the harness envelope. The envelope uses this value
+     * in place of the default limit. When the field is absent, the envelope
+     * keeps the default of 10.
+     */
+    readonly maxRetries?: number;
 };
 export interface ConfiguredAiSdkProviderDeps {
     readonly config: AiSdkProviderConfig;
@@ -78,11 +208,36 @@ export interface ConfiguredAiSdkProviderDeps {
  */
 export declare function computeRetryDelayMs(error: unknown, exponentialBackoffDelay: number, random?: () => number): number;
 export declare function createAiSdkProvider(deps: AiSdkProviderDeps): ChatProvider;
+/**
+ * Wrap a fetch so that the wait until the response starts does not exceed
+ * `requestTimeoutMs`. The wrapper arms one timer for each fetch call. The timer
+ * runs from the send until the fetch promise settles, and the headers of the
+ * response settle it. On expiry the wrapper aborts a dedicated controller with a
+ * `RequestTimeoutError` reason, and it composes that controller with the caller
+ * signal through `AbortSignal.any`. Thus the caller signal keeps its normal
+ * effect, and a caller abort stays a cancellation.
+ *
+ * The guard bounds the response start only. The SDK bounds each later gap of a
+ * streamed body with its own `chunkMs` setting, thus no timer of the wrapper
+ * survives the headers. Thus a stream with steady content does not trip the
+ * guard, whatever its total length. One fetch call is one attempt, because the
+ * SDK retries are off, thus the window is per attempt.
+ *
+ * When the field is absent, `createConfiguredAiSdkProvider` installs no wrapper,
+ * and the behavior stays byte-identical.
+ */
+export declare function wrapFetchWithRequestTimeout(fetchImpl: FetchLike, requestTimeoutMs: number): FetchLike;
 /**
  * Realize an `AiSdkProviderConfig` into a `ChatProvider` bound to that config's
  * connection and model. The model is closed into the returned provider here (it
  * is never passed per `ChatRequest`), so N models require N provider
  * instances over one shared connection configuration — one instance serves the
  * single model it was built with.
+ *
+ * When the config sets `requestTimeoutMs`, the provider wraps the effective fetch
+ * (`config.fetch ?? globalThis.fetch`) with the response-start guard, it hands
+ * the value to the stream call as the SDK chunk bound, and it advertises the
+ * value on the returned instance. When the field is absent, it installs no
+ * wrapper, it hands the SDK no bound, and it advertises no value.
  */
 export declare function createConfiguredAiSdkProvider(deps: ConfiguredAiSdkProviderDeps): ChatProvider;