Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
feat(ts): add local Agent and Router predictLong
wowe62cd678ab93
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.tsindex bfef3b9f..fa133562 100644--- a/laya-ts/src/agent.ts+++ b/laya-ts/src/agent.ts@@ -22,6 +22,8 @@ import {import type { BinningMap, InternalQ, MinConfidence, OptionStats, SequenceStats } from "./common.js";import type { Batch, SessionProvider } from "./providers.js";import type { OptionStabilityReport } from "./option-stability.js";+import { predictLong, recordLongResults, finishLongResults, isLongCall, type LongPredictOptions, type LongResult } from "./predict-long.js";+export type { LongPredictOptions, LongResult, LongUsage, LongAnswer, LongWindow } from "./predict-long.js";import { encodeWithData, parseTokenizerJson, type TokenizerLike } from "./tokenizer.js";import { decide, decideBatch, type DecideOptions, type DecideBatchOptions, type DecisionResult } from "./structured.js";import {@@ -616,11 +618,12 @@ export class Agent extends HookRegistry {throw err;} finally {ctx.markElapsed();- if (ctx.results !== null) {+ if (ctx.results !== null && (!isLongCall(opts) || Array.isArray(ctx.results))) {ctx.usage = aggregateUsage(ctx.results);if (mc !== null) {flagLowConfidence(ctx.results as unknown as Record<string, unknown>[], mc);}+ recordLongResults(opts, ctx);}try {await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors, timeoutMs });@@ -629,6 +632,7 @@ export class Agent extends HookRegistry {if (ctx.error === null) throw hookErr;}}+ finishLongResults(opts, ctx);return ctx.results as unknown as SystemOneResult[];}@@ -882,6 +886,19 @@ export class Agent extends HookRegistry {return this._predictHooked(states, questions, opts);}+ /** Scan overlapping token windows locally and keep each question's strongest answer.+ * Attribution refers to the original candidate token slice; decoding and re-encoding can+ * change its length. Confidence belongs to the winning window, not the whole document.+ * Agent hooks wrap one batch of windows. A hook budget change is checked after inference.+ */+ async predictLong(+ state: unknown,+ questions: Record<string, QuestionDef>,+ opts: LongPredictOptions = {},+ ): Promise<LongResult> {+ return predictLong(this, state, questions, opts);+ }+/*** Answer `state` against a JSON schema (or explicit `opts.questions`) and return typed* values — see `structured.ts`. Pass exactly one of `schema` or `opts.questions`; otherdiff --git a/laya-ts/src/index.ts b/laya-ts/src/index.tsindex cec8a0d0..28d2b3c7 100644--- a/laya-ts/src/index.ts+++ b/laya-ts/src/index.ts@@ -1,5 +1,6 @@export const VERSION = "0.1.0";export { Agent, checkQuestion, toInternal, defaultTokenizer } from "./agent.js";+export type { LongPredictOptions, LongResult, LongUsage, LongAnswer, LongWindow } from "./predict-long.js";export type {QuestionDef,SystemOneResult,@@ -16,7 +17,7 @@ export type {export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle, PINNED_REVISIONS, resolveRevision } from "./providers.js";export type { Batch, SessionProvider, ProviderOptions, NodeBundle, WebBundle } from "./providers.js";export { Router, normaliseName, DEFAULT_MODELS, digestsFromEnv, _digestsFromEnv } from "./router.js";-export type { RoutedResult, RouteDecision, ModelName, ModelSpec, BatchRequest, PredictBatchOptions, RouterOptions, RouteOptions } from "./router.js";+export type { RoutedResult, RoutedLongResult, RoutedLongPredictOptions, RouteDecision, ModelName, ModelSpec, BatchRequest, PredictBatchOptions, RouterOptions, RouteOptions } from "./router.js";export { shortlistChoice, predictShortlist, predictTournament, embedFnFromAgent, cached, cachedEmbedFn, DEFAULT_SHORTLIST_K, DEFAULT_SHORTLIST_MAXSIZE, DEFAULT_TOURNAMENT_GROUP } from "./shortlist.js";export type { EmbedFn, ShortlistMeta, TournamentMeta, CacheInfo, CachedEmbedFn } from "./shortlist.js";export { analyse, isEnglish, guessLatinLanguage, detectScript } from "./lang.js";diff --git a/laya-ts/src/predict-long.ts b/laya-ts/src/predict-long.tsnew file mode 100644index 00000000..cd350282--- /dev/null+++ b/laya-ts/src/predict-long.ts@@ -0,0 +1,361 @@+import { buildQuestionPrefix, serializeState } from "./common.js";+import type { OptionStats } from "./common.js";+import { checkQuestion, toInternal } from "./agent.js";+import type { Agent, QuestionDef, SystemAnswer, PredictOptions } from "./agent.js";+import { defaultsAlreadyRan, markDefaultsRan, normaliseHooks } from "./hooks.js";+import type { HookArg, PredictContext, PredictHook } from "./hooks.js";++export interface LongWindow {+ index: number;+ token_start: number;+ token_end: number;+ count: number;+}++export type LongAnswer = SystemAnswer & { window?: LongWindow };++/** Long scans sum numeric usage, including boolean truncation flags. */+export interface LongUsage {+ input_tokens: number;+ output_tokens: number;+ windows: number;+ state_tokens?: number;+ state_tokens_dropped?: number;+ truncated?: boolean | number;+ truncated_questions?: string[];+ options?: Record<string, OptionStats>;+ [key: string]: unknown;+}++export interface LongResult {+ model: string;+ answers: Record<string, LongAnswer>;+ usage: LongUsage;+}++// Deliberately independent of PredictOptions: windows are sized from the Agent config,+// and the winning window's confidence is not a document-level confidence threshold.+export interface LongPredictOptions {+ window?: number | null;+ stride?: number | null;+ aggregate?: "auto";+ batchSize?: number | null;+ lang?: string | null;+ hooks?: HookArg;+ onPredictStart?: PredictHook;+ onPredictEnd?: PredictHook;+ hooksRaise?: boolean;+ hooksTimeout?: number | null;+}++type Dict = Record<string, unknown>;+function isDict(value: unknown): value is Dict {+ if (typeof value !== "object" || value === null || Array.isArray(value)) return false;+ const proto = Object.getPrototypeOf(value);+ return proto === Object.prototype || proto === null;+}++function copyValue<T>(value: T): T {+ if (Array.isArray(value)) return value.map(copyValue) as T;+ if (isDict(value)) return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, copyValue(val)])) as T;+ return value;+}++function sameValue(a: unknown, b: unknown): boolean {+ if (Object.is(a, b)) return true;+ if (Array.isArray(a) && Array.isArray(b)) {+ return a.length === b.length && a.every((value, i) => sameValue(value, b[i]));+ }+ if (isDict(a) && isDict(b)) {+ const keys = Object.keys(a);+ return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && sameValue(a[key], b[key]));+ }+ return false;+}++/** Validate values supplied by hooks without widening ordinary prediction types. */+export function validateLongResult(value: unknown, label = "predictLong result", requireWindows = true): asserts value is LongResult {+ if (!isDict(value) || typeof value.model !== "string" || !isDict(value.answers) || !isDict(value.usage)) {+ throw new TypeError(`${label}: expected model, answers and usage objects`);+ }+ const usage = value.usage;+ for (const key of ["input_tokens", "output_tokens", "state_tokens", "state_tokens_dropped"]) {+ if (key !== "input_tokens" && key !== "output_tokens" && usage[key] === undefined) continue;+ if (typeof usage[key] !== "number" || !Number.isFinite(usage[key]) || usage[key] < 0) {+ throw new TypeError(`${label}: usage.${key} must be a finite non-negative number`);+ }+ }+ if ((requireWindows || usage.windows !== undefined) &&+ (!Number.isSafeInteger(usage.windows) || (usage.windows as number) < 0)) {+ throw new TypeError(`${label}: usage.windows must be a non-negative safe integer`);+ }+ if (usage.truncated !== undefined && typeof usage.truncated !== "boolean" &&+ (typeof usage.truncated !== "number" || !Number.isFinite(usage.truncated) || usage.truncated < 0)) {+ throw new TypeError(`${label}: usage.truncated must be a boolean or non-negative number`);+ }+ if (usage.truncated_questions !== undefined && (!Array.isArray(usage.truncated_questions) ||+ usage.truncated_questions.some((qid) => typeof qid !== "string"))) {+ throw new TypeError(`${label}: usage.truncated_questions must be an array of question ids`);+ }+ if (usage.options !== undefined && (!isDict(usage.options) || Object.values(usage.options).some((stats) =>+ !isDict(stats) || ["total", "distinct"].some((key) => typeof stats[key] !== "number" || !Number.isFinite(stats[key]) || stats[key] < 0) ||+ (stats.tokens_per_option !== null && (typeof stats.tokens_per_option !== "number" || !Number.isFinite(stats.tokens_per_option) || stats.tokens_per_option < 0))))) {+ throw new TypeError(`${label}: usage.options must map question ids to option statistics`);+ }+ for (const [qid, answer] of Object.entries(value.answers)) {+ if (!isDict(answer) || !["choice", "score", "noul"].includes(answer.type as string)) {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)} must have a supported type`);+ }+ for (const key of ["confidence", "answer_confidence", ...(answer.type === "noul" ? ["noul"] : answer.type === "score" ? ["score"] : [])]) {+ if (typeof answer[key] !== "number" || !Number.isFinite(answer[key])) {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.${key} must be a finite number`);+ }+ }+ if (answer.type === "choice" && typeof answer.choice !== "string") {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.choice must be a string`);+ }+ if (!isDict(answer.action) || typeof answer.action.act_probability !== "number" || !Number.isFinite(answer.action.act_probability)) {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.action.act_probability must be a finite number`);+ }+ if (answer.type !== "noul" && (!isDict(answer.probabilities) ||+ Object.values(answer.probabilities).some((probability) => typeof probability !== "number" || !Number.isFinite(probability)))) {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.probabilities must map labels to finite numbers`);+ }+ if (answer.type === "score" && (!isDict(answer.legend) || Object.values(answer.legend).some((level) => typeof level !== "string"))) {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.legend must map levels to strings`);+ }+ if (answer.window !== undefined) {+ const w = answer.window;+ if (!isDict(w) || !["index", "token_start", "token_end", "count"].every((key) => Number.isSafeInteger(w[key]) && (w[key] as number) >= 0) ||+ (w.index as number) >= (w.count as number) || (w.token_start as number) > (w.token_end as number)) {+ throw new TypeError(`${label}: answer ${JSON.stringify(qid)}.window is invalid`);+ }+ }+ }+}++/** Cache results are copied; counting a skipped scan must not mutate the caller's cache. */+export function skippedLongResult(value: unknown): LongResult {+ validateLongResult(value, "predictLong hook result", false);+ return { ...value, usage: { ...value.usage, windows: 0 } };+}++export function validateLongOptions(opts: LongPredictOptions): void {+ for (const key of ["window", "stride", "batchSize"] as const) {+ const value = opts[key];+ if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || value <= 0)) {+ throw new TypeError(`predictLong: ${key} must be a positive safe integer`);+ }+ }+ if (opts.aggregate !== undefined && opts.aggregate !== "auto") {+ throw new Error("predictLong: only aggregate='auto' is supported");+ }+}++interface AnswerRecord { index: number; values: Dict }+interface Evidence {+ answered: boolean;+ states: unknown[] | null;+ questionTypes: Record<string, unknown> | null;+ questions: Dict | null;+ maxLen: number | null;+ headMaxLen: number | null;+ answers: Map<object, Map<string, AnswerRecord | null>> | null;+ resultCount: number | null;+ trackAnswers: boolean;+}++const recorders = new WeakMap<PredictOptions, Evidence>();+export function isLongCall(opts: PredictOptions): boolean { return recorders.has(opts); }++/** The short public systemOne path returns just the first result; retain its final count. */+export function finishLongResults(opts: PredictOptions, ctx: PredictContext): void {+ const evidence = recorders.get(opts);+ if (!evidence) return;+ if (!Array.isArray(ctx.results)) throw new TypeError("predictLong: prediction hooks must return an array of results");+ evidence.resultCount = ctx.results.length;+}+const predictionFields = ["type", "choice", "noul", "score", "legend", "probabilities", "confidence", "answer_confidence"];+function answerValues(answer: Dict): Dict {+ return Object.fromEntries(predictionFields.filter((key) => Object.hasOwn(answer, key)).map((key) => [key, copyValue(answer[key])]));+}++/** Internal dispatcher boundary: record inference results before any end hook can edit them. */+export function recordLongResults(opts: PredictOptions, ctx: PredictContext): void {+ const evidence = recorders.get(opts);+ if (!evidence || !Array.isArray(ctx.results)) return;+ evidence.resultCount = ctx.results.length;+ if (evidence.answered || !evidence.trackAnswers) return;+ const recorded: NonNullable<Evidence["answers"]> = new Map();+ ctx.results.forEach((result, index) => {+ if (!isDict(result?.answers)) return;+ for (const [qid, answer] of Object.entries(result.answers)) {+ if (!isDict(answer)) continue;+ let byQuestion = recorded.get(answer);+ if (!byQuestion) recorded.set(answer, byQuestion = new Map());+ byQuestion.set(qid, byQuestion.has(qid) ? null : { index, values: answerValues(answer) });+ }+ });+ evidence.answers = recorded;+}++function observedOptions(opts: LongPredictOptions, trackAnswers: boolean): [PredictOptions, Evidence] {+ const evidence: Evidence = { answered: false, states: null, questionTypes: null, questions: null,+ maxLen: null, headMaxLen: null, answers: null, resultCount: null, trackAnswers };+ const hooks = normaliseHooks(opts.hooks, opts.onPredictStart, opts.onPredictEnd);+ hooks.push({ onPredictStart(ctx) {+ evidence.answered = ctx.results !== null;+ evidence.states = Array.isArray(ctx.states) ? [...ctx.states] : null;+ if (!evidence.answered && isDict(ctx.questions)) {+ evidence.questionTypes = Object.fromEntries(Object.entries(ctx.questions).map(([qid, q]) => [qid, isDict(q) ? q.type : null]));+ }+ evidence.maxLen = ctx.maxLen;+ evidence.headMaxLen = ctx.headMaxLen;+ evidence.questions = isDict(ctx.questions) ? { ...ctx.questions } : null;+ } });+ const call: PredictOptions = { lang: opts.lang, hooks, hooksRaise: opts.hooksRaise, hooksTimeout: opts.hooksTimeout };+ if (defaultsAlreadyRan(opts)) markDefaultsRan(call);+ recorders.set(call, evidence);+ return [call, evidence];+}++function stateRoom(agent: Agent, questions: Record<string, QuestionDef>, maxLen: number, headMaxLen: number): number[] {+ return Object.values(questions).map((q) => Math.max(0, maxLen - buildQuestionPrefix(agent.tok, toInternal(q), maxLen, headMaxLen).ids.length - 1));+}++function windowBudget(agent: Agent, questions: Record<string, QuestionDef>, opts: LongPredictOptions): [number, number, number] {+ const requested = opts.window ?? Math.max(64, agent.maxLen - agent.headMaxLen - 8);+ const rooms = stateRoom(agent, questions, agent.maxLen, agent.headMaxLen);+ const room = rooms.length ? Math.min(...rooms) : requested;+ if (room <= 0) throw new Error(`predictLong: the questions' options fill the whole sequence (maxLen=${agent.maxLen}, headMaxLen=${agent.headMaxLen}), leaving no room for the state`);+ const size = Math.min(requested, room);+ if (size < requested && (opts.window != null || requested >= room * 2)) {+ console.warn(`laya: predictLong: questions leave ${room} state tokens inside maxLen=${agent.maxLen}; capping window ${requested} -> ${size}. Fewer or shorter options reduce the number of full forward passes.`);+ }+ let step = opts.stride ?? Math.max(1, Math.floor(size / 2));+ if (step > size) {+ if (size < requested && step <= requested) {+ const adjusted = Math.max(1, Math.floor(size / 2));+ console.warn(`laya: predictLong: window was reduced to ${size}; adjusting stride ${step} -> ${adjusted} to avoid unread gaps`);+ step = adjusted;+ } else {+ throw new Error(`predictLong: stride=${step} steps past the ${size}-token window; pass stride <= ${size}`);+ }+ }+ return [size, step, room];+}++function checkScanBudget(agent: Agent, evidence: Evidence, sized: number, asked: Record<string, QuestionDef>): void {+ if (evidence.answered || !evidence.questions || !Object.keys(evidence.questions).length) return;+ const maxLen = evidence.maxLen ?? agent.maxLen;+ const headMaxLen = evidence.headMaxLen ?? agent.headMaxLen;+ if (maxLen === agent.maxLen && headMaxLen === agent.headMaxLen && sameValue(evidence.questions, asked)) return;+ let rooms: number[];+ try { rooms = stateRoom(agent, evidence.questions as Record<string, QuestionDef>, maxLen, headMaxLen); }+ catch { return; } // Malformed questions belong to the normal inference validator.+ const room = Math.min(...rooms);+ if (room < sized) throw new Error(`predictLong: after the start hooks ran, the questions and token budget (maxLen=${maxLen} headMaxLen=${headMaxLen}) leave ${room} state tokens per window, but the scan was sized for ${sized} from the agent's config (maxLen=${agent.maxLen} headMaxLen=${agent.headMaxLen}). Every window would be re-truncated and parts of the document would reach no model. Pass window/stride explicitly, or call predictBatch directly, if a start hook changes either.`);+}++export async function predictLong(agent: Agent, state: unknown, questions: Record<string, QuestionDef>, opts: LongPredictOptions): Promise<LongResult> {+ if (state === null || state === undefined) throw new TypeError("state must not be None; pass a string, dict, or list");+ if (!isDict(questions)) throw new TypeError("questions must be a dict of question id -> definition");+ validateLongOptions(opts);+ for (const [qid, q] of Object.entries(questions)) checkQuestion(qid, q);+ const [budget, step, room] = windowBudget(agent, questions, opts);+ const asked = copyValue(questions);+ const stateIds = agent.tok.encode(serializeState(state).split(agent.tok.maskToken).join(" "));+ if (stateIds.length <= (opts.window != null ? budget : room)) {+ const [call, evidence] = observedOptions(opts, false);+ let single: unknown;+ try { single = await agent.systemOne(state, questions, call); }+ finally { recorders.delete(call); }+ // Correctness checks are outside the hook dispatcher and its suppression/timeout policy.+ // Inference has already run; changing that order would change the hook contract.+ checkScanBudget(agent, evidence, Math.max(budget, stateIds.length), asked);+ if (evidence.answered) {+ if (evidence.resultCount !== 1) throw new Error(`predictLong: a start hook answered this state with ${evidence.resultCount} results; ctx.skip() takes one result for the document`);+ console.warn("laya: predictLong: a hook answered the state before it was scanned, so no window decided the result");+ return skippedLongResult(single);+ }+ validateLongResult(single, "predictLong result", false);+ return { ...single, usage: { ...single.usage, windows: 1 } };+ }+ if (typeof agent.tok.decode !== "function") {+ const name = (agent.tok as { name?: unknown }).name ?? agent.tok.constructor?.name ?? "custom tokenizer";+ throw new Error(`predictLong: tokenizer ${JSON.stringify(name)} needs decode(ids) to split a long state`);+ }+ const windows: string[] = [], starts: number[] = [];+ for (let start = 0; start < stateIds.length; start += step) {+ windows.push(agent.tok.decode(stateIds.slice(start, start + budget)));+ starts.push(start);+ if (start + budget >= stateIds.length) break;+ }+ const [call, evidence] = observedOptions(opts, true);+ const configBudget = Math.max(64, agent.maxLen - agent.headMaxLen - 8);+ const unclamped = Math.max(1, Math.ceil(windows.length * Math.max(1, Math.floor(budget / 2)) / Math.max(1, Math.floor(configBudget / 2))));+ call.batchSize = opts.batchSize ?? (budget < configBudget && windows.length > unclamped * 2 ? unclamped : null);+ let results: unknown;+ try { results = await agent.predictBatch([...windows], questions, call); }+ finally { recorders.delete(call); }+ checkScanBudget(agent, evidence, budget, asked);+ if (!Array.isArray(results)) throw new TypeError("predictLong: prediction hooks must return an array of results");+ if (evidence.answered) {+ if (results.length !== 1) throw new Error(`predictLong: a start hook answered this state with ${results.length} results; ctx.skip() takes one result for the document, not one per window`);+ console.warn("laya: predictLong: a hook answered the state before it was scanned, so no window decided the result");+ return skippedLongResult(results[0]);+ }+ const rewritten = evidence.states !== null && !sameValue(evidence.states, windows);+ if (results.length !== windows.length && !rewritten) throw new Error(`predictLong: the state was split into ${windows.length} windows and the call returned ${results.length} results`);+ if (!results.length) {+ console.warn("laya: predictLong: a start hook left no states to score, so the call aggregated nothing and returns no answers");+ return { model: "laya-rl-agent", answers: {}, usage: { input_tokens: 0, output_tokens: 0, windows: 0 } };+ }+ for (const result of results) validateLongResult(result, "predictLong window result", false);+ const rows = results as LongResult[];+ const questionTypes = evidence.questionTypes ?? Object.fromEntries(Object.entries(questions).map(([qid, q]) => [qid, q.type]));+ const answers: Record<string, LongAnswer> = {};+ for (const [qid, qtype] of Object.entries(questionTypes)) {+ const missing = rows.filter((r) => !Object.hasOwn(r.answers, qid)).length;+ if (missing) {+ if (missing === rows.length && !Object.hasOwn(asked, qid) && evidence.questionTypes !== null) continue;+ throw new Error(`predictLong: answer ${JSON.stringify(qid)} is missing from ${missing} of ${rows.length} windows after prediction hooks`);+ }+ const per = rows.map((r) => r.answers[qid]);+ if (per.some((answer) => answer.type !== per[0].type)) throw new Error(`predictLong: answer ${JSON.stringify(qid)} has inconsistent types across windows`);+ // The inference schema chooses the aggregation rule, even when end hooks uniformly+ // rewrite the answer schema. Such edits invalidate attribution, not the result itself.+ const metric = (answer: LongAnswer): number => qtype === "noul" ? (answer as { noul: number }).noul : answer.answer_confidence;+ if (per.some((answer) => !Number.isFinite(metric(answer)))) throw new TypeError(`predictLong: answer ${JSON.stringify(qid)} is missing the numeric aggregation field for ${String(qtype)}`);+ let best = 0;+ for (let i = 1; i < per.length; i++) if (metric(per[i]) > metric(per[best])) best = i;+ const original = per[best];+ let index: number | null = null;+ if (!rewritten) {+ if (evidence.answers === null) index = best; // A replacement predictBatch did not dispatch hooks.+ else {+ const record = evidence.answers.get(original)?.get(qid);+ if (record && sameValue(record.values, answerValues(original as unknown as Dict))) index = record.index;+ }+ }+ const answer = { ...original };+ delete answer.window;+ if (index !== null) answer.window = { index, token_start: starts[index], token_end: Math.min(starts[index] + budget, stateIds.length), count: rows.length };+ Object.defineProperty(answers, qid, { value: answer, enumerable: true, writable: true, configurable: true });+ }+ const usage: Dict = Object.create(null);+ for (const row of rows) {+ for (const [key, value] of Object.entries(row.usage)) {+ const previous = usage[key];+ if (typeof value === "number" || typeof value === "boolean") {+ usage[key] = (typeof previous === "number" || typeof previous === "boolean" ? Number(previous) : 0) + Number(value);+ } else if (isDict(value) && isDict(previous)) usage[key] = { ...previous, ...value };+ else Object.defineProperty(usage, key, { value, enumerable: true, writable: true, configurable: true });+ }+ }+ const result = { model: "laya-rl-agent", answers, usage: { ...usage, output_tokens: 0, windows: rows.length } as LongUsage };+ // Individually finite window counters can still overflow when summed. The Agent+ // must uphold the same result contract that the Router checks at its boundary.+ validateLongResult(result);+ return result;+}diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.tsindex 11c6f151..5a85b104 100644--- a/laya-ts/src/router.ts+++ b/laya-ts/src/router.ts@@ -1,5 +1,6 @@import { analyse, type AnalyseResult } from "./lang.js";import { checkQuestion, type PredictOptions, type QuestionDef, type SystemOneResult } from "./agent.js";+import { skippedLongResult, validateLongOptions, validateLongResult, type LongPredictOptions, type LongResult } from "./predict-long.js";import { checkMinConfidence, flagLowConfidence } from "./common.js";import { decide, decideBatch, type DecideOptions, type DecideBatchOptions, type DecisionResult } from "./structured.js";import {@@ -11,6 +12,7 @@ import {markDefaultsRan,dispatchAsync,normaliseHooks,+ validateHooksTimeout,type Hook,type HookArg,type PredictHook,@@ -110,6 +112,23 @@ export interface RouteDecision {}export type RoutedResult = SystemOneResult & { routing: RouteDecision };+export type RoutedLongResult = LongResult & { routing: RouteDecision };+export type RoutedLongPredictOptions = RouteOptions & LongPredictOptions;++function validLongRouting(routing: RouteDecision | undefined): boolean {+ if (!routing || typeof routing !== "object" || Array.isArray(routing) ||+ !Object.hasOwn(DEFAULT_MODELS, routing.model) || typeof routing.repo !== "string" ||+ typeof routing.reason !== "string" ||+ (routing.workflow !== null && typeof routing.workflow !== "string")) return false;+ const d = routing.detection;+ return d === null || (typeof d === "object" && !Array.isArray(d) &&+ typeof d.script === "string" && (d.language === null || typeof d.language === "string") &&+ typeof d.isEnglish === "boolean" && typeof d.languageUndecided === "boolean" &&+ Number.isFinite(d.diacriticRate) && Number.isFinite(d.nonLatinFraction) &&+ (d.mixedSegment === null || typeof d.mixedSegment === "string") &&+ d.scriptProfile !== null && typeof d.scriptProfile === "object" && !Array.isArray(d.scriptProfile) &&+ Object.values(d.scriptProfile).every((value) => typeof value === "number" && Number.isFinite(value)));+}export type LangGuess = string | null | undefined | ((state: unknown) => unknown);@@ -591,6 +610,25 @@ export class Router extends HookRegistry {questions: Record<string, QuestionDef>,opts: RouteOptions & PredictOptions = {},): Promise<RoutedResult> {+ return this._predict(state, questions, opts) as Promise<RoutedResult>;+ }++ /** Route the document once, then scan it using the selected Agent's window budget. */+ async predictLong(+ state: unknown,+ questions: Record<string, QuestionDef>,+ opts: RoutedLongPredictOptions = {},+ ): Promise<RoutedLongResult> {+ validateLongOptions(opts);+ return this._predict(state, questions, opts, opts) as Promise<RoutedLongResult>;+ }++ private async _predict(+ state: unknown,+ questions: Record<string, QuestionDef>,+ opts: RouteOptions & PredictOptions,+ scan?: LongPredictOptions,+ ): Promise<RoutedResult | RoutedLongResult> {if (state === null || state === undefined) {throw new TypeError("state must not be None; pass a string, dict, or list");}@@ -599,10 +637,12 @@ export class Router extends HookRegistry {`questions must be a dict of question id -> definition, got ${questions === null ? "null" : Array.isArray(questions) ? "Array" : typeof questions}`,);}- const mcOpt = opts.minConfidence ?? opts.min_confidence;+ const mcOpt = scan ? undefined : opts.minConfidence ?? opts.min_confidence;const mc = mcOpt !== undefined && mcOpt !== null ? checkMinConfidence(mcOpt) : null;const active = composeHooks(this.hooks, opts.hooks, opts.onPredictStart, opts.onPredictEnd);const raiseErrors = opts.hooksRaise ?? this.hooksRaise;+ const timeout = scan ? validateHooksTimeout(scan.hooksTimeout) : null;+ const timeoutMs = timeout === null ? null : timeout * 1000;const hasStart = active.some((h) => typeof h.onPredictStart === "function");// The per-call token-budget overrides seed the context, so a start hook can read and rewrite// them exactly as it can `states`/`questions`; the values it leaves are what reaches the agent@@ -615,8 +655,8 @@ export class Router extends HookRegistry {model: null,agent: null,router: this,- maxLen: opts.maxLen ?? null,- headMaxLen: opts.headMaxLen ?? null,+ maxLen: scan ? null : opts.maxLen ?? null,+ headMaxLen: scan ? null : opts.headMaxLen ?? null,});try {// Per-call hooks apply to the whole call, including onRoute inside route().@@ -632,7 +672,7 @@ export class Router extends HookRegistry {};ctx.agent = agent;- await dispatchAsync(active, "onPredictStart", ctx, { raiseErrors });+ await dispatchAsync(active, "onPredictStart", ctx, { raiseErrors, timeoutMs });if (ctx.results === null) {if (hasStart) {if (typeof ctx.questions !== "object" || ctx.questions === null || Array.isArray(ctx.questions)) {@@ -659,14 +699,36 @@ export class Router extends HookRegistry {if (ctx.maxLen !== null && ctx.maxLen !== undefined) agentOpts.maxLen = ctx.maxLen;if (ctx.headMaxLen !== null && ctx.headMaxLen !== undefined) agentOpts.headMaxLen = ctx.headMaxLen;markDefaultsRan(agentOpts);- const result = (await agent.systemOne(- ctx.states[0],- ctx.questions as Record<string, QuestionDef>,- agentOpts,- )) as RoutedResult;- result["routing"] = { ...decision };+ let result: RoutedResult | RoutedLongResult;+ if (scan) {+ // Read the context after start hooks, but run inference outside hook dispatch. A+ // timeout or suppressed hook error must never turn a scan into one truncated pass.+ const runner = ctx.agent as { predictLong?: (s: unknown, q: Record<string, QuestionDef>, o: LongPredictOptions) => Promise<LongResult> } | null;+ if (typeof runner?.predictLong !== "function") {+ throw new TypeError("Router.predictLong requires the routed agent to implement predictLong");+ }+ const detection = ctx.decision?.detection as AnalyseResult | null | undefined;+ const longOpts: LongPredictOptions = {+ window: scan.window, stride: scan.stride, aggregate: scan.aggregate,+ batchSize: scan.batchSize, lang: scan.lang ?? detection?.language ?? null,+ };+ markDefaultsRan(longOpts);+ const scanned = await runner.predictLong(ctx.states[0], ctx.questions as Record<string, QuestionDef>, longOpts);+ validateLongResult(scanned, "Router.predictLong agent result");+ result = { ...scanned, routing: (scanned as RoutedLongResult).routing ?? { ...decision } };+ } else {+ result = (await agent.systemOne(ctx.states[0], ctx.questions as Record<string, QuestionDef>, agentOpts)) as RoutedResult;+ result.routing = { ...decision };+ }ctx.results = [result as unknown as Record<string, unknown>];} else {+ if (scan) {+ if (!Array.isArray(ctx.results) || ctx.results.length !== 1) {+ throw new Error("Router.predictLong: a skipping hook must return exactly one document result");+ }+ ctx.results = [skippedLongResult(ctx.results[0]) as unknown as Record<string, unknown>];+ console.warn("laya: Router.predictLong: a start hook answered the document without scanning; usage.windows is 0");+ }// A cache hit short-circuits inference, but predict still promises a `routing` key.// Add it without overwriting a routing the cached payload already has.for (const result of ctx.results) {@@ -678,27 +740,37 @@ export class Router extends HookRegistry {} catch (err) {ctx.error = err;try {- await dispatchAsync(active, "onError", ctx, { raiseErrors });+ await dispatchAsync(active, "onError", ctx, { raiseErrors, timeoutMs });} catch {// A failing onError hook must not hide the failure that triggered it.}throw err;} finally {ctx.markElapsed();- if (ctx.results !== null) {+ if (ctx.results !== null && (!scan || Array.isArray(ctx.results))) {ctx.usage = aggregateUsage(ctx.results);if (mc !== null) {flagLowConfidence(ctx.results as unknown as Record<string, unknown>[], mc);}}try {- await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors });+ await dispatchAsync(active, "onPredictEnd", ctx, { raiseErrors, timeoutMs });} catch (hookErr) {// End hooks run on the failure path too; do not let one mask the real error.if (ctx.error === null) throw hookErr;}}- return (ctx.results as unknown as RoutedResult[])[0];+ if (scan) {+ if (!Array.isArray(ctx.results) || ctx.results.length !== 1) {+ throw new Error("Router.predictLong must return exactly one document result");+ }+ validateLongResult(ctx.results[0], "Router.predictLong result");+ const routing = ctx.results[0].routing as RouteDecision | undefined;+ if (!validLongRouting(routing)) {+ throw new TypeError("Router.predictLong result must include a valid routing decision");+ }+ }+ return (ctx.results as unknown as (RoutedResult | RoutedLongResult)[])[0];}/**diff --git a/laya-ts/tests/agent-long.test.ts b/laya-ts/tests/agent-long.test.tsnew file mode 100644index 00000000..5f0af51b--- /dev/null+++ b/laya-ts/tests/agent-long.test.ts@@ -0,0 +1,286 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { Agent, defaultTokenizer, type QuestionDef } from "../src/agent.js";+import { clearDefaultHooks, setDefaultHooks, type PredictContext } from "../src/hooks.js";+import { OptionStabilityHook } from "../src/option-stability.js";+import type { Batch, SessionProvider } from "../src/providers.js";++afterEach(() => { clearDefaultHooks(); vi.restoreAllMocks(); });+const questions: Record<string, QuestionDef> = { q: { type: "noul", instructions: "true?" } };+const document = "abcdefghijklmnopqrstuvwxyz".repeat(4);+const tok = { ...defaultTokenizer(),+ encode: (text: string) => Array.from(text, (c) => c.codePointAt(0)! + 200),+ decode: (ids: readonly number[]) => String.fromCodePoint(...ids.map((id) => id - 200)),+};+function makeAgent(increasing = false, options = {}) {+ const batches: Batch[] = [];+ let row = 0;+ const provider: SessionProvider = {+ async runEncoder(batch) { batches.push(batch); return { lastHidden: batch.inputIds.map(() => [[0]]) }; },+ async runHead(_hidden, batch) {+ return { logits: batch.qtype.map((_, i) => batch.markerPos[i].map((_, option) => option === 1 ? increasing ? ++row / 4 : 2 : 0)), act: batch.qtype.map(() => [0, 1]) };+ },+ };+ return { agent: new Agent({ provider, tok, max_len: 80, head_max_len: 32, ...options }), batches };+}++describe("Agent.predictLong", () => {+ it("preserves short-path output and supports encode-only custom tokenizers", async () => {+ const { agent } = makeAgent();+ const { decode: _decode, ...encodeOnly } = tok;+ agent.tok = encodeOnly;+ const ordinary = await agent.predict("short", questions);+ expect(await agent.predictLong("short", questions)).toEqual({ ...ordinary, usage: { ...ordinary.usage, windows: 1 } });+ await expect(agent.predictLong(document, questions, { window: 20 })).rejects.toThrow("needs decode");+ });++ it("rejects bad questions and unsafe options before hooks or inference", async () => {+ const { agent, batches } = makeAgent();+ const hook = vi.fn();+ await expect(agent.predictLong(document, { q: { type: "invalid" } }, { onPredictStart: hook })).rejects.toThrow('question "q"');+ for (const key of ["window", "stride", "batchSize"]) {+ for (const value of [0, -1, 1.1, NaN, Infinity, Number.MAX_SAFE_INTEGER + 1, true]) {+ await expect(agent.predictLong(document, questions, { [key]: value, onPredictStart: hook })).rejects.toThrow("positive safe integer");+ }+ }+ await expect(agent.predictLong(document, questions, { window: 10, stride: 11 })).rejects.toThrow("stride=11");+ await expect(agent.predictLong(document, questions, { aggregate: "mean" as never })).rejects.toThrow("only aggregate");+ expect(hook).not.toHaveBeenCalled();+ expect(batches).toHaveLength(0);+ });++ it("uses batched inference, earliest ties, candidate spans and numeric truncation counts", async () => {+ const { agent, batches } = makeAgent();+ const result = await agent.predictLong(document, questions, { window: 20, stride: 10, batchSize: 3 });+ expect(result.answers.q.window).toEqual({ index: 0, token_start: 0, token_end: 20, count: 10 });+ expect(result.usage.windows).toBe(10);+ expect(result.usage.truncated).toBe(0);+ expect(batches.map((b) => b.inputIds.length)).toEqual([3, 3, 3, 1]);+ expect(result.usage.output_tokens).toBe(0);+ });++ it("keeps inference answer identity through default/installed/per-call end-hook reordering", async () => {+ const events: string[] = [];+ setDefaultHooks({ onPredictStart: () => { events.push("default-start"); }, onPredictEnd: (ctx) => { ctx.results!.reverse(); events.push("default-end"); } });+ const { agent } = makeAgent(true, { hooks: { onPredictStart: () => { events.push("installed-start"); }, onPredictEnd: () => { events.push("installed-end"); } } });+ const result = await agent.predictLong(document, questions, { window: 20,+ onPredictStart: async () => { await Promise.resolve(); events.push("call-start"); },+ onPredictEnd: () => { events.push("call-end"); },+ });+ expect(result.answers.q.window).toEqual({ index: 9, token_start: 90, token_end: 104, count: 10 });+ expect(events).toEqual(["default-start", "installed-start", "call-start", "default-end", "installed-end", "call-end"]);+ });++ it("does not invent an origin for an answer object shared by inference rows", async () => {+ const { agent } = makeAgent();+ const base = await agent.predict("short", questions);+ vi.spyOn(agent as any, "_systemOneMany").mockImplementation(async (states: unknown[]) => states.map(() => ({ ...base })));+ const result = await agent.predictLong(document, questions, { window: 20 });+ expect(result.answers.q).not.toHaveProperty("window");+ });++ it("preserves the replacement-batch fallback but does not excuse missing added answers", async () => {+ const { agent } = makeAgent();+ const base = await agent.predict("short", questions);+ vi.spyOn(agent, "predictBatch").mockImplementation(async (states) => states.map(() => structuredClone(base)));+ const result = await agent.predictLong(document, questions, { window: 20 });+ expect(result.answers.q.window?.index).toBe(0);+ await expect(agent.predictLong(document, { ...questions, extra: questions.q }, { window: 20 })).rejects.toThrow('answer "extra" is missing');+ });++ it("clamps requested windows and adjusts their stride before inference, with a bounded default batch", async () => {+ const { agent, batches } = makeAgent();+ const warnings = vi.spyOn(console, "warn").mockImplementation(() => {});+ const wide = { q: { type: "choice", instructions: "pick", criteria: Array.from({ length: 11 }, (_, i) => `label${i}`) } };+ let actualStates: unknown[] = [];+ const result = await agent.predictLong("x".repeat(150), wide, { window: 80, stride: 40,+ onPredictStart(ctx) { actualStates = [...ctx.states]; },+ });+ const size = result.answers.q.window!.token_end;+ expect(size).toBeLessThan(40);+ expect(actualStates.length).toBe(result.usage.windows);+ expect(batches.length).toBeGreaterThan(1);+ expect(Math.max(...batches.map((b) => b.inputIds.length))).toBeLessThan(result.usage.windows);+ expect(warnings).toHaveBeenCalledTimes(2);+ await expect(agent.predictLong(document, wide, { window: 80, stride: 81 })).rejects.toThrow("stride=81");+ });++ it.each(["clone", "probabilities", "confidence", "shared"])("drops attribution for %s answer edits", async (edit) => {+ const { agent } = makeAgent();+ const result = await agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {+ const first = ctx.results![0].answers as Record<string, any>;+ for (const row of ctx.results!) {+ const answers = row.answers as Record<string, any>;+ if (edit === "clone") answers.q = { ...answers.q };+ else if (edit === "probabilities") answers.q.probabilities = { yes: 1 };+ else if (edit === "confidence") answers.q.confidence = 0.123;+ else answers.q = first.q;+ }+ } });+ // End hooks that share the first unchanged answer retain that first answer's known+ // origin. Sharing at inference time, tested separately, has no unique origin.+ if (edit === "shared") expect(result.answers.q.window?.index).toBe(0);+ else expect(result.answers.q).not.toHaveProperty("window");+ });++ it("keeps attribution after action/reliability annotations and equal-value state replacements", async () => {+ const { agent } = makeAgent();+ const result = await agent.predictLong(document, questions, { window: 20,+ onPredictStart(ctx) { ctx.states = ctx.states.map((state) => `${state}`); },+ onPredictEnd(ctx) {+ for (const row of ctx.results!) {+ const answer = (row.answers as Record<string, any>).q;+ answer.action = { act_probability: 0.1 };+ answer.reliability = { note: "external" };+ }+ },+ });+ expect(result.answers.q.window?.index).toBe(0);+ expect(result.answers.q.action.act_probability).toBe(0.1);+ });++ it("omits all attribution when start hooks rewrite/reorder/remove windows", async () => {+ for (const rewrite of [(ctx: PredictContext) => { ctx.states.reverse(); },+ (ctx: PredictContext) => { ctx.states = ["replacement"]; },+ (ctx: PredictContext) => { ctx.states = []; }]) {+ const { agent } = makeAgent();+ vi.spyOn(console, "warn").mockImplementation(() => {});+ const result = await agent.predictLong(document, questions, { window: 20, onPredictStart: rewrite });+ if (!result.usage.windows) expect(result.answers).toEqual({});+ else expect(result.answers.q).not.toHaveProperty("window");+ }+ });++ it("accepts exactly one cached document, copies usage, and rejects malformed hook payloads", async () => {+ const { agent, batches } = makeAgent();+ const cached = await agent.predict("cached", questions);+ const warning = vi.spyOn(console, "warn").mockImplementation(() => {});+ const priorRuns = batches.length;+ for (const state of ["short", document]) {+ const result = await agent.predictLong(state, questions, { window: 20, onPredictStart: (ctx) => ctx.skip([cached as never]) });+ expect(result.usage.windows).toBe(0);+ expect(result).not.toBe(cached);+ expect(result.usage).not.toBe(cached.usage);+ expect(cached.usage).not.toHaveProperty("windows");+ await expect(agent.predictLong(state, questions, { window: 20, onPredictStart: (ctx) => ctx.skip([cached as never, cached as never]) })).rejects.toThrow("one result for the document");+ await expect(agent.predictLong(state, questions, { window: 20, onPredictStart: (ctx) => ctx.skip([{ model: "cache", answers: {}, usage: { input_tokens: "wrong", output_tokens: 0 } }]) })).rejects.toThrow("input_tokens");+ }+ expect(warning).toHaveBeenCalled();+ expect(batches).toHaveLength(priorRuns);+ });++ it("validates malformed result arrays and end-hook skip counts without masking the error", async () => {+ const { agent } = makeAgent();+ await expect(agent.predictLong("short", questions, { onPredictStart(ctx) { ctx.results = {} as never; } })).rejects.toThrow("array of results");+ const base = await agent.predict("short", questions);+ vi.spyOn(console, "warn").mockImplementation(() => {});+ await expect(agent.predictLong("short", questions, {+ onPredictStart(ctx) { ctx.skip([base as never]); },+ onPredictEnd(ctx) { ctx.results!.push(base as never); },+ })).rejects.toThrow("2 results");+ await expect(agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {+ (ctx.results![0].answers as Record<string, any>).q.type = "choice";+ (ctx.results![0].answers as Record<string, any>).q.choice = "yes";+ (ctx.results![0].answers as Record<string, any>).q.probabilities = { yes: 1 };+ } })).rejects.toThrow("inconsistent types");+ });++ it("keeps uniformly rewritten answer schemas while applying the original aggregation rule", async () => {+ const { agent } = makeAgent();+ const result = await agent.predictLong(document, { q: { type: "choice", instructions: "pick", criteria: ["a", "b"] } }, {+ window: 20, onPredictEnd(ctx) {+ for (const row of ctx.results!) Object.assign((row.answers as Record<string, any>).q,+ { type: "score", score: 1, legend: { "0": "low", "1": "high" } });+ },+ });+ expect(result.answers.q.type).toBe("score");+ expect(result.answers.q).not.toHaveProperty("window");+ });++ it("runs the budget guard after inference even with suppressed hook errors", async () => {+ const { agent, batches } = makeAgent();+ await expect(agent.predictLong(document, questions, { window: 40, hooksRaise: false,+ onPredictStart(ctx) { ctx.maxLen = 45; },+ })).rejects.toThrow("scan was sized for 40");+ expect(batches.length).toBeGreaterThan(0);+ const short = makeAgent();+ await expect(short.agent.predictLong("x".repeat(40), questions, { hooksRaise: false,+ onPredictStart(ctx) { ctx.maxLen = 45; },+ })).rejects.toThrow("scan was sized");+ expect(short.batches.length).toBeGreaterThan(0);+ });++ it("rejects aggregate usage overflow after individually valid window reports", async () => {+ const { agent } = makeAgent();+ await expect(agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {+ for (const result of ctx.results!) {+ (result.usage as Record<string, unknown>).input_tokens = Number.MAX_VALUE;+ }+ } })).rejects.toThrow("usage.input_tokens must be a finite non-negative number");+ });++ it("preserves own prototype-named keys in generic usage without changing its prototype", async () => {+ const { agent } = makeAgent();+ const result = await agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {+ for (const row of ctx.results!) {+ row.usage = { ...(row.usage as object), ...JSON.parse('{"__proto__":2,"constructor":{"seen":true}}') };+ }+ } });+ expect(Object.hasOwn(result.usage, "__proto__")).toBe(true);+ expect(result.usage["__proto__"]).toBe(result.usage.windows * 2);+ expect(result.usage["constructor"]).toEqual({ seen: true });+ expect(Object.getPrototypeOf(result.usage)).toBe(Object.prototype);+ });++ it("detects nested in-place question edits against the pre-hook deep snapshot", async () => {+ const { agent, batches } = makeAgent();+ const q: Record<string, QuestionDef> = { q: { type: "choice", instructions: "pick", criteria: { a: "A", b: "B" } } };+ await expect(agent.predictLong(document, q, { window: 40, hooksRaise: false, onPredictStart(ctx) {+ Object.assign((ctx.questions.q as QuestionDef).criteria as object, Object.fromEntries(Array.from({ length: 8 }, (_, i) => [`extra${i}`, "extra"])));+ } })).rejects.toThrow("scan was sized");+ expect(batches.length).toBeGreaterThan(0);+ });++ it("allows only uniformly removed start-added questions", async () => {+ const { agent } = makeAgent();+ const start = (ctx: PredictContext) => { ctx.questions = { ...ctx.questions, probe: questions.q }; };+ const result = await agent.predictLong(document, questions, { window: 20, onPredictStart: start, onPredictEnd(ctx) {+ for (const row of ctx.results!) delete (row.answers as Record<string, unknown>).probe;+ } });+ expect(Object.keys(result.answers)).toEqual(["q"]);+ await expect(agent.predictLong(document, questions, { window: 20, onPredictStart: start, onPredictEnd(ctx) {+ delete (ctx.results![0].answers as Record<string, unknown>).probe;+ } })).rejects.toThrow('answer "probe" is missing from 1 of 10');+ await expect(agent.predictLong(document, questions, { window: 20, onPredictEnd(ctx) {+ for (const row of ctx.results!) delete (row.answers as Record<string, unknown>).q;+ } })).rejects.toThrow('answer "q" is missing from 10 of 10');+ });++ it("uses a real OptionStabilityHook without leaking probe questions or losing spans", async () => {+ const { agent } = makeAgent(false, { hooks: new OptionStabilityHook({ accept: null, escalate: null, variants: "fast", seed: "long" }) });+ const result = await agent.predictLong(document, { q: { type: "choice", instructions: "pick", criteria: ["a", "b"] } }, { window: 20 });+ expect(Object.keys(result.answers)).toEqual(["q"]);+ expect(result.answers.q.window?.index).toBe(0);+ expect(result.answers.q).toHaveProperty("reliability");+ });++ it("keeps concurrent long and ordinary contexts independent", async () => {+ const { agent } = makeAgent();+ const [left, right, ordinary] = await Promise.all([+ agent.predictLong(document, questions, { window: 20, onPredictStart: async (ctx) => { await Promise.resolve(); ctx.states.reverse(); } }),+ agent.predictLong(document, questions, { window: 30 }),+ agent.predict("short", questions),+ ]);+ expect(left.answers.q).not.toHaveProperty("window");+ expect(right.answers.q.window?.token_end).toBe(30);+ expect(ordinary.usage).not.toHaveProperty("windows");+ });++ it("sums numeric usage, shallow-merges dictionaries, and preserves last other fields", async () => {+ const { agent } = makeAgent();+ const result = await agent.predictLong("x".repeat(30), questions, { window: 20, stride: 20, onPredictEnd(ctx) {+ Object.assign(ctx.results![0].usage as object, { custom: 1, truncated: true, options: { first: { total: 2, distinct: 1, tokens_per_option: 4 } }, last: ["first"] });+ Object.assign(ctx.results![1].usage as object, { custom: 2, truncated: false, options: { second: { total: 3, distinct: 2, tokens_per_option: 4 } }, last: [] });+ } });+ expect(result.usage).toMatchObject({ custom: 3, truncated: 1, options: { first: { total: 2 }, second: { total: 3 } }, last: [], windows: 2 });+ });+});diff --git a/laya-ts/tests/package-e2e.mjs b/laya-ts/tests/package-e2e.mjsindex 3310ce38..92034f8e 100644--- a/laya-ts/tests/package-e2e.mjs+++ b/laya-ts/tests/package-e2e.mjs@@ -107,7 +107,7 @@ test("the packed module installs and works in an external ESM TypeScript projectawait writeFile(join(consumerDir, "runtime.mjs"),`import assert from "node:assert/strict";-import { Agent, VERSION, predictTournament, DEFAULT_TOURNAMENT_GROUP,+import { Agent, Router, defaultTokenizer, VERSION, predictTournament, DEFAULT_TOURNAMENT_GROUP,OptionStabilityHook, calibrateReliability, decideReliability } from "laya-ts";let encoderCalls = 0;@@ -151,6 +151,21 @@ assert.equal(stable.answers.intent.reliability.n_variants, 3);assert.equal(stable.answers.intent.reliability.decision, null);const cuts = calibrateReliability([0.80001, 0.80002], [false, true], { targetAccuracy: 1 });assert.equal(decideReliability(0.80002, ...cuts), "ACCEPT");+const longAgent = new Agent({ provider, tok: {+ ...defaultTokenizer(),+ encode: (text) => Array.from(text, (c) => c.codePointAt(0) + 1000),+ decode: (ids) => String.fromCodePoint(...ids.map((id) => id - 1000)),+} });+const longRouter = new Router();+longRouter.attach("english", longAgent);+const long = await longRouter.predictLong("a long document ".repeat(8), {+ intent: { type: "choice", instructions: "Pick", criteria: ["refund", "other"] },+}, { model: "english", window: 40, stride: 20, batchSize: 2 });+assert(long.usage.windows > 1);+assert.equal(typeof long.usage.truncated, "number");+assert.equal(long.answers.intent.choice, "refund");+assert.equal(long.answers.intent.window.token_start, 0);+assert.equal(long.routing.model, "english");`,);await run(process.execPath, ["runtime.mjs"], consumerDir);@@ -168,6 +183,7 @@ assert.equal(decideReliability(0.80002, ...cuts), "ACCEPT");type SessionProvider,type SystemOneResult,type TournamentMeta,+ type LongResult,} from "laya-ts";const provider: SessionProvider = {@@ -205,6 +221,8 @@ async function reliability(): Promise<OptionStabilityReport | undefined> {return result.answers.intent.type === "choice" ? result.answers.intent.reliability : undefined;}void reliability;+const longPrediction: Promise<LongResult> = new Agent({ provider }).predictLong("short", questions);+void longPrediction;`,);await writeFile(diff --git a/laya-ts/tests/router-long.test.ts b/laya-ts/tests/router-long.test.tsnew file mode 100644index 00000000..fb22c005--- /dev/null+++ b/laya-ts/tests/router-long.test.ts@@ -0,0 +1,135 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { Router } from "../src/router.js";+import { clearDefaultHooks, defaultsAlreadyRan, setDefaultHooks } from "../src/hooks.js";++const questions = { q: { type: "noul", instructions: "Is this urgent?" } };+const result = (windows = 3) => ({ model: "test", answers: {}, usage: { input_tokens: 12, output_tokens: 0, windows } });+afterEach(() => { clearDefaultHooks(); vi.restoreAllMocks(); });++describe("Router.predictLong", () => {+ it("routes and loads once, forwards language and scan options, wraps the document", async () => {+ const calls: string[] = [];+ setDefaultHooks({ onPredictStart: () => { calls.push("default"); } });+ const predictLong = vi.fn(async (_s, _q, opts) => {+ expect(defaultsAlreadyRan(opts)).toBe(true);+ calls.push("scan");+ return result();+ });+ const loader = vi.fn(async () => ({ predictLong }));+ const router = new Router({ loader, hooks: {+ onRoute: () => { calls.push("route"); },+ onPredictStart: (ctx) => { expect(ctx.states).toHaveLength(1); calls.push("start"); },+ onPredictEnd: () => { calls.push("end"); },+ } });+ const out = await router.predictLong("Please refund the duplicate charge on my invoice", questions,+ { window: 80, stride: 40, batchSize: 2, aggregate: "auto" });+ expect(loader).toHaveBeenCalledTimes(1);+ expect(predictLong).toHaveBeenCalledTimes(1);+ expect(predictLong.mock.calls[0][2]).toMatchObject({ lang: "en", window: 80, stride: 40, batchSize: 2, aggregate: "auto" });+ expect(out.routing.model).toBe("english");+ expect(out.usage.windows).toBe(3);+ expect(calls).toEqual(["route", "default", "start", "scan", "end"]);+ });++ it("uses the post-start agent, state, questions and detected language", async () => {+ const original = { predictLong: vi.fn() };+ const changed = { predictLong: vi.fn(async () => result(2)) };+ const router = new Router({ loader: async () => original });+ const changedQuestions = { other: { type: "noul", instructions: "Changed?" } };+ await router.predictLong("hello", questions, { onPredictStart(ctx) {+ ctx.agent = changed;+ ctx.states = ["changed"];+ ctx.questions = changedQuestions;+ ctx.decision = { ...ctx.decision, detection: { language: "de" } };+ ctx.maxLen = 1; ctx.headMaxLen = 1;+ } });+ expect(original.predictLong).not.toHaveBeenCalled();+ expect(changed.predictLong).toHaveBeenCalledWith("changed", changedQuestions, expect.objectContaining({ lang: "de" }));+ expect(changed.predictLong.mock.calls[0]).toHaveLength(3);+ const opts = changed.predictLong.mock.calls[0][2] as Record<string, unknown>;+ expect(opts).not.toHaveProperty("maxLen");+ expect(opts).not.toHaveProperty("headMaxLen");+ });++ it("copies a skipped cached document and usage, warns and reports zero windows", async () => {+ const cached = { model: "cached", answers: {}, usage: { input_tokens: 8, output_tokens: 0 } };+ const predictLong = vi.fn();+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});+ const router = new Router({ loader: async () => ({ predictLong }) });+ const out = await router.predictLong("hello", questions, { onPredictStart: (ctx) => ctx.skip([cached]) });+ expect(predictLong).not.toHaveBeenCalled();+ expect(out).not.toBe(cached);+ expect(out.usage).not.toBe(cached.usage);+ expect(out.usage.windows).toBe(0);+ expect(cached.usage).not.toHaveProperty("windows");+ expect(cached).not.toHaveProperty("routing");+ expect(warn).toHaveBeenCalled();+ });++ it.each([{ results: [] }, { results: [result(), result()] }])("rejects ambiguous hook document results", async ({ results }) => {+ const router = new Router({ loader: async () => ({}) });+ await expect(router.predictLong("hello", questions, { hooksRaise: false,+ onPredictStart: (ctx) => ctx.skip(results),+ })).rejects.toThrow(/exactly one/);+ });++ it("propagates missing scan support and inference errors even when hooks are suppressed", async () => {+ const systemOne = vi.fn(async () => result());+ const router = new Router({ loader: async () => ({ systemOne }) });+ await expect(router.predictLong("hello", questions, { hooksRaise: false })).rejects.toThrow(/implement predictLong/);+ expect(systemOne).not.toHaveBeenCalled();+ router.attach("english", { predictLong: async () => { throw new Error("scan failed"); } });+ await expect(router.predictLong("hello", questions, { model: "english", hooksRaise: false })).rejects.toThrow("scan failed");+ });++ it("does not apply hook timeouts to inference", async () => {+ const router = new Router({ loader: async () => ({ predictLong: async () => {+ await new Promise((resolve) => setTimeout(resolve, 30));+ return result();+ } }) });+ await expect(router.predictLong("hello", questions, { hooksTimeout: 0.001, hooksRaise: true })).resolves.toMatchObject({ usage: { windows: 3 } });+ });++ it("keeps concurrent ordinary and long calls isolated, including reentrant ordinary prediction", async () => {+ const calls: string[] = [];+ const agent = {+ systemOne: vi.fn(async (state) => { calls.push(`ordinary:${state}`); return result(1); }),+ predictLong: vi.fn(async (state) => { calls.push(`long:${state}`); return result(4); }),+ };+ const router = new Router({ loader: async () => agent });+ const [long, ordinary] = await Promise.all([+ router.predictLong("long", questions, { onPredictStart: async () => { await router.predict("nested", questions); } }),+ router.predict("ordinary", questions),+ ]);+ expect(long.usage.windows).toBe(4);+ expect(ordinary.model).toBe("test");+ expect(calls.sort()).toEqual(["long:long", "ordinary:nested", "ordinary:ordinary"]);+ });++ it("validates the final document supplied by an end hook", async () => {+ const router = new Router({ loader: async () => ({ predictLong: async () => result() }) });+ await expect(router.predictLong("hello", questions, { hooksRaise: false, onPredictEnd(ctx) {+ ctx.results = [{ ...result(), usage: { input_tokens: 0, output_tokens: 0, windows: -1 } }];+ } })).rejects.toThrow(/windows/);+ });++ it("refuses an end-hook replacement that drops the promised routing decision", async () => {+ const router = new Router({ loader: async () => ({ predictLong: async () => result() }) });+ await expect(router.predictLong("hello", questions, { hooksRaise: false, onPredictEnd(ctx) {+ ctx.results = [result()];+ } })).rejects.toThrow(/routing decision/);+ });++ it("validates detection metadata in a hook-supplied routing decision", async () => {+ const router = new Router({ loader: async () => ({ predictLong: async () => result() }) });+ await expect(router.predictLong("hello", questions, { onPredictEnd(ctx) {+ (ctx.results![0].routing as Record<string, unknown>).detection = {};+ } })).rejects.toThrow(/routing decision/);+ });++ it.each([{ window: 0 }, { stride: 1.5 }, { batchSize: -1 }, { window: Number.MAX_SAFE_INTEGER + 1 }])("rejects invalid scan options before loading: %j", async (opts) => {+ const loader = vi.fn();+ await expect(new Router({ loader }).predictLong("hello", questions, opts)).rejects.toThrow();+ expect(loader).not.toHaveBeenCalled();+ });+});diff --git a/laya-ts/tests/types/predict-long.ts b/laya-ts/tests/types/predict-long.tsnew file mode 100644index 00000000..51f1cdea--- /dev/null+++ b/laya-ts/tests/types/predict-long.ts@@ -0,0 +1,31 @@+import {+ Agent, Router, type TokenizerLike, type LongPredictOptions, type LongResult,+ type RoutedLongResult, type SystemOneResult,+} from "../../src/index.js";++declare const agent: Agent;+declare const router: Router;+declare const encodeOnly: Omit<TokenizerLike, "decode">;+const oldTokenizer: TokenizerLike = encodeOnly;+const options: LongPredictOptions = { window: 80, stride: 40, batchSize: 2, aggregate: "auto", hooksTimeout: 1 };+const questions = { q: { type: "noul", instructions: "Is this urgent?" } };+const long: Promise<LongResult> = agent.predictLong("document", questions, options);+const routed: Promise<RoutedLongResult> = router.predictLong("document", questions, { ...options, lang: "en" });+const ordinary: Promise<SystemOneResult> = agent.predict("document", questions);+async function inspect() {+ const truncated: boolean | number | undefined = (await long).usage.truncated;+ const originalTruncated: boolean | undefined = (await ordinary).usage.truncated;+ const windowStart: number | undefined = (await long).answers.q.window?.token_start;+ return [truncated, originalTruncated, windowStart];+}+// @ts-expect-error long prediction uses the checkpoint budget, not ordinary per-call truncation+agent.predictLong("document", questions, { maxLen: 128 });+// @ts-expect-error headMaxLen does not belong to the long options+router.predictLong("document", questions, { headMaxLen: 64 });+// @ts-expect-error a window winner's confidence is not a calibrated document confidence gate+agent.predictLong("document", questions, { minConfidence: 0.9 });+// @ts-expect-error only the reference auto aggregator is supported+agent.predictLong("document", questions, { aggregate: "mean" });+void oldTokenizer;+void routed;+void inspect;