@autorag/librarian 2.12.0 → 2.13.0

package/dist/retrieval/chunk-location.d.ts

@@ -0,0 +1,28 @@
+/** Where a retrieved chunk sits inside its parsed document. Every field is measured, never model-written. */
+export interface ChunkLocation {
+    /** 1-based first line of the chunk in the parsed document. */
+    readonly lineStart: number;
+    /** 1-based last line of the chunk in the parsed document. */
+    readonly lineEnd: number;
+    /** Nearest article or heading line at or before the chunk's first line. */
+    readonly section?: string;
+}
+/**
+ * Find `chunk` in `document` by its non-blank lines (compared trimmed, so
+ * indentation and blank-line differences between the chunker's output and the
+ * file do not matter) and report the 1-based line range plus the section it
+ * sits in.
+ *
+ * Returns undefined unless the chunk matches exactly one place: a chunk the
+ * chunker rewrote (table flattening) or one that occurs twice has no single
+ * correct line, and reporting a guess would be worse than reporting nothing.
+ */
+export declare function locateChunk(document: string, chunk: string): ChunkLocation | undefined;
+/** One stable text form of a location, for tool output the model reads. Undefined when nothing is known. */
+export declare function describeLocation(location: {
+    readonly lineStart?: number;
+    readonly lineEnd?: number;
+    readonly section?: string;
+}): string | undefined;
+/** ` (lines 7-8, section "…")` for a retrieval result whose backend measured a location; empty otherwise. */
+export declare function locationSuffix(metadata: Readonly<Record<string, unknown>>): string;

package/dist/retrieval/fallback.d.ts

@@ -0,0 +1,24 @@
+import type { RetrievalMethod, RetrievalMethodDescriptor, RetrievalOptions, RetrievalResult } from "./types.js";
+/**
+ * One logical retrieval method that prefers its primary and degrades to a
+ * fallback only when the primary cannot run.
+ *
+ * Datasources used to register a hybrid method next to its lexical and semantic
+ * components and let the merger reconcile them. That ran the same backend
+ * several times and let the merger count a hybrid and its own component as
+ * independent corroboration. Registering one chain instead means the pipeline
+ * sees a single method per datasource: the hybrid when it works, a component
+ * only when it does not.
+ *
+ * The chain reports the primary's descriptor, so selection, diagnostics and
+ * surface grouping behave as if the primary were registered alone. A primary
+ * that answers with no hits is an answer, not a failure: the fallback is not
+ * consulted, because a lexical-only retry cannot find what a hybrid missed.
+ */
+export declare class FallbackRetrievalMethod implements RetrievalMethod {
+    private readonly primary;
+    private readonly fallbacks;
+    constructor(primary: RetrievalMethod, fallbacks: readonly RetrievalMethod[]);
+    describe(): RetrievalMethodDescriptor;
+    retrieve(query: string, options: RetrievalOptions): Promise<RetrievalResult[]>;
+}

package/dist/retrieval/index.d.ts

@@ -1,5 +1,6 @@
 export { bm25Scores, tokenize } from "./bm25.js";
 export { RetrievalEngine, type RetrievalEngineOptions } from "./engine.js";
+export { FallbackRetrievalMethod } from "./fallback.js";
 export type { MergeOptions } from "./merger.js";
 export { ParallelRetriever, ResultMerger } from "./merger.js";
 export { RetrievalMethodRegistry } from "./registry.js";

package/dist/retrieval/types.d.ts

@@ -14,11 +14,27 @@ export interface RetrievalMethodDescriptor {
     datasourceId?: string;
     tags?: readonly string[];
 }
+/**
+ * A fallback chain answered with a fallback because its primary method failed. `reason` is the primary's
+ * error verbatim, so the degraded surface can be reported like any other skipped method.
+ */
+export interface RetrievalFallbackEvent {
+    /** Name of the primary method that failed. */
+    method: string;
+    /** Name of the fallback that answered instead. */
+    fallback: string;
+    reason: string;
+}
 export interface RetrievalOptions {
     topK?: number;
     scope?: string;
     filters?: Record<string, unknown>;
     signal?: AbortSignal;
+    /**
+     * Owned by the retrieval pipeline, not by callers: invoked when a method answered through a fallback.
+     * Methods that wrap another method must not forward it.
+     */
+    onFallback?: (event: RetrievalFallbackEvent) => void;
 }
 export interface RetrievalMethod {
     describe(): RetrievalMethodDescriptor;

package/internal-skills/organize/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: organize
+description: Rules for acting on files and folders on disk — sort, move, copy, bulk-rename, rename by content, convert formats, create folder structures, or move to the trash. Plan every target path before changing anything, never overwrite or permanently delete, confirm with a listing, and report every change as old path → new path.
+license: Apache-2.0
+---
+
+# Organizing files and folders
+
+Use this skill when the user asks you to act on files or folders — tidy or sort
+a folder, move or copy files into folders, bulk or pattern rename, rename files
+according to what their content says, convert formats, create folder
+structures, archive, or move files to the trash. This is a file-organization
+task, not a document search: the answer is the change on disk, not information
+found in the files.
+
+## How to do it
+
+- Work with `bash` (`ls`, `mkdir`, `mv`, `cp`, and a bounded `find`). Read a
+  file (with `read` or `bash`) only when its content decides the new name or
+  folder, then carry the change out with `bash` or the file tools.
+- Use the converter tools for format conversions, the duplicate scan when the
+  request is about duplicates, and the file-name discovery tools to locate
+  files by name.
+- Do **not** search document contents, the user's datasources, or the web in
+  this turn: content retrieval and the web tools are not part of this task. The
+  turn prompt lists the exact tools to use and the ones to leave alone.
+
+## Rules
+
+- **Plan first.** List what you found, decide every target path, and check that
+  no two targets share a name and that no target already exists before you move
+  anything. Never overwrite an existing file.
+- **Touch only what the request names.** When the request does not name a
+  folder, ask which one instead of guessing, unless the conversation already
+  says.
+- **Never delete permanently** — no `rm`, `rmdir`, `unlink`, `find -delete`,
+  `shred`, or PowerShell `Remove-Item`. Move what must go to the OS trash
+  instead (macOS `/usr/bin/trash`, Linux `gio trash`, Windows Recycle Bin).
+- **Confirm afterwards.** List the destination folder to check the changes
+  really happened.
+- **Finish with a report**, as your final message and with no tool call: every
+  change as old path → new path (one per line), what you skipped and why, and
+  anything that still needs the user. Write in the language of the request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autorag/librarian",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Personal librarian agent for office work on the Pi framework, with pluggable retrieval methods",
   "license": "Apache-2.0",
   "repository": {
@@ -31,6 +31,7 @@
   "files": [
     "dist",
     "skills",
+    "internal-skills",
     "README.md",
     "NOTICE",
     "licenses",

package/skills/autorag/SKILL.md

@@ -123,14 +123,21 @@ autorag evidence <sessionId> --result 1 --json
 ```
 
 The response includes the original source, retrieval method, stable evidence
-ID, raw excerpt/content, and any available `chunkIndex`, `lineNumber`,
-`retrievalResultId`, and metadata. Omit `--result` to inspect every result in
+ID, raw excerpt/content, and any available `chunkIndex`, `lineNumber` and
+`lineEnd` (the chunk's line range in the parsed document), `section` (the
+article or heading it sits in), `retrievalResultId`, and metadata. Omit `--result` to inspect every result in
 the session. Prefer this command whenever the caller wants detailed chunk text
 rather than only the curated summary.
 
 - `--scope` narrows datasource retrieval to a requested sub-path (ordinary
   per-query filtering).
 - `--json` is required for programmatic consumption.
+- Each search result carries `locations` (`lineStart`, `lineEnd`, `section`)
+  when the harness measured where its evidence sits in the parsed document. Quote
+  those, not line numbers or counts written in the answer prose; a
+  `line-reference-unverified` diagnostic (with `--debug`) flags prose line
+  numbers no cited evidence covers. Locations are absent for chunks the chunker
+  rewrote (such as flattened tables).
 - `--debug` is required for `sessionId` and diagnostics in search output.
 - `autorag evidence` is the detailed source/chunk inspection path.
 
@@ -152,13 +159,17 @@ default, OpenRouter), Jev first routes the question:
   verification, and reports every change as old path → new path.
 - Anything else that needs no retrieval (commit, push, open a PR, run a build)
   is carried out in one tool turn the same way.
-- Private-data questions use local search; the agent decides on web search
-  after the fast answer.
+- Private-data questions use local search. Questions about public facts that may
+  be recent or have changed can use the public web: Jev picks the web in the
+  same check as the registered connections, one web search runs per search
+  query before the fast answer, and the fast phase may also call `web_search`
+  itself when the baseline lacks the answer.
 - A multi-part question is split into up to five parallel search queries.
 - On local search, Jev also picks which registered datasources (Slack,
-  Discord, KakaoTalk, email, ...) to search before the fast answer, from each
-  datasource's description and where similar past questions were answered;
-  their chunks are reranked together with local file evidence.
+  Discord, KakaoTalk, email, ...) to search before the fast answer — and
+  whether to search the public web — from each description and where similar
+  past questions were answered; their hits are reranked together with local
+  file evidence.
 
 After the fast answer, Jev ends the run if the answer is complete and
 evidence-backed. So `results` may come straight from the fast answer, with no

package/skills/autorag-setup/SKILL.md

@@ -239,11 +239,13 @@ fast and multi-part questions thorough.
 - **Jev** (`jev`, default `{ "backend": "dazzi" }` when signed in to Dazzi
   Models, else `{ "backend": "openrouter" }`; model `jev-1.13` on Dazzi,
   `typesafe/jev-1.13` on OpenRouter) runs before the fast answer. It routes each question to
-  local search, a direct answer (general knowledge or small
-  talk skips retrieval entirely), `organize` (moving, renaming, converting, or
-  sorting files and folders), `extra` (any other action that needs no
-  retrieval, such as committing code), or the `config` branch, and decides
-  whether to decompose it. On
+  local search (everything needing more information),
+  `organize` (moving, renaming, converting, or
+  sorting files and folders), `extra` (a knowledge answer, or any other action that needs no
+  retrieval, such as committing code: one turn with every tool), or the `config`
+  branch, and decides
+  whether to decompose it. A non-local branch only wins above a 0.75 confidence
+  floor; anything weaker stays on local search. On
   local search it also decides, per registered datasource, whether to search
   it before the fast answer, using each datasource's `description` and where
   similar past questions were answered (retrieval memory). When setting up a