@autorag/librarian 2.13.7 → 2.13.8

package/README.md

@@ -207,6 +207,7 @@ AutoRAG Agent orchestrates five integrated subsystems:
    - **Jikji Find-First Discovery:** Local CLI-backed fast discovery answer packs.
    - **Everything File-Name Search (Windows):** The bundled [voidtools Everything](https://www.voidtools.com/) indexes file and folder names under your search roots so the agent finds files by name, extension, path, size, or date instantly (`everything_search`).
    - **FSearch File-Name Search (macOS/Linux):** [fsearch-cli](https://github.com/NomaDamas/fsearch-mac) (FSearch) keeps a live, per-workspace name index of your search roots so the agent finds files by name, extension, path, size, or date instantly (`fsearch_search`); without fsearch-cli installed it degrades to a slow filesystem walk.
+   - **Calculator:** Exact decimal arithmetic (40 significant digits, no floating-point drift) plus calendar and clock math — days between dates, date offsets with month-end clamping, weekdays, ISO weeks, business days with holidays, the current time, and DST-aware time zone conversion — through the `calculator` tool. The system prompt, including the fast-answer phase, orders the model to compute every number and date with it instead of in its head. It runs in-process, reads no files, and needs no configuration.
    - **Datasource Skills:** Federated retrieval across every configured external datasource.
 3. **Result Merger & Scope Narrowing:** Cross-method deduplication, score normalization, and ordinary query-scope narrowing.
 4. **Direct Evidence Reading (`bash`):** The agent directly opens and inspects promising files with `cat`, `grep`, or `find` to verify facts against ground truth.
@@ -286,6 +287,20 @@ autorag refresh
 autorag status
 ```
 
+### Indexing only when you want it (power and time schedule)
+
+Background indexing (`autorag watch`, auto-refresh, the fs watcher) can be limited by power source and local time. An explicit `autorag refresh` is never gated.
+
+```jsonc
+// ~/.autorag/config.json
+{ "refresh": { "schedule": { "power": "ac", "windows": ["22:00-07:00"], "days": ["mon","tue","wed","thu","fri"] } } }
+```
+
+- `power`: `any` (default) or `ac` (index only while plugged in; pauses on battery). An unknown power source (desktop, probe failure) counts as plugged in.
+- `windows`: local `HH:MM-HH:MM`, start inclusive, end exclusive; `22:00-07:00` wraps midnight and belongs to the day it starts on.
+- `days`: `sun`..`sat`. Omit for every day.
+- `autorag watch --power ac --window 22:00-07:00 --days mon,tue` overrides the config. `--once` while closed prints `skipped` and exits 0; a long-running watcher defers changes and indexes once the schedule opens.
+
 ### Excluding files and folders
 
 Leave generated workspaces or archives out when initializing:

package/dist/agent/agent.d.ts

@@ -14,12 +14,14 @@ import { type MinSyncSyncProgress, type MinSyncSyncResult, type MinSyncVectorMet
 import { type ParsedMirrorSyncOptions, type ParsedMirrorSyncResult } from "../mirror/sync.js";
 import { type DefaultParserRegistryOptions } from "../parser/index.js";
 import { RetrievalEngine } from "../retrieval/engine.js";
+import { type RecordCutOptions } from "../retrieval/record-cut.js";
 import { RetrievalMethodRegistry } from "../retrieval/registry.js";
 import type { DatasourceCatalogEntry } from "../retrieval/selection.js";
 import type { RetrievalDiagnostic, RetrievalOptions, RetrievalResult } from "../retrieval/types.js";
 import { type ConvertFilesDetails } from "./convert-tool.js";
 import { type DatasourceAgentSkill } from "./datasource-skill.js";
 import { type ScanDuplicateDocumentsDetails } from "./dupey-tool.js";
+import { type IndexSchedule, type ScheduleDecision } from "./index-schedule.js";
 import { type JevToolOptions } from "./jev-extension.js";
 import { type JikjiFindProviderResult } from "./jikji-find-tool.js";
 import { type PackagedAgentSkill } from "./packaged-skill.js";
@@ -65,6 +67,12 @@ export interface AutoRAGRefreshLimits {
      * disk and `cloud-evict-failed` is reported. `0` tries once. Default 3.
      */
     readonly cloudEvictRetries?: number;
+    /**
+     * When background indexing (auto-refresh, fs watch, `autorag watch`) may run: power (`any`/`ac`),
+     * local-time `windows` (`HH:MM-HH:MM`) and weekdays. Omitted = always.
+     * An explicit `refresh()` call is never gated. See {@link IndexSchedule}.
+     */
+    readonly schedule?: IndexSchedule;
 }
 /**
  * Hard caps on retrieval, baseline prefetch, and the candidate lists handed to
@@ -99,6 +107,13 @@ export interface AutoRAGRetrievalLimits {
         /** Max results rendered per baseline section. Default 100. */
         readonly sectionLimit?: number;
     };
+    /**
+     * Spread each search's hits across documents instead of cutting by chunk, so one long document cannot take
+     * every slot (PipesHub's FUSION_RECORD_CUT). Off unless `enabled` is true: when on, MinSync and the merger ask
+     * for `depth` x the requested count, a chunk shown earlier in the run is not resent, and each search result
+     * is held to `resultChars` with the budget split fairly across its chunks.
+     */
+    readonly recordCut?: RecordCutOptions;
 }
 export interface AutoRefreshOptions {
     readonly intervalMs: number;
@@ -215,6 +230,10 @@ export interface AutoRAGWatchRefreshOptions {
     readonly debounceMs?: number;
     readonly force?: boolean;
     readonly maxWatchers?: number;
+    /** Replaces the configured `refresh.schedule` for this watcher. */
+    readonly schedule?: IndexSchedule;
+    /** How often a watcher with a closed schedule re-checks it (default 60000). */
+    readonly scheduleRecheckMs?: number;
     /** Injectable watcher factory (defaults to a recursive fs.watch). Primarily for tests. */
     readonly watcherFactory?: WatcherFactory;
 }
@@ -727,6 +746,11 @@ export declare class AutoRAGAgent {
         immediate?: boolean;
     }): void;
     stopAutoRefresh(): void;
+    /**
+     * Whether the configured index schedule lets a background refresh run now. `override` replaces the
+     * configured schedule (CLI flags). Probes the power source only when the policy depends on it.
+     */
+    indexScheduleDecision(override?: IndexSchedule, now?: Date): Promise<ScheduleDecision>;
     private runAutoRefreshTick;
     searchDocuments(query: string, options?: RetrievalOptions): Promise<SearchDocumentsResponse>;
     /**
@@ -954,10 +978,16 @@ export declare class AutoRAGAgent {
     private defaultWatcherFactory;
     syncParsedMirrors(force?: boolean, options?: Pick<ParsedMirrorSyncOptions, "signal" | "onProgress" | "retrySkipped" | "onBatch" | "batchSize">): Promise<ParsedMirrorSyncResult>;
     /**
-     * Lightweight stat-only staleness scan used when `refresh` is called with
+     * Lightweight stat-only staleness scan used by status and when `refresh` is called with
      * methods that exclude parsed mirrors (e.g. only `datasources` or `jikji`).
      * Returns a zero-count `ParsedMirrorSyncResult` carrying fresh diagnostics
      * so the refresh result and status remain consistent.
+     *
+     * It never runs a duplicate scan: that reads every file under every root and costs seconds
+     * on a large corpus. It reuses the exclusions the last refresh recorded instead, so it
+     * differs from a fresh scan in two narrow ways: an indexed file that has since become an
+     * older exact duplicate is not reported (the next refresh drops it), and a newly added file
+     * that is already a duplicate is reported stale until the next refresh excludes it.
      */
     private scanMirrorStaleness;
     /** The machine's non-physical roots, resolved once; a probe failure reads as no roots, never an error. */

package/dist/agent/calculator-tool.d.ts

@@ -0,0 +1,39 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { Type } from "typebox";
+export declare const CALCULATOR_TOOL_NAME = "calculator";
+/** The standing order every prompt repeats: calculations belong to the tool, never to the model. */
+export declare const CALCULATOR_PROMPT_RULE = "Never do arithmetic, date, time, or time zone math yourself: use calculator for every sum, percentage, average, unit conversion, day count, date offset, weekday, and \"what time is it in\u2026\", and copy its result unchanged. The current date in your instructions is a starting point, not a substitute for the tool.";
+/** The fast phase forbids tools; this carves out the one that reads no sources and cannot slow the answer down. */
+export declare const CALCULATOR_FAST_PHASE_RULE = "calculator is allowed: Never do arithmetic, date, time, or time zone math yourself: use calculator for every sum, percentage, average, unit conversion, day count, date offset, weekday, and \"what time is it in\u2026\", and copy its result unchanged. The current date in your instructions is a starting point, not a substitute for the tool.";
+export interface CalculatorToolOptions {
+    /** The instant "now" and "today" mean. Tests pin it; the default reads the system clock on every call. */
+    readonly now?: () => Date;
+    /** Zone used when a call names none. Defaults to the host's zone. */
+    readonly hostTimeZone?: string;
+}
+declare const calculatorSchema: Type.TObject<{
+    operation: Type.TEnum<["evaluate", "now", "date_diff", "date_add", "date_info", "convert_timezone", "business_days_between", "add_business_days"]>;
+    expression: Type.TOptional<Type.TString>;
+    timeZone: Type.TOptional<Type.TString>;
+    toTimeZone: Type.TOptional<Type.TString>;
+    date: Type.TOptional<Type.TString>;
+    datetime: Type.TOptional<Type.TString>;
+    from: Type.TOptional<Type.TString>;
+    to: Type.TOptional<Type.TString>;
+    years: Type.TOptional<Type.TInteger>;
+    months: Type.TOptional<Type.TInteger>;
+    weeks: Type.TOptional<Type.TInteger>;
+    days: Type.TOptional<Type.TInteger>;
+    hours: Type.TOptional<Type.TInteger>;
+    minutes: Type.TOptional<Type.TInteger>;
+    seconds: Type.TOptional<Type.TInteger>;
+    holidays: Type.TOptional<Type.TArray<Type.TString>>;
+    inclusive: Type.TOptional<Type.TBoolean>;
+}>;
+export type CalculatorDetails = Record<string, string | number | boolean>;
+/**
+ * The model's calculator: exact decimal arithmetic and calendar/clock math. Language models miscount days,
+ * drop digits and forget daylight saving, so every numeric or date answer comes from this tool, not from the model.
+ */
+export declare function createCalculatorTool(options?: CalculatorToolOptions): AgentTool<typeof calculatorSchema, CalculatorDetails>;
+export {};

package/dist/agent/evidence-ledger.d.ts

@@ -77,6 +77,17 @@ export declare class EvidenceLedger {
      * at e1 would let a stale id silently resolve to a different chunk.
      */
     private lastOrdinal;
+    /** Ids whose text a search tool already put in front of the model during the current run. */
+    private readonly shown;
+    /** Whether a search already showed this evidence's text in the current run. */
+    hasShown(id: string): boolean;
+    /** Record that this evidence's text reached the model; returns whether it had already. */
+    markShown(id: string): boolean;
+    /**
+     * Start a run: nothing has been shown yet. A new question may follow a compaction that dropped the
+     * earlier tool output, so a repeat is only ever "already shown" within one run.
+     */
+    beginRun(): void;
     /** Record evidence and return its id. The same chunk always gets the same id. */
     register(input: LedgerEvidenceInput): string;
     /** Record one retrieval result as returned by `tool`; backend metadata is carried over. */

package/dist/agent/index-schedule.d.ts

@@ -0,0 +1,45 @@
+export type PowerPolicy = "any" | "ac";
+export type PowerSource = "ac" | "battery" | "unknown";
+export type ScheduleDay = "sun" | "mon" | "tue" | "wed" | "thu" | "fri" | "sat";
+export interface IndexSchedule {
+    /** `any` (default) ignores power; `ac` pauses while on battery and runs only when plugged in. */
+    readonly power?: PowerPolicy;
+    /** Local-time windows `HH:MM-HH:MM`; indexing is allowed inside any of them. Omitted = all day. */
+    readonly windows?: readonly string[];
+    /** Local weekdays indexing is allowed on. Omitted = every day. */
+    readonly days?: readonly ScheduleDay[];
+}
+export type ScheduleDenyReason = "battery" | "outside-window" | "outside-day";
+export type ScheduleDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: ScheduleDenyReason;
+};
+/** Validate and normalize a raw `refresh.schedule` value. Throws a plain Error naming the field. */
+export declare function validateIndexSchedule(raw: unknown): IndexSchedule;
+/** Decide whether a background refresh may run at `now` given the detected `source`. */
+export declare function evaluateIndexSchedule(schedule: IndexSchedule | undefined, now: Date, source: PowerSource): ScheduleDecision;
+/** Map raw probe output to a power source. Returns `unknown` for anything unrecognized. */
+export declare function parsePowerSourceOutput(platform: string, output: string): PowerSource;
+export interface PowerProbeDeps {
+    readonly platform?: NodeJS.Platform;
+    /** Run a command and return stdout. */
+    readonly run?: (command: string, args: readonly string[]) => Promise<string>;
+    readonly read?: (path: string) => Promise<string>;
+    readonly list?: (dir: string) => Promise<string[]>;
+}
+/** Detect the current power source. Never throws: any probe failure yields `unknown`. */
+export declare function detectPowerSource(deps?: PowerProbeDeps): Promise<PowerSource>;
+export interface CheckIndexScheduleOptions {
+    readonly now?: Date;
+    /** Replaces the platform power probe (tests). */
+    readonly detect?: () => Promise<PowerSource>;
+}
+/**
+ * Decide from a raw config object (`refresh.schedule`) whether a background refresh may run now. For hosts
+ * that run their own scheduler, such as the desktop app's OS job. Probes the power source only when the policy
+ * asks for AC. A malformed schedule fails open: a bad edit must not silently stop indexing, and the config
+ * loader already rejects it loudly where the user can see it.
+ */
+export declare function checkIndexSchedule(rawConfig: Record<string, unknown>, options?: CheckIndexScheduleOptions): Promise<ScheduleDecision>;

package/dist/agent/index.d.ts

@@ -1,5 +1,6 @@
 export type { AutoRAGAgentOptions, AutoRefreshOptions } from "./agent.js";
 export { AutoRAGAgent } from "./agent.js";
+export { CALCULATOR_FAST_PHASE_RULE, CALCULATOR_PROMPT_RULE, CALCULATOR_TOOL_NAME, type CalculatorDetails, type CalculatorToolOptions, createCalculatorTool, } from "./calculator-tool.js";
 export { CONVERT_FILES_TOOL_NAME, type ConvertFilesDetails, createConvertFilesTool, createListFileConversionsTool, type FileConversionProvider, LIST_FILE_CONVERSIONS_TOOL_NAME, } from "./convert-tool.js";
 export { buildDatasourceSkillsPrompt, createLoadDatasourceSkillTool, type DatasourceSkillProvider, datasourceSkillLocation, formatDatasourceSkillInvocation, LOAD_DATASOURCE_SKILL_TOOL_NAME, type LoadDatasourceSkillDetails, toDatasourceAgentSkill, } from "./datasource-skill.js";
 export { DECISION_PROVIDER_DEFAULT_MODELS, type DecisionModelRuntime, PiDecisionBackend, type PiDecisionBackendOptions, } from "./decision-backends.js";

package/dist/agent/result-render.d.ts

@@ -0,0 +1,43 @@
+import type { RecordCut } from "../retrieval/record-cut.js";
+import type { RetrievalResult } from "../retrieval/types.js";
+import type { EvidenceLedger } from "./evidence-ledger.js";
+/** One retrieved chunk as a search tool shows it to the model. */
+export interface EvidenceRow {
+    /** Ledger id, cited as `[eN]`. */
+    readonly id: string;
+    /** Everything after the id on the first line: source, score, location. */
+    readonly header: string;
+    readonly content: string;
+    /** A search earlier in this run already put this chunk's text in front of the model. */
+    readonly repeat: boolean;
+}
+export interface RenderedEvidence {
+    readonly text: string;
+    /** Ids whose text is in `text`; the caller marks these as shown so a later search does not resend them. */
+    readonly delivered: ReadonlySet<string>;
+}
+export declare const REPEAT_NOTE = "(already shown earlier in this run; text not repeated)";
+export declare const NOT_READ_NOTE = "(not read: result budget used up; narrow the query to read it)";
+/**
+ * Render search results for the model.
+ *
+ * Without a record cut every row is shown in full, exactly as before. With one,
+ * a chunk an earlier search of this run already showed is named without its
+ * text, and the rest share `recordCut.resultChars` max-min fairly: a long chunk
+ * is cut and says how much, a short one keeps all of it, and when the budget
+ * cannot give every chunk a useful share the lowest-ranked ones are listed as
+ * not read rather than every chunk being clipped to a stub.
+ */
+export declare function renderEvidenceRows(rows: readonly EvidenceRow[], recordCut: RecordCut | undefined): RenderedEvidence;
+/** Options a search tool takes for the record cut; absent means the legacy rendering. */
+export interface RecordCutToolOptions {
+    readonly recordCut?: RecordCut;
+}
+/**
+ * Register `results` in the ledger and render them. With a record cut, a chunk an earlier search of this run
+ * already showed is not resent, and only chunks whose text reached the model are marked as shown.
+ */
+export declare function registerAndRender(ledger: EvidenceLedger, tool: string, results: readonly RetrievalResult[], header: (result: RetrievalResult) => string, recordCut: RecordCut | undefined): {
+    readonly evidenceIds: string[];
+    readonly text: string;
+};

package/dist/agent/search-all-tool.d.ts

@@ -2,6 +2,7 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
 import { EvidenceLedger } from "./evidence-ledger.js";
+import { type RecordCutToolOptions } from "./result-render.js";
 import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_ALL_DOCUMENTS_TOOL_NAME = "search_all_documents";
 declare const searchAllSchema: Type.TObject<{
@@ -36,5 +37,5 @@ export interface SearchAllDocumentsDetails {
  * properties are not part of the schema and are never forwarded to the
  * provider — only `query`, `topK`, and `scope` are passed through.
  */
-export declare function createSearchAllDocumentsTool(provider: SearchAllDocumentsProvider, ledger?: EvidenceLedger): AgentTool<typeof searchAllSchema, SearchAllDocumentsDetails>;
+export declare function createSearchAllDocumentsTool(provider: SearchAllDocumentsProvider, ledger?: EvidenceLedger, options?: RecordCutToolOptions): AgentTool<typeof searchAllSchema, SearchAllDocumentsDetails>;
 export {};

package/dist/agent/search-minsync-tool.d.ts

@@ -2,6 +2,7 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { MinSyncVectorMethod } from "../minsync/method.js";
 import { EvidenceLedger } from "./evidence-ledger.js";
+import { type RecordCutToolOptions } from "./result-render.js";
 import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 export declare const SEARCH_MINSYNC_DOCUMENTS_TOOL_NAME = "semantic_search_local_docs";
 declare const searchMinSyncSchema: Type.TObject<{
@@ -23,5 +24,5 @@ export interface SearchMinSyncDocumentsDetails {
  * into an "unavailable" result: the error propagates with its own message and
  * the harness reports it as a failed tool call.
  */
-export declare function createSearchMinSyncDocumentsTool(getMethod: () => MinSyncVectorMethod, resolveScope?: (scope: string | undefined) => string | undefined, ledger?: EvidenceLedger): AgentTool<typeof searchMinSyncSchema, SearchMinSyncDocumentsDetails>;
+export declare function createSearchMinSyncDocumentsTool(getMethod: () => MinSyncVectorMethod, resolveScope?: (scope: string | undefined) => string | undefined, ledger?: EvidenceLedger, options?: RecordCutToolOptions): AgentTool<typeof searchMinSyncSchema, SearchMinSyncDocumentsDetails>;
 export {};

package/dist/agent/search-single-datasource-tool.d.ts

@@ -2,6 +2,7 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "typebox";
 import type { RetrievalDiagnostic, RetrievalResult } from "../retrieval/types.js";
 import { EvidenceLedger } from "./evidence-ledger.js";
+import { type RecordCutToolOptions } from "./result-render.js";
 import { type SearchDocumentRetrievalTraceResult } from "./search-documents.js";
 /**
  * Per-datasource search tools.
@@ -54,7 +55,7 @@ export interface SearchSingleDatasourceDetails {
     /** Top candidates in traceable shape (additive; used for the run's retrieval trace). */
     readonly results?: readonly SearchDocumentRetrievalTraceResult[];
 }
-export declare function createSingleDatasourceSearchTools(provider: SingleDatasourceSearchProvider, specs: readonly SingleDatasourceToolSpec[], ledger?: EvidenceLedger): AgentTool<typeof searchSingleDatasourceSchema, SearchSingleDatasourceDetails>[];
+export declare function createSingleDatasourceSearchTools(provider: SingleDatasourceSearchProvider, specs: readonly SingleDatasourceToolSpec[], ledger?: EvidenceLedger, options?: RecordCutToolOptions): AgentTool<typeof searchSingleDatasourceSchema, SearchSingleDatasourceDetails>[];
 declare const searchSingleDatasourceSchema: Type.TObject<{
     query: Type.TString;
     topK: Type.TOptional<Type.TInteger>;

package/dist/agent/watch-refresh.d.ts

@@ -24,6 +24,8 @@ export interface WatchRefreshDeps {
     readonly onLimit?: () => void;
 }
 export interface WatchRefreshHandle {
+    /** Schedule a (debounced) refresh as if a change had been seen, e.g. for a deferred initial refresh. */
+    trigger(): void;
     stop(): void;
 }
 export declare function createWatchRefresh(deps: WatchRefreshDeps): WatchRefreshHandle;

package/dist/calculator/civil.d.ts

@@ -0,0 +1,27 @@
+/** Proleptic Gregorian calendar arithmetic on whole days since 1970-01-01. No time zones, no `Date`. */
+export declare const MS_PER_DAY = 86400000;
+export declare const MIN_YEAR = 1;
+export declare const MAX_YEAR = 9999;
+export declare const WEEKDAYS: readonly ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+export interface Civil {
+    readonly y: number;
+    readonly m: number;
+    readonly d: number;
+}
+export declare function pad(value: number, width?: number): string;
+export declare function floorDiv(a: number, b: number): number;
+export declare function mod(a: number, b: number): number;
+export declare function isLeapYear(y: number): boolean;
+export declare function daysInMonth(y: number, m: number): number;
+export declare function isRealDate(y: number, m: number, d: number): boolean;
+/** Days since 1970-01-01 (Howard Hinnant's days_from_civil). */
+export declare function daysFromCivil(y: number, m: number, d: number): number;
+export declare function civilFromDays(days: number): Civil;
+/** 1 = Monday … 7 = Sunday. 1970-01-01 was a Thursday. */
+export declare function isoWeekday(days: number): number;
+export declare function dayOfYear(c: Civil): number;
+/** ISO 8601 week date, e.g. `2026-W45-7`. */
+export declare function isoWeekDate(days: number): string;
+/** Adds calendar months, clamping the day to the end of a shorter month (Jan 31 + 1 month = Feb 28). */
+export declare function addMonths(c: Civil, months: number): Civil;
+export declare function formatDate(days: number): string;

package/dist/calculator/decimal.d.ts

@@ -0,0 +1,47 @@
+/** Significant digits every intermediate result keeps. */
+export declare const WORK_DIGITS = 60;
+/** Significant digits a final result keeps. */
+export declare const RESULT_DIGITS = 40;
+export declare const MAX_INTEGER_EXPONENT = 10000;
+/** `n × 10^e`. Normalized: no trailing zeros in `n`, and zero is `{0n, 0}`. */
+export interface Dec {
+    readonly n: bigint;
+    readonly e: number;
+}
+/** Whether any step rounded or approximated, so the answer is not the exact mathematical value. */
+export interface Precision {
+    inexact: boolean;
+}
+export declare const ZERO: Dec;
+export declare const ONE: Dec;
+export type RoundingMode = "half-away" | "floor" | "ceil" | "trunc";
+export declare function digitCount(n: bigint): number;
+export declare function normalize(n: bigint, e: number): Dec;
+export declare function parseDecimal(text: string): Dec;
+export declare function fromInteger(value: number): Dec;
+/** A finite double rounded to 15 significant digits: transcendental results are only that accurate. */
+export declare function fromDouble(value: number, precision: Precision, name: string): Dec;
+export declare function toDouble(value: Dec): number;
+export declare function sign(value: Dec): -1 | 0 | 1;
+export declare function negate(value: Dec): Dec;
+export declare function isInteger(value: Dec): boolean;
+/** Drops every digit below `10^target`, rounding as `mode` says. */
+export declare function roundAtExponent(value: Dec, target: number, mode: RoundingMode, precision: Precision): Dec;
+/** Rounds to `digits` significant digits, half away from zero. */
+export declare function roundSignificant(value: Dec, digits: number, precision: Precision): Dec;
+export declare function compare(a: Dec, b: Dec): -1 | 0 | 1;
+export declare function add(a: Dec, b: Dec, precision: Precision): Dec;
+export declare function subtract(a: Dec, b: Dec, precision: Precision): Dec;
+export declare function multiply(a: Dec, b: Dec, precision: Precision): Dec;
+export declare function divide(a: Dec, b: Dec, precision: Precision): Dec;
+/** `a mod b` with the sign of `a`, like JavaScript's `%` but exact. */
+export declare function remainder(a: Dec, b: Dec, precision: Precision): Dec;
+/** Exact total of every term; only the final result is rounded. */
+export declare function sumExact(terms: readonly Dec[], precision: Precision): Dec;
+/** Square root to WORK_DIGITS digits; exact when the root is a terminating decimal. */
+export declare function squareRoot(value: Dec, precision: Precision): Dec;
+export declare function cubeRoot(value: Dec, precision: Precision): Dec;
+/** `base ^ exponent`. Integer exponents are exact up to WORK_DIGITS; fractional ones are double precision. */
+export declare function power(base: Dec, exponent: Dec, precision: Precision): Dec;
+/** Plain digits up to 10^40, scientific notation beyond (and below 1e-7), trailing zeros trimmed. */
+export declare function formatDecimal(value: Dec): string;

package/dist/calculator/errors.d.ts

@@ -0,0 +1,4 @@
+/** A calculation the calculator refuses: bad input or a result it cannot give honestly. The message is for the model. */
+export declare class CalculatorError extends Error {
+    constructor(message: string);
+}

package/dist/calculator/expression.d.ts

@@ -0,0 +1,11 @@
+import { digitCount, normalize, ZERO } from "./decimal.js";
+export declare const MAX_EXPRESSION_LENGTH = 4096;
+export interface ExpressionResult {
+    readonly expression: string;
+    readonly value: string | string[];
+    /** False when any step rounded or approximated, so the digits are the best 40-digit answer rather than the exact one. */
+    readonly exact: boolean;
+}
+/** Evaluates one expression, or one flat `[a, b, …]` list of expressions, with exact decimal arithmetic. */
+export declare function evaluateExpression(source: string): ExpressionResult;
+export { digitCount, normalize, ZERO };

package/dist/calculator/index.d.ts

@@ -0,0 +1,17 @@
+import { type CalculatorRequest, type Fields } from "./operations.js";
+export { CalculatorError } from "./errors.js";
+export { MAX_EXPRESSION_LENGTH } from "./expression.js";
+export type { CalculatorRequest, Fields } from "./operations.js";
+export declare const CALCULATOR_OPERATIONS: readonly ["evaluate", "now", "date_diff", "date_add", "date_info", "convert_timezone", "business_days_between", "add_business_days"];
+export interface CalculatorOptions {
+    /** The instant "now" and "today" mean. Defaults to the system clock. */
+    readonly now?: Date;
+    /** Zone used when the request names none. Defaults to the host's zone. */
+    readonly hostTimeZone?: string;
+}
+export interface CalculatorOutput {
+    readonly fields: Fields;
+    /** One `name: value` line per field: the text the model reads. */
+    readonly text: string;
+}
+export declare function calculate(request: CalculatorRequest, options?: CalculatorOptions): CalculatorOutput;

package/dist/calculator/operations.d.ts

@@ -0,0 +1,36 @@
+import { type Zone } from "./timezone.js";
+export type FieldValue = string | number | boolean;
+export type Fields = Record<string, FieldValue>;
+export interface CalculatorRequest {
+    readonly operation: string;
+    readonly expression?: string;
+    /** Zone a date or time is read in and shown in; for convert_timezone, the source zone. */
+    readonly timeZone?: string;
+    readonly toTimeZone?: string;
+    readonly date?: string;
+    readonly datetime?: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly years?: number;
+    readonly months?: number;
+    readonly weeks?: number;
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+    readonly holidays?: readonly string[];
+    readonly inclusive?: boolean;
+}
+export interface Clock {
+    readonly now: Date;
+    readonly zone: Zone;
+    readonly zoneSource: "requested" | "host default";
+}
+export declare function need<T>(operation: string, name: string, value: T | undefined): T;
+export declare function now(clock: Clock): Fields;
+export declare function dateDiff(request: CalculatorRequest, clock: Clock): Fields;
+export declare function dateAdd(request: CalculatorRequest, clock: Clock): Fields;
+export declare function convertTimeZone(request: CalculatorRequest, clock: Clock, sourceGiven: boolean): Fields;
+export declare function dateInfo(request: CalculatorRequest, clock: Clock): Fields;
+export declare function businessDaysBetween(request: CalculatorRequest, clock: Clock): Fields;
+export declare function addBusinessDays(request: CalculatorRequest, clock: Clock): Fields;

package/dist/calculator/temporal.d.ts

@@ -0,0 +1,18 @@
+import { type Zone } from "./timezone.js";
+/** A date with no time of day, or one instant on the timeline. */
+export type Temporal = {
+    readonly kind: "date";
+    readonly days: number;
+}
+/** `zoneless` marks a wall-clock time that was placed in the zone by assumption, not by its own offset. */
+ | {
+    readonly kind: "instant";
+    readonly epochMs: number;
+    readonly zoneless: boolean;
+};
+export declare function todayIn(zone: Zone, now: Date): number;
+export declare function parseTemporal(input: string, zone: Zone, now: Date): Temporal;
+/** Calendar day of a value: a date as is, an instant as the date on the wall clock in `zone`. */
+export declare function dayOf(value: Temporal, zone: Zone): number;
+/** The instant of a value: a date means midnight in `zone`. */
+export declare function instantOf(value: Temporal, zone: Zone): number;

package/dist/calculator/timezone.d.ts

@@ -0,0 +1,19 @@
+/** A UTC offset in force at every instant (`fixed`, seconds), or an IANA zone whose offset changes over time. */
+export interface Zone {
+    readonly name: string;
+    readonly fixed?: number;
+}
+export declare function formatOffset(seconds: number): string;
+export declare function fixedZone(offsetSeconds: number): Zone;
+export declare function parseZone(input: string): Zone;
+/** Seconds east of UTC in force at `epochMs`. */
+export declare function offsetAt(zone: Zone, epochMs: number): number;
+/** Wall-clock time in the zone, as milliseconds counted from 1970-01-01T00:00 with no zone attached. */
+export declare function toNaive(zone: Zone, epochMs: number): number;
+/**
+ * The instant a wall-clock time denotes. A time that occurs twice (clocks turn back) is its first
+ * occurrence; a time that never occurs (clocks jump ahead) moves forward by the length of the gap.
+ */
+export declare function fromNaive(zone: Zone, naiveMs: number): number;
+/** `YYYY-MM-DDTHH:MM:SS[.mmm]±HH:MM` for an instant in the zone. */
+export declare function formatIso(zone: Zone, epochMs: number): string;

package/dist/cli/commands/index.d.ts

@@ -4,6 +4,6 @@ import type { CommandContext } from "./types.js";
  * and MinSync indexes
  * (preserving `bin`, `datasources`, and the memory file). `rebuild` resets then re-runs a forced
  * refresh. Returns 0 on success, 2 for usage/decline errors, 1 for runtime
- * errors including path-escape guard violations.
+ * errors including path-escape guard violations, and 130/143 when a rebuild is stopped by SIGINT/SIGTERM.
  */
 export declare function runIndex(ctx: CommandContext): Promise<number>;

package/dist/cli/commands/lite-refresh.d.ts

@@ -5,6 +5,6 @@ import type { CommandContext } from "./types.js";
  * Delegates to the agent's refresh pipeline (parsed mirrors, MinSync,
  * datasources, Jikji) without requiring any model configuration.
  *
- * Exit codes: 0 on success, 2 on config error, 1 on runtime error.
+ * Exit codes: 0 on success, 2 on config error, 1 on runtime error, 130/143 when stopped by SIGINT/SIGTERM.
  */
 export declare function runLiteRefresh(ctx: CommandContext): Promise<number>;

package/dist/cli/commands/refresh.d.ts

@@ -8,6 +8,10 @@ import type { CommandContext } from "./types.js";
  *
  * `--method minsync,parsed` restricts which methods run. When omitted, all
  * methods run. Parsed mirrors are always synced when MinSync is selected.
+ *
+ * SIGINT and SIGTERM abort the refresh: the MinSync and parser children are stopped, the run is recorded as
+ * failed, and the command exits 130 or 143 like any process a signal ended. A long first index can run for
+ * hours, so an operator or a service manager needs to be able to stop it.
  */
 export declare function runRefresh(ctx: CommandContext): Promise<number>;
 /**

package/dist/cli/commands/watch.d.ts

@@ -5,6 +5,7 @@ import type { CommandContext } from "./types.js";
  * - default: long-running recursive fs watch with debounced refresh
  * - `--once`: single refresh tick (for cron / launchd / Task Scheduler)
  *
- * Exit codes: 0 on success, 2 on config error, 1 on runtime error.
+ * Exit codes: 0 on success, 2 on config error, 1 on runtime error, 130/143 when a one-shot tick is stopped by
+ * SIGINT/SIGTERM. The long-running watch handles those signals itself and exits 0.
  */
 export declare function runWatch(ctx: CommandContext): Promise<number>;