@actor0/harness 0.0.0-stage → 0.5.2

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./answer-filter.js";
+export * from "./tool-call-block.js";
+export * from "./harness.js";
+export * from "./model-client.js";
+export * from "./plan-prefix.js";
+export * from "./protocol.js";
+export * from "./reasoning-summary.js";
+export * from "./tool-host.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from "./answer-filter.js";
+export * from "./tool-call-block.js";
+export * from "./harness.js";
+export * from "./model-client.js";
+export * from "./plan-prefix.js";
+export * from "./protocol.js";
+export * from "./reasoning-summary.js";
+export * from "./tool-host.js";
+export * from "./types.js";

package/dist/model-client.d.ts

@@ -0,0 +1,165 @@
+import type { ChatMessage, ModelClient, ModelEvent, ToolDefinition } from "./types.js";
+export declare class ModelTransportError extends Error {
+    readonly retriable: boolean;
+    readonly retryAfterMs?: number | undefined;
+    /**
+     * @param retryAfterMs how long the server asked us to wait, when it said.
+     *   A retriable error that carries one has a floor under its next attempt:
+     *   see `retryDelay` in harness.ts.
+     */
+    constructor(message: string, retriable?: boolean, retryAfterMs?: number | undefined);
+}
+/**
+ * The longest server-requested wait this harness will sit through.
+ *
+ * A windowed rate limit can name a reset twenty minutes out. Honouring that
+ * in a terminal means the turn disappears for twenty minutes with nothing on
+ * screen, which the user reads as a hang; ignoring it means the retries land
+ * inside the window and the turn fails having proved nothing. So the wait is
+ * honoured up to here, and past it the failure is surfaced instead, with the
+ * time the limit lifts in the message the user reads.
+ */
+export declare const MAX_HONOURED_RETRY_AFTER_MS = 120000;
+/**
+ * How long the server asked us to wait, in milliseconds.
+ *
+ * `Retry-After` is a count of seconds per RFC 9110, and an HTTP-date in the
+ * dialect several providers actually send. Both are honoured; a value that is
+ * neither is ignored rather than guessed at, because a misread directive is
+ * worse than no directive.
+ */
+export declare function retryAfterMs(headers: Headers, now?: number): number | undefined;
+export type OpenAiCompatibleOptions = {
+    baseUrl: string;
+    apiKey?: string;
+    model: string;
+    fetchImpl?: typeof fetch;
+    headers?: Record<string, string>;
+    /**
+     * Override the request path. Defaults to `/chat/completions` appended to
+     * `baseUrl`. Gateways and application proxies routinely expose an
+     * OpenAI-shaped endpoint somewhere else — `/api/chat`, a tunnel, a route
+     * that also serves HTML — and forcing every one of them to sit at
+     * `baseUrl + /chat/completions` would be a transport limitation leaking
+     * into every host that has to work around it.
+     */
+    path?: string;
+    /**
+     * Reasoning effort for models that support it (o-series and reasoning
+     * models). Sent as `reasoning_effort`; omitted entirely when unset, so a
+     * non-reasoning endpoint never sees an unknown field.
+     */
+    reasoningEffort?: "low" | "medium" | "high";
+};
+export declare class OpenAiCompatibleModel implements ModelClient {
+    private readonly endpoint;
+    private readonly apiKey?;
+    private readonly model;
+    private readonly fetchImpl;
+    private readonly headers;
+    private readonly reasoningEffort?;
+    constructor(options: OpenAiCompatibleOptions);
+    stream(messages: ChatMessage[], tools: ToolDefinition[], signal: AbortSignal): AsyncIterable<ModelEvent>;
+}
+/**
+ * True when a response is an HTML document rather than a stream or a JSON
+ * error. Gateways, edge runtimes and bot checks all answer this way, and none
+ * of them say so in the body: the caller has to read the shape.
+ */
+export declare function looksLikeHtml(contentType: string | null, body: string | null): boolean; /** True when the response claims to be the event stream we asked for. */
+/**
+ * Whether an error delivered *inside* a 200 response can be fixed by asking
+ * again.
+ *
+ * A 200 means the request was accepted, so the status classification above
+ * never runs — there is no status left to read. Everything then arrives in
+ * one shape, `data: {"error": {...}}`: a dropped upstream connection, a rate
+ * limit, a rejected key, a request that does not fit the context window.
+ * Calling all of them retriable, which is what this did, replays a
+ * deterministic failure three times with 1s/2s/4s of backoff, at four times the
+ * token cost, and ends in exactly the same error.
+ *
+ * Code and type are read first because they are exact, and because they are
+ * the part OpenAI, Anthropic, Gemini and OpenRouter all agree on. The message
+ * is the fallback for the servers that send neither. An unrecognised error
+ * stays retriable: a stream that died mid-flight is far more often a dropped
+ * connection than a request the server will never accept, and guessing wrong
+ * in that direction costs one wasted attempt, while guessing wrong the other
+ * way refuses to start the turn at all.
+ */
+export declare function isRetriableStreamError(message: string, code?: string, type?: string): boolean;
+/**
+ * Is this failure the conversation not fitting the model?
+ *
+ * Named because it is the one transport failure with a real recovery, and
+ * recovery is not the transport layer's job: the caller has to shorten the
+ * history and ask again, which is a decision about the conversation.
+ */
+export declare function isContextOverflow(message: string): boolean;
+/**
+ * Is this thrown value the model saying the request is too big?
+ *
+ * Asked of the error rather than of the message so a host does not have to
+ * know which layer raised it, or re-derive that a retriable failure of the
+ * same shape must not be compacted around. Both spellings land here: a 400
+ * whose body is the diagnosis, and an error frame inside a 200.
+ */
+/**
+ * A request the endpoint will never accept, however often it is
+ * sent — the one transport failure with a host-level recovery
+ * (compact the history and ask again), which is why this is a
+ * classifier and not just a message match.
+ *
+ * It also looks through a `FailedTurnError`: a turn that failed
+ * mid-flight wraps the transport error that ended it (see
+ * `failedTurn`), and without the unwrap every such failure reads
+ * as an unknown error, so the recovery never fires and a turn the
+ * endpoint merely refused rewinds the session instead of being
+ * asked again. That makes the return a plain boolean rather than
+ * a type predicate — in the wrapped case the error is a
+ * `FailedTurnError`, not the `ModelTransportError` the old
+ * signature claimed — and its one caller reads it as a gate.
+ */
+export declare function isContextOverflowError(error: unknown): boolean;
+/**
+ * The context window the endpoint said it has, in tokens, or undefined.
+ *
+ * The overflow message is not only a diagnosis, it is the one measurement of
+ * the limit the provider will ever volunteer, and reading it as a boolean
+ * throws the number away. A host recovering from an overflow has to decide
+ * how much history to keep, and a guess cannot be smaller than the truth: on
+ * a 4k-window model a recovery that targets 8,000 tokens does not fit by
+ * construction, and the one replay it is allowed fails exactly like the
+ * request it was meant to fix.
+ *
+ * Anchored on the number *and* the word "token" on purpose. The messages that
+ * carry a limit also carry the count that broke it — "your messages resulted
+ * in 91234 tokens" — and a looser pattern reads the wrong number, which is
+ * worse than reading none. A per-message char limit is not a window and is
+ * not returned for one; `OVERFLOW_TEXT` matches that shape too, deliberately,
+ * because it is a different failure with its own advice.
+ *
+ * Returned only for a failure that is a real refusal, so a retriable error
+ * carrying a similar string cannot talk a host into compacting a turn that
+ * was never the problem.
+ */
+export declare function contextWindowTokens(error: unknown): number | undefined;
+/**
+ * A failure message a person can act on.
+ *
+ * The endpoint is included because "request failed" tells the reader nothing
+ * when three of them are configured, and the status because a body alone
+ * cannot distinguish a rate limit from a crash. An HTML body is summarised
+ * rather than quoted: the previous behaviour pasted its first 600 characters
+ * into the transcript, which buried a one-line diagnosis under a wall of markup
+ * and still omitted the two facts that would have identified the fault.
+ *
+ * The closing line is derived from `retriable`, never from a guess about what
+ * "usually" happens. Telling someone a 403 will be retried when it will not is
+ * worse than saying nothing, because they wait for a retry that never comes.
+ *
+ * The URL is safe to print — the constructor clears any query string, so a key
+ * passed as a query parameter is already gone by this point.
+ */
+export declare function describeHttpFailure(endpoint: string, response: Response, body: string, retriable: boolean, retryAfterMs?: number): string;
+//# sourceMappingURL=model-client.d.ts.map

package/dist/model-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-client.d.ts","sourceRoot":"","sources":["../src/model-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAY,cAAc,EAAS,MAAM,YAAY,CAAC;AAExG,qBAAa,mBAAoB,SAAQ,KAAK;IAMf,QAAQ,CAAC,SAAS;IAAU,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM;IALvF;;;;OAIG;gBACS,OAAO,EAAE,MAAM,EAAW,SAAS,UAAQ,EAAW,YAAY,CAAC,EAAE,MAAM,YAAA;CAIxF;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,SAAU,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,SAAS,CAa3F;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,eAAe,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CAC7C,CAAC;AAyBF,qBAAa,qBAAsB,YAAW,WAAW;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IACjD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAA4B;gBAEjD,OAAO,EAAE,uBAAuB;IAqBrC,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC;CA+GhH;AAkGD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAMtF,CAAA,yEAAyE;AA0B1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ7F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG9D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAStE;AAqGD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,OAAO,EAClB,YAAY,CAAC,EAAE,MAAM,GACpB,MAAM,CAyBR"}