@draht/rlm 2026.7.12-1

package/README.md

@@ -0,0 +1,167 @@
+# @draht/rlm
+
+Recursive Language Models (RLM) — the inference-time scaffold from Zhang,
+Kraska, Khattab (2026), *Recursive Language Models* (arXiv:2512.24601):
+root-LLM-produces-code → REPL-executes → truncated-stdout → history-append →
+FINAL-check. Lets a root model answer questions about inputs far larger than
+its own context window by writing Python that inspects, chunks, and searches
+the content from inside a sandboxed REPL, optionally recursing into
+sub-`llm_query` calls, instead of the caller ever loading the raw content
+into a single prompt.
+
+## When to prefer RLM over a normal agent read
+
+Reach for RLM when the input genuinely doesn't fit the model's context
+window, or fits only by truncating away content that might matter:
+
+- A log file, dataset dump, or exported knowledge base that's tens or
+  hundreds of megabytes — orders of magnitude past any model's window.
+- A directory/glob of source files too large to read whole without evicting
+  earlier conversation context.
+- Any case where you'd otherwise have to guess which prefix/suffix/sample of
+  the input to truncate to, and a wrong guess means missing the answer.
+
+Don't reach for RLM when the input already fits comfortably in the model's
+context window — a normal read is faster, cheaper, and easier to debug. RLM
+trades one direct read for several extra model round trips (see below); that
+trade only pays off when the alternative is truncation-induced information
+loss, not just "this file is somewhat long."
+
+## Cost envelope
+
+A normal read is one call: the whole input goes into the prompt, the model
+answers once. RLM is **not** universally cheaper than that — it's a
+different trade:
+
+- The root model makes one call per REPL step (a handful to a few dozen
+  steps for a typical run), and each step's Python may itself call
+  `llm_query(...)`, which is a *second* model call (typically to a smaller
+  "rlm-sub" role — see `router-session.ts`'s `RlmRole`) that also costs
+  money.
+- So RLM's total cost is `sum(root-step costs) + sum(sub-call costs)` versus
+  a baseline's single call. RLM wins when the baseline's single call would
+  otherwise require either failing outright (input doesn't fit at all) or
+  paying for a much larger context window / re-reading the input multiple
+  times across a conversation to compensate for truncation — not in the
+  general case.
+- **Don't guess — measure.** `src/cost-comparison.ts`'s `compareCost()`
+  computes both numbers for one trajectory: `rlmCostUsd` from the trajectory's
+  own logged cost entries (`readCostLog`/`getSessionCosts` from
+  `@draht/router`, filtered by `trajectoryId`), and `baselineCostUsd` as the
+  estimated cost (via `@draht/router`'s `estimateCost`) of a single call that
+  truncates the same content down to the target model's context window
+  (first-N-characters-that-fit — a simple, named strategy, not a claim that
+  it's the smartest possible truncation). Run it against a real trajectory ID
+  before assuming RLM is the cheaper (or more expensive) option for your
+  specific input/model pair; `.draht/rlm/cost-comparison-report.json` is
+  where a comparison run writes its report.
+
+## Observability: trajectory logs & replay
+
+Every `createRouterBackedSession` run writes a newline-delimited JSON
+trajectory log to `.draht/rlm/<trajectoryId>.jsonl` (`src/trajectory.ts`) —
+one `TrajectoryStepEntry` per REPL step (its code, truncated stdout, error if
+any, the sub-calls it triggered, and that step's own cost) plus one terminal
+`TrajectoryFinalEntry` once the session resolves. `trajectoryId` is the same
+ID already used to tag the session's `@draht/router` cost-log entries, so a
+trajectory's logs and its cost accounting always correlate by the same key.
+
+Because the whole run is on disk, it can be reconstructed with **zero LLM
+calls**:
+
+```bash
+draht rlm replay <trajectory-id>
+```
+
+reads the JSONL log via `readTrajectory()` and prints the final answer (add a
+verbose flag for the full step-by-step trace) — no router, no model, no
+network access on that code path at all. Useful for auditing what a session
+actually did, debugging a run that didn't reach `FINAL`, or reviewing cost
+without re-running anything.
+
+The `test/s-niah.test.ts` regression suite exercises recall at 10x and 100x a
+mocked root model's context window (synthetic needle-in-haystack at ~4M and
+~40M characters, against a scripted mock `rootLlm` — no real model calls) as
+a standing check that the scaffold still finds a planted needle at scale.
+
+## Worked example
+
+Say `deploy.log` is a 40 MB deployment log and you need to know what caused
+an outage buried somewhere in it — too large to paste into a normal prompt.
+The same question, three ways:
+
+**Interactive `/rlm` command** (inside a `draht` session):
+
+```
+/rlm deploy.log What caused the outage around the 03:00 UTC deploy?
+```
+
+**`draht rlm` CLI** (scriptable, one-shot):
+
+```bash
+draht rlm --input ./deploy.log --query "What caused the outage around the 03:00 UTC deploy?"
+```
+
+**`rlm_query` tool** (an agent defers the read itself, mid-session, instead
+of loading the log into its own context):
+
+```json
+{
+  "tool": "rlm_query",
+  "input": {
+    "input": "deploy.log",
+    "query": "What caused the outage around the 03:00 UTC deploy?"
+  }
+}
+```
+
+All three share the same path under the hood: `parseInputArg`/`loadInput`
+resolve `deploy.log` into content, `createRouterBackedSession` wraps it as
+the REPL's `context` with the question prepended as a header, and the root
+model writes Python to grep/chunk/search `context` — recursing into
+`llm_query` sub-calls for individual chunks as needed — until it calls
+`FINAL(...)`/`FINAL_VAR(...)` with the answer. `--input`/`input` also accepts
+a glob (`"src/**/*.ts"`), an `http(s)://` URL, or `knowledge:<client-slug>`
+for a named client knowledge base.
+
+To check whether that particular run was worth it cost-wise, take the
+`trajectoryId` of its `.draht/rlm/<trajectoryId>.jsonl` log (or the matching
+`trajectoryId` field in `.draht/cost-log.jsonl`) and feed it into
+`compareCost()` (see Cost envelope, above) rather than assuming either
+direction.
+
+## Development
+
+```bash
+npm install          # from repo root, resolves this workspace package
+cd packages/rlm
+npx tsc --noEmit     # typecheck
+npm test             # vitest
+```
+
+## Package layout
+
+- `src/session.ts` — `RlmSession` root loop (step/run, `FINAL`/`FINAL_VAR`
+  sentinels, constant-size history).
+- `src/router-session.ts` — `createRouterBackedSession`, the production
+  `@draht/router`-backed factory (prompt-tier selection, cost logging,
+  trajectory logging).
+- `src/trajectory.ts` — trajectory JSONL append/read (this phase).
+- `src/cost-comparison.ts` — RLM-vs-baseline cost harness (this phase).
+- `src/loaders.ts` — `--input`/`/rlm <input>` source loaders (file, glob,
+  URL, `knowledge:<slug>`).
+- `src/prompts.ts` — tiered system-prompt templates, selected by the root
+  model's context window.
+- `python/repl_driver.py` — the sandboxed Python REPL driver.
+- `packages/coding-agent/src/rlm-cli.ts` — `draht rlm` CLI subcommand.
+- `packages/rlm-agent/` — `/rlm` command + `rlm_query` tool extension for
+  normal agent sessions.
+
+## AGENTS.md
+
+RLM is a cross-cutting coding-agent capability, not a property of any single
+generated project's stack — none of `packages/templates/src/*.md`'s
+per-stack templates (Astro, Go/gRPC, SST TypeScript) is the right home for a
+"when to use RLM" note, and this repo's own root `AGENTS.md` is a
+contributor-workflow doc, not a feature reference. This README is the
+primary documentation surface for RLM; no template changes were made.

package/dist/cost-comparison.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Cost-comparison harness: RLM trajectory cost vs. a truncate-and-single-call
+ * baseline for the same task.
+ *
+ * `rlmCostUsd` is the real, already-incurred cost of a trajectory recovered
+ * from `@draht/router`'s cost log (every root + sub call `createRouterBackedSession`
+ * logs is tagged with one `trajectoryId` -- see router-session.ts). There is
+ * nothing to "compare" about that half; it's just a sum-and-filter over
+ * already-logged `CostEntry` rows.
+ *
+ * `baselineCostUsd` is necessarily an *estimate*, not a measurement: it models
+ * the cost of the simplest plausible non-RLM alternative for an oversize
+ * task -- truncate the context down to whatever fits the target model's
+ * context window, then make one single call -- and prices that hypothetical
+ * call via `@draht/router`'s `estimateCost`. The specific truncation strategy
+ * modeled here is deliberately the crudest one: keep the first N characters
+ * of the context that fit the window (a `CHARS_PER_TOKEN` heuristic converts
+ * the token-denominated `contextWindow` into a character budget). A smarter
+ * baseline (e.g. picking the *most relevant* N characters via embedding
+ * search, or summarizing before truncating) would likely produce different
+ * numbers -- that's out of scope here. This harness answers "what would the
+ * cheapest naive single-call alternative have cost", not "what is the best
+ * possible non-RLM approach". See
+ * .planning/phases/30-eval-observability-docs/30-01-PLAN.md, Architecture
+ * section 3, and its Risks section.
+ */
+/** Which target model the truncate-and-single-call baseline is priced against. */
+export interface BaselineModel {
+    provider: string;
+    modelName: string;
+    /** Context window, in tokens -- used to compute how much of the context the baseline call could fit after truncation. */
+    contextWindow: number;
+}
+/** Result of comparing one RLM trajectory's real cost against a truncate-and-single-call baseline for the same task. */
+export interface CostComparisonResult {
+    /**
+     * Identifies which task/trajectory this comparison covers. There is no
+     * separate task-name concept tracked elsewhere in this codebase, so this
+     * is the `trajectoryId` itself -- callers that want a human-readable label
+     * should track that mapping themselves.
+     */
+    task: string;
+    /** Sum of every cost-log entry (root call + every `llm_query` sub-call) tagged with this trajectoryId. */
+    rlmCostUsd: number;
+    /**
+     * Estimated cost of truncating the context to fit `model`'s window and
+     * making one single call instead (see the module doc for the exact
+     * truncation approach modeled).
+     */
+    baselineCostUsd: number;
+    /** Number of root-LLM steps the RLM trajectory took (one "rlm-root"-role cost entry per step -- see router-session.ts's `rootLlm`). */
+    rlmSteps: number;
+    /** The full (untruncated) context length, in characters, the RLM trajectory operated over. */
+    contextLengthChars: number;
+}
+/**
+ * Compares an already-run RLM trajectory's real cost (read back from the
+ * cost log at `costLogPath`, filtered by `trajectoryId`) against the
+ * estimated cost of a truncate-and-single-call baseline for the same task:
+ * truncate `contextLengthChars` down to whatever fits `model.contextWindow`
+ * (first-N-characters, converted via `CHARS_PER_TOKEN`), then price one call
+ * to `model` via `@draht/router`'s `estimateCost`.
+ *
+ * Doesn't run anything itself -- the RLM trajectory must already have run
+ * (via `createRouterBackedSession`, logging its cost entries under
+ * `costLogPath`) before calling this; the baseline call is hypothetical and
+ * never actually dispatched. This function is pure arithmetic over its
+ * inputs plus the cost log, and makes no claim about which side is cheaper --
+ * that depends entirely on the task.
+ */
+export declare function compareCost(trajectoryId: string, contextLengthChars: number, model: BaselineModel, costLogPath?: string): CostComparisonResult;
+/**
+ * Writes a `CostComparisonResult` to disk as the "eval report" R30-EVAL.3
+ * asks for, creating parent directories as needed. Defaults to
+ * `.draht/rlm/cost-comparison-report.json` (relative to `process.cwd()`),
+ * mirroring `trajectory.ts`'s `DEFAULT_LOG_DIR` convention -- callers that
+ * don't want to touch that real location (e.g. tests) should pass an
+ * explicit `reportPath` instead.
+ */
+export declare function writeCostComparisonReport(result: CostComparisonResult, reportPath?: string): void;
+//# sourceMappingURL=cost-comparison.d.ts.map

package/dist/cost-comparison.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-comparison.d.ts","sourceRoot":"","sources":["../src/cost-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,yHAAyH;IACzH,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,wHAAwH;AACxH,MAAM,WAAW,oBAAoB;IACpC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,uIAAuI;IACvI,QAAQ,EAAE,MAAM,CAAC;IACjB,8FAA8F;IAC9F,kBAAkB,EAAE,MAAM,CAAC;CAC3B;AAuBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAC1B,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,MAAM,EAC1B,KAAK,EAAE,aAAa,EACpB,WAAW,CAAC,EAAE,MAAM,GAClB,oBAAoB,CAwBtB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAIjG"}

package/dist/cost-comparison.js

@@ -0,0 +1,93 @@
+/**
+ * Cost-comparison harness: RLM trajectory cost vs. a truncate-and-single-call
+ * baseline for the same task.
+ *
+ * `rlmCostUsd` is the real, already-incurred cost of a trajectory recovered
+ * from `@draht/router`'s cost log (every root + sub call `createRouterBackedSession`
+ * logs is tagged with one `trajectoryId` -- see router-session.ts). There is
+ * nothing to "compare" about that half; it's just a sum-and-filter over
+ * already-logged `CostEntry` rows.
+ *
+ * `baselineCostUsd` is necessarily an *estimate*, not a measurement: it models
+ * the cost of the simplest plausible non-RLM alternative for an oversize
+ * task -- truncate the context down to whatever fits the target model's
+ * context window, then make one single call -- and prices that hypothetical
+ * call via `@draht/router`'s `estimateCost`. The specific truncation strategy
+ * modeled here is deliberately the crudest one: keep the first N characters
+ * of the context that fit the window (a `CHARS_PER_TOKEN` heuristic converts
+ * the token-denominated `contextWindow` into a character budget). A smarter
+ * baseline (e.g. picking the *most relevant* N characters via embedding
+ * search, or summarizing before truncating) would likely produce different
+ * numbers -- that's out of scope here. This harness answers "what would the
+ * cheapest naive single-call alternative have cost", not "what is the best
+ * possible non-RLM approach". See
+ * .planning/phases/30-eval-observability-docs/30-01-PLAN.md, Architecture
+ * section 3, and its Risks section.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { estimateCost, readCostLog } from "@draht/router";
+/**
+ * Rough heuristic: ~4 characters per token for English-ish text. This is the
+ * same order-of-magnitude approximation used broadly across LLM tooling when
+ * an exact tokenizer isn't wired in for a given model -- it is NOT
+ * model-exact, and the `baselineCostUsd` this produces should be read as
+ * "same ballpark", not "precise". See the module doc above and the Risks
+ * section of the phase 30 plan.
+ */
+const CHARS_PER_TOKEN = 4;
+/**
+ * Fixed assumed output length (tokens) for the baseline's single call -- a
+ * plausible "here's the answer" response size. Deliberately not modeled
+ * per-task: this harness needs a reasonable, explicitly-documented constant,
+ * not a task-specific prediction of how long an answer would be.
+ */
+const BASELINE_OUTPUT_TOKENS = 500;
+/** Default path the "eval report" JSON is written to/read from, relative to `process.cwd()`. */
+const DEFAULT_REPORT_PATH = ".draht/rlm/cost-comparison-report.json";
+/**
+ * Compares an already-run RLM trajectory's real cost (read back from the
+ * cost log at `costLogPath`, filtered by `trajectoryId`) against the
+ * estimated cost of a truncate-and-single-call baseline for the same task:
+ * truncate `contextLengthChars` down to whatever fits `model.contextWindow`
+ * (first-N-characters, converted via `CHARS_PER_TOKEN`), then price one call
+ * to `model` via `@draht/router`'s `estimateCost`.
+ *
+ * Doesn't run anything itself -- the RLM trajectory must already have run
+ * (via `createRouterBackedSession`, logging its cost entries under
+ * `costLogPath`) before calling this; the baseline call is hypothetical and
+ * never actually dispatched. This function is pure arithmetic over its
+ * inputs plus the cost log, and makes no claim about which side is cheaper --
+ * that depends entirely on the task.
+ */
+export function compareCost(trajectoryId, contextLengthChars, model, costLogPath) {
+    const entries = readCostLog(costLogPath).filter((entry) => entry.trajectoryId === trajectoryId);
+    const rlmCostUsd = entries.reduce((sum, entry) => sum + entry.estimatedCostUsd, 0);
+    // Exactly one "rlm-root"-role cost entry is logged per root-LLM step (see
+    // router-session.ts's `logRouterCall("rlm-root", ...)` inside `rootLlm`) --
+    // sub-calls (role "rlm-sub") don't count as separate steps.
+    const rlmSteps = entries.filter((entry) => entry.role === "rlm-root").length;
+    const truncatedInputTokens = Math.min(model.contextWindow, Math.ceil(contextLengthChars / CHARS_PER_TOKEN));
+    const baselineCostUsd = estimateCost(model.provider, model.modelName, truncatedInputTokens, BASELINE_OUTPUT_TOKENS, 0);
+    return {
+        task: trajectoryId,
+        rlmCostUsd,
+        baselineCostUsd,
+        rlmSteps,
+        contextLengthChars,
+    };
+}
+/**
+ * Writes a `CostComparisonResult` to disk as the "eval report" R30-EVAL.3
+ * asks for, creating parent directories as needed. Defaults to
+ * `.draht/rlm/cost-comparison-report.json` (relative to `process.cwd()`),
+ * mirroring `trajectory.ts`'s `DEFAULT_LOG_DIR` convention -- callers that
+ * don't want to touch that real location (e.g. tests) should pass an
+ * explicit `reportPath` instead.
+ */
+export function writeCostComparisonReport(result, reportPath) {
+    const path = resolve(reportPath ?? DEFAULT_REPORT_PATH);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+}
+//# sourceMappingURL=cost-comparison.js.map

package/dist/cost-comparison.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-comparison.js","sourceRoot":"","sources":["../src/cost-comparison.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAiC1D;;;;;;;GAOG;AACH,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAEnC,gGAAgG;AAChG,MAAM,mBAAmB,GAAG,wCAAwC,CAAC;AAErE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,WAAW,CAC1B,YAAoB,EACpB,kBAA0B,EAC1B,KAAoB,EACpB,WAAoB;IAEpB,MAAM,OAAO,GAAG,WAAW,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,YAAY,KAAK,YAAY,CAAC,CAAC;IAChG,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC;IACnF,0EAA0E;IAC1E,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,MAAM,CAAC;IAE7E,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,CAAC,kBAAkB,GAAG,eAAe,CAAC,CAAC,CAAC;IAC5G,MAAM,eAAe,GAAG,YAAY,CACnC,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,SAAS,EACf,oBAAoB,EACpB,sBAAsB,EACtB,CAAC,CACD,CAAC;IAEF,OAAO;QACN,IAAI,EAAE,YAAY;QAClB,UAAU;QACV,eAAe;QACf,QAAQ;QACR,kBAAkB;KAClB,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAA4B,EAAE,UAAmB;IAC1F,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC,CAAC;IACxD,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,aAAa,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACtE,CAAC","sourcesContent":["/**\n * Cost-comparison harness: RLM trajectory cost vs. a truncate-and-single-call\n * baseline for the same task.\n *\n * `rlmCostUsd` is the real, already-incurred cost of a trajectory recovered\n * from `@draht/router`'s cost log (every root + sub call `createRouterBackedSession`\n * logs is tagged with one `trajectoryId` -- see router-session.ts). There is\n * nothing to \"compare\" about that half; it's just a sum-and-filter over\n * already-logged `CostEntry` rows.\n *\n * `baselineCostUsd` is necessarily an *estimate*, not a measurement: it models\n * the cost of the simplest plausible non-RLM alternative for an oversize\n * task -- truncate the context down to whatever fits the target model's\n * context window, then make one single call -- and prices that hypothetical\n * call via `@draht/router`'s `estimateCost`. The specific truncation strategy\n * modeled here is deliberately the crudest one: keep the first N characters\n * of the context that fit the window (a `CHARS_PER_TOKEN` heuristic converts\n * the token-denominated `contextWindow` into a character budget). A smarter\n * baseline (e.g. picking the *most relevant* N characters via embedding\n * search, or summarizing before truncating) would likely produce different\n * numbers -- that's out of scope here. This harness answers \"what would the\n * cheapest naive single-call alternative have cost\", not \"what is the best\n * possible non-RLM approach\". See\n * .planning/phases/30-eval-observability-docs/30-01-PLAN.md, Architecture\n * section 3, and its Risks section.\n */\n\nimport { mkdirSync, writeFileSync } from \"node:fs\";\nimport { dirname, resolve } from \"node:path\";\nimport { estimateCost, readCostLog } from \"@draht/router\";\n\n/** Which target model the truncate-and-single-call baseline is priced against. */\nexport interface BaselineModel {\n\tprovider: string;\n\tmodelName: string;\n\t/** Context window, in tokens -- used to compute how much of the context the baseline call could fit after truncation. */\n\tcontextWindow: number;\n}\n\n/** Result of comparing one RLM trajectory's real cost against a truncate-and-single-call baseline for the same task. */\nexport interface CostComparisonResult {\n\t/**\n\t * Identifies which task/trajectory this comparison covers. There is no\n\t * separate task-name concept tracked elsewhere in this codebase, so this\n\t * is the `trajectoryId` itself -- callers that want a human-readable label\n\t * should track that mapping themselves.\n\t */\n\ttask: string;\n\t/** Sum of every cost-log entry (root call + every `llm_query` sub-call) tagged with this trajectoryId. */\n\trlmCostUsd: number;\n\t/**\n\t * Estimated cost of truncating the context to fit `model`'s window and\n\t * making one single call instead (see the module doc for the exact\n\t * truncation approach modeled).\n\t */\n\tbaselineCostUsd: number;\n\t/** Number of root-LLM steps the RLM trajectory took (one \"rlm-root\"-role cost entry per step -- see router-session.ts's `rootLlm`). */\n\trlmSteps: number;\n\t/** The full (untruncated) context length, in characters, the RLM trajectory operated over. */\n\tcontextLengthChars: number;\n}\n\n/**\n * Rough heuristic: ~4 characters per token for English-ish text. This is the\n * same order-of-magnitude approximation used broadly across LLM tooling when\n * an exact tokenizer isn't wired in for a given model -- it is NOT\n * model-exact, and the `baselineCostUsd` this produces should be read as\n * \"same ballpark\", not \"precise\". See the module doc above and the Risks\n * section of the phase 30 plan.\n */\nconst CHARS_PER_TOKEN = 4;\n\n/**\n * Fixed assumed output length (tokens) for the baseline's single call -- a\n * plausible \"here's the answer\" response size. Deliberately not modeled\n * per-task: this harness needs a reasonable, explicitly-documented constant,\n * not a task-specific prediction of how long an answer would be.\n */\nconst BASELINE_OUTPUT_TOKENS = 500;\n\n/** Default path the \"eval report\" JSON is written to/read from, relative to `process.cwd()`. */\nconst DEFAULT_REPORT_PATH = \".draht/rlm/cost-comparison-report.json\";\n\n/**\n * Compares an already-run RLM trajectory's real cost (read back from the\n * cost log at `costLogPath`, filtered by `trajectoryId`) against the\n * estimated cost of a truncate-and-single-call baseline for the same task:\n * truncate `contextLengthChars` down to whatever fits `model.contextWindow`\n * (first-N-characters, converted via `CHARS_PER_TOKEN`), then price one call\n * to `model` via `@draht/router`'s `estimateCost`.\n *\n * Doesn't run anything itself -- the RLM trajectory must already have run\n * (via `createRouterBackedSession`, logging its cost entries under\n * `costLogPath`) before calling this; the baseline call is hypothetical and\n * never actually dispatched. This function is pure arithmetic over its\n * inputs plus the cost log, and makes no claim about which side is cheaper --\n * that depends entirely on the task.\n */\nexport function compareCost(\n\ttrajectoryId: string,\n\tcontextLengthChars: number,\n\tmodel: BaselineModel,\n\tcostLogPath?: string,\n): CostComparisonResult {\n\tconst entries = readCostLog(costLogPath).filter((entry) => entry.trajectoryId === trajectoryId);\n\tconst rlmCostUsd = entries.reduce((sum, entry) => sum + entry.estimatedCostUsd, 0);\n\t// Exactly one \"rlm-root\"-role cost entry is logged per root-LLM step (see\n\t// router-session.ts's `logRouterCall(\"rlm-root\", ...)` inside `rootLlm`) --\n\t// sub-calls (role \"rlm-sub\") don't count as separate steps.\n\tconst rlmSteps = entries.filter((entry) => entry.role === \"rlm-root\").length;\n\n\tconst truncatedInputTokens = Math.min(model.contextWindow, Math.ceil(contextLengthChars / CHARS_PER_TOKEN));\n\tconst baselineCostUsd = estimateCost(\n\t\tmodel.provider,\n\t\tmodel.modelName,\n\t\ttruncatedInputTokens,\n\t\tBASELINE_OUTPUT_TOKENS,\n\t\t0,\n\t);\n\n\treturn {\n\t\ttask: trajectoryId,\n\t\trlmCostUsd,\n\t\tbaselineCostUsd,\n\t\trlmSteps,\n\t\tcontextLengthChars,\n\t};\n}\n\n/**\n * Writes a `CostComparisonResult` to disk as the \"eval report\" R30-EVAL.3\n * asks for, creating parent directories as needed. Defaults to\n * `.draht/rlm/cost-comparison-report.json` (relative to `process.cwd()`),\n * mirroring `trajectory.ts`'s `DEFAULT_LOG_DIR` convention -- callers that\n * don't want to touch that real location (e.g. tests) should pass an\n * explicit `reportPath` instead.\n */\nexport function writeCostComparisonReport(result: CostComparisonResult, reportPath?: string): void {\n\tconst path = resolve(reportPath ?? DEFAULT_REPORT_PATH);\n\tmkdirSync(dirname(path), { recursive: true });\n\twriteFileSync(path, `${JSON.stringify(result, null, 2)}\\n`, \"utf-8\");\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { InputSource, LoadedInput } from "./loaders.js";
+export { loadInput, parseInputArg } from "./loaders.js";
+export type { PromptTier, PromptVars } from "./prompts.js";
+export { renderPrompt, selectTier } from "./prompts.js";
+export type { CreateRouterBackedSessionOptions } from "./router-session.js";
+export { createRouterBackedSession } from "./router-session.js";
+export { extractPythonCode, pythonReprToValue, RlmSession, truncateStdout } from "./session.js";
+export type { TrajectoryFinalEntry, TrajectoryStepEntry } from "./trajectory.js";
+export { appendTrajectoryEntry, readTrajectory } from "./trajectory.js";
+export type { RlmHistoryEntry, RlmResult, RlmResultKind, RlmSessionOptions } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAeA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,gCAAgC,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAMhG,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// @draht/rlm — Recursive Language Models core primitives.
+//
+// The root loop (`RlmSession`) and its Python REPL driver
+// (`python/repl_driver.py`) implement the inference-time scaffold from
+// Zhang, Kraska, Khattab (2026), *Recursive Language Models*
+// (arXiv:2512.24601). Real `@draht/router` wiring for `llmQuery`/the root
+// LLM, sandboxing, and CLI integration land in later phases (27-29); see
+// .planning/phases/26-rlm-core-primitives/26-01-PLAN.md.
+export { loadInput, parseInputArg } from "./loaders.js";
+export { renderPrompt, selectTier } from "./prompts.js";
+export { createRouterBackedSession } from "./router-session.js";
+export { extractPythonCode, pythonReprToValue, RlmSession, truncateStdout } from "./session.js";
+export { appendTrajectoryEntry, readTrajectory } from "./trajectory.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,0DAA0D;AAC1D,uEAAuE;AACvE,6DAA6D;AAC7D,0EAA0E;AAC1E,yEAAyE;AACzE,yDAAyD;AASzD,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAOhG,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC","sourcesContent":["// @draht/rlm — Recursive Language Models core primitives.\n//\n// The root loop (`RlmSession`) and its Python REPL driver\n// (`python/repl_driver.py`) implement the inference-time scaffold from\n// Zhang, Kraska, Khattab (2026), *Recursive Language Models*\n// (arXiv:2512.24601). Real `@draht/router` wiring for `llmQuery`/the root\n// LLM, sandboxing, and CLI integration land in later phases (27-29); see\n// .planning/phases/26-rlm-core-primitives/26-01-PLAN.md.\n\n// Input loaders -- turn a raw `--input`/`/rlm <input>` argument (file, glob,\n// URL, or `knowledge:<client-slug>`) into loaded prompt content. See\n// .planning/phases/29-agent-cli-integration/29-01-PLAN.md, Architecture\n// section 1. Re-exported from the package root so consumers outside this\n// package (e.g. `@draht/rlm-agent`, the `draht rlm` CLI) can import them via\n// the public `@draht/rlm` entry point instead of reaching into `src/`.\nexport type { InputSource, LoadedInput } from \"./loaders.js\";\nexport { loadInput, parseInputArg } from \"./loaders.js\";\nexport type { PromptTier, PromptVars } from \"./prompts.js\";\nexport { renderPrompt, selectTier } from \"./prompts.js\";\nexport type { CreateRouterBackedSessionOptions } from \"./router-session.js\";\nexport { createRouterBackedSession } from \"./router-session.js\";\nexport { extractPythonCode, pythonReprToValue, RlmSession, truncateStdout } from \"./session.js\";\n// Trajectory JSONL logging/replay (Phase 30) -- see\n// .planning/phases/30-eval-observability-docs/30-01-PLAN.md, Architecture\n// section 1. Re-exported from the package root so consumers outside this\n// package (e.g. `draht rlm replay`) can import via the public `@draht/rlm`\n// entry point instead of reaching into `src/`.\nexport type { TrajectoryFinalEntry, TrajectoryStepEntry } from \"./trajectory.js\";\nexport { appendTrajectoryEntry, readTrajectory } from \"./trajectory.js\";\nexport type { RlmHistoryEntry, RlmResult, RlmResultKind, RlmSessionOptions } from \"./types.js\";\n"]}

package/dist/loaders.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Input loaders -- turn a raw `--input`/`/rlm <input>` argument into loaded
+ * text content ready to become an `RlmSession`'s `prompt`. Covers four kinds
+ * of source: a single file, a glob pattern, an `http(s)://` URL, and a named
+ * client knowledge base (via `@draht/knowledge`). See
+ * .planning/phases/29-agent-cli-integration/29-01-PLAN.md, Architecture
+ * section 1.
+ *
+ * `parseInputArg` classifies the raw string; `loadInput` does the actual
+ * I/O. Kept as two functions so callers (CLI, `/rlm` command, `rlm_query`
+ * tool) can validate/echo back what kind of source they resolved before
+ * paying the cost of loading it.
+ */
+export type InputSource = {
+    type: "file";
+    path: string;
+} | {
+    type: "glob";
+    pattern: string;
+    cwd: string;
+} | {
+    type: "url";
+    url: string;
+} | {
+    type: "knowledge";
+    clientSlug: string;
+};
+export interface LoadedInput {
+    /** The loaded/concatenated text content. */
+    content: string;
+    /** What kind of content `content` holds (e.g. "text", "code", "logs", "json") -- see `PromptVars.contextType`. */
+    contextType: string;
+}
+/**
+ * Classifies a raw `--input`/`/rlm` argument into an {@link InputSource}:
+ * - `knowledge:<client-slug>` -> `{ type: "knowledge", clientSlug }`.
+ * - `http://...` / `https://...` -> `{ type: "url", url }`.
+ * - anything containing glob metacharacters (`* ? { } [ ] !`) -> `{ type: "glob", pattern, cwd }`.
+ * - everything else -> `{ type: "file", path }`, resolved against `cwd` if relative.
+ */
+export declare function parseInputArg(input: string, cwd: string): InputSource;
+/** Loads the given {@link InputSource}, returning its content and the context type to advertise to the RLM root loop. */
+export declare function loadInput(source: InputSource): Promise<LoadedInput>;
+//# sourceMappingURL=loaders.d.ts.map

package/dist/loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.d.ts","sourceRoot":"","sources":["../src/loaders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,MAAM,WAAW,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,kHAAkH;IAClH,WAAW,EAAE,MAAM,CAAC;CACpB;AAkCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAiBrE;AAED,yHAAyH;AACzH,wBAAsB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAgBzE"}

package/dist/loaders.js

@@ -0,0 +1,156 @@
+/**
+ * Input loaders -- turn a raw `--input`/`/rlm <input>` argument into loaded
+ * text content ready to become an `RlmSession`'s `prompt`. Covers four kinds
+ * of source: a single file, a glob pattern, an `http(s)://` URL, and a named
+ * client knowledge base (via `@draht/knowledge`). See
+ * .planning/phases/29-agent-cli-integration/29-01-PLAN.md, Architecture
+ * section 1.
+ *
+ * `parseInputArg` classifies the raw string; `loadInput` does the actual
+ * I/O. Kept as two functions so callers (CLI, `/rlm` command, `rlm_query`
+ * tool) can validate/echo back what kind of source they resolved before
+ * paying the cost of loading it.
+ */
+import { glob, readFile } from "node:fs/promises";
+import * as path from "node:path";
+/**
+ * Recognized prefix for the knowledge-base input syntax: `knowledge:<client-slug>`
+ * (e.g. `knowledge:acme-corp`), where `<client-slug>` matches `ClientConfig.slug`
+ * from `@draht/knowledge`'s `client-config.ts`.
+ */
+const KNOWLEDGE_PREFIX = "knowledge:";
+/** Characters that mark an `--input` string as a glob pattern rather than a literal file path. */
+const GLOB_CHARS = /[*?{}[\]!]/;
+const CODE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".go",
+    ".rs",
+    ".java",
+    ".c",
+    ".cc",
+    ".cpp",
+    ".h",
+    ".hpp",
+    ".rb",
+    ".sh",
+    ".swift",
+    ".kt",
+]);
+/**
+ * Classifies a raw `--input`/`/rlm` argument into an {@link InputSource}:
+ * - `knowledge:<client-slug>` -> `{ type: "knowledge", clientSlug }`.
+ * - `http://...` / `https://...` -> `{ type: "url", url }`.
+ * - anything containing glob metacharacters (`* ? { } [ ] !`) -> `{ type: "glob", pattern, cwd }`.
+ * - everything else -> `{ type: "file", path }`, resolved against `cwd` if relative.
+ */
+export function parseInputArg(input, cwd) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith(KNOWLEDGE_PREFIX)) {
+        const clientSlug = trimmed.slice(KNOWLEDGE_PREFIX.length).trim();
+        return { type: "knowledge", clientSlug };
+    }
+    if (/^https?:\/\//i.test(trimmed)) {
+        return { type: "url", url: trimmed };
+    }
+    if (GLOB_CHARS.test(trimmed)) {
+        return { type: "glob", pattern: trimmed, cwd };
+    }
+    return { type: "file", path: path.isAbsolute(trimmed) ? trimmed : path.join(cwd, trimmed) };
+}
+/** Loads the given {@link InputSource}, returning its content and the context type to advertise to the RLM root loop. */
+export async function loadInput(source) {
+    switch (source.type) {
+        case "file":
+            return loadFile(source.path);
+        case "glob":
+            return loadGlob(source.pattern, source.cwd);
+        case "url":
+            return loadUrl(source.url);
+        case "knowledge":
+            return loadKnowledge(source.clientSlug);
+        default: {
+            // Exhaustiveness check -- widen InputSource, forget a branch, get a compile error here.
+            const _never = source;
+            throw new Error(`loadInput: unknown source type "${_never.type}"`);
+        }
+    }
+}
+async function loadFile(filePath) {
+    const content = await readFile(filePath, "utf-8");
+    return { content, contextType: inferContextType(filePath) };
+}
+async function loadGlob(pattern, cwd) {
+    const matches = [];
+    for await (const match of glob(pattern, { cwd })) {
+        matches.push(match);
+    }
+    matches.sort();
+    if (matches.length === 0) {
+        throw new Error(`loadInput: glob pattern "${pattern}" matched no files (cwd: ${cwd})`);
+    }
+    const contextTypes = new Set();
+    const parts = await Promise.all(matches.map(async (relPath) => {
+        const absPath = path.isAbsolute(relPath) ? relPath : path.join(cwd, relPath);
+        const content = await readFile(absPath, "utf-8");
+        contextTypes.add(inferContextType(absPath));
+        return `--- source: ${absPath} ---\n${content}`;
+    }));
+    // A single matched file's context type carries through; a mixed match falls back to "text".
+    const contextType = contextTypes.size === 1 ? [...contextTypes][0] : "text";
+    return { content: parts.join("\n\n"), contextType };
+}
+async function loadUrl(url) {
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`loadInput: fetching "${url}" failed with status ${response.status}`);
+    }
+    const content = await response.text();
+    const contentType = response.headers.get("content-type") ?? "";
+    return { content, contextType: contentType.includes("json") ? "json" : "text" };
+}
+/** Chunks per section pulled from the client's knowledge store -- generous enough to cover most real stores. */
+const KNOWLEDGE_SEARCH_LIMIT = 20;
+async function loadKnowledge(clientSlug) {
+    const { KnowledgeManager } = await import("@draht/knowledge");
+    const manager = new KnowledgeManager(clientSlug);
+    try {
+        const [conventions, decisions] = await Promise.all([
+            manager.searchKnowledge("project conventions and AGENTS.md guidance", "general", KNOWLEDGE_SEARCH_LIMIT),
+            manager.searchKnowledge("past decisions and rationale", "decide", KNOWLEDGE_SEARCH_LIMIT),
+        ]);
+        const sections = [
+            formatKnowledgeSection("AGENTS.md / conventions", conventions),
+            formatKnowledgeSection("Past decisions", decisions),
+        ].filter((section) => section !== null);
+        if (sections.length === 0) {
+            throw new Error(`loadInput: no knowledge found for client "${clientSlug}"`);
+        }
+        return { content: sections.join("\n\n"), contextType: "text" };
+    }
+    finally {
+        manager.close();
+    }
+}
+function formatKnowledgeSection(title, results) {
+    if (results.length === 0)
+        return null;
+    const body = results.map((r) => r.content).join("\n\n");
+    return `## ${title}\n\n${body}`;
+}
+function inferContextType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".json")
+        return "json";
+    if (ext === ".log")
+        return "logs";
+    if (CODE_EXTENSIONS.has(ext))
+        return "code";
+    return "text";
+}
+//# sourceMappingURL=loaders.js.map

package/dist/loaders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loaders.js","sourceRoot":"","sources":["../src/loaders.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Input loaders -- turn a raw `--input`/`/rlm <input>` argument into loaded\n * text content ready to become an `RlmSession`'s `prompt`. Covers four kinds\n * of source: a single file, a glob pattern, an `http(s)://` URL, and a named\n * client knowledge base (via `@draht/knowledge`). See\n * .planning/phases/29-agent-cli-integration/29-01-PLAN.md, Architecture\n * section 1.\n *\n * `parseInputArg` classifies the raw string; `loadInput` does the actual\n * I/O. Kept as two functions so callers (CLI, `/rlm` command, `rlm_query`\n * tool) can validate/echo back what kind of source they resolved before\n * paying the cost of loading it.\n */\n\nimport { glob, readFile } from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport type { SearchResult } from \"@draht/knowledge\";\n\nexport type InputSource =\n\t| { type: \"file\"; path: string }\n\t| { type: \"glob\"; pattern: string; cwd: string }\n\t| { type: \"url\"; url: string }\n\t| { type: \"knowledge\"; clientSlug: string };\n\nexport interface LoadedInput {\n\t/** The loaded/concatenated text content. */\n\tcontent: string;\n\t/** What kind of content `content` holds (e.g. \"text\", \"code\", \"logs\", \"json\") -- see `PromptVars.contextType`. */\n\tcontextType: string;\n}\n\n/**\n * Recognized prefix for the knowledge-base input syntax: `knowledge:<client-slug>`\n * (e.g. `knowledge:acme-corp`), where `<client-slug>` matches `ClientConfig.slug`\n * from `@draht/knowledge`'s `client-config.ts`.\n */\nconst KNOWLEDGE_PREFIX = \"knowledge:\";\n\n/** Characters that mark an `--input` string as a glob pattern rather than a literal file path. */\nconst GLOB_CHARS = /[*?{}[\\]!]/;\n\nconst CODE_EXTENSIONS = new Set([\n\t\".ts\",\n\t\".tsx\",\n\t\".js\",\n\t\".jsx\",\n\t\".mjs\",\n\t\".cjs\",\n\t\".py\",\n\t\".go\",\n\t\".rs\",\n\t\".java\",\n\t\".c\",\n\t\".cc\",\n\t\".cpp\",\n\t\".h\",\n\t\".hpp\",\n\t\".rb\",\n\t\".sh\",\n\t\".swift\",\n\t\".kt\",\n]);\n\n/**\n * Classifies a raw `--input`/`/rlm` argument into an {@link InputSource}:\n * - `knowledge:<client-slug>` -> `{ type: \"knowledge\", clientSlug }`.\n * - `http://...` / `https://...` -> `{ type: \"url\", url }`.\n * - anything containing glob metacharacters (`* ? { } [ ] !`) -> `{ type: \"glob\", pattern, cwd }`.\n * - everything else -> `{ type: \"file\", path }`, resolved against `cwd` if relative.\n */\nexport function parseInputArg(input: string, cwd: string): InputSource {\n\tconst trimmed = input.trim();\n\n\tif (trimmed.startsWith(KNOWLEDGE_PREFIX)) {\n\t\tconst clientSlug = trimmed.slice(KNOWLEDGE_PREFIX.length).trim();\n\t\treturn { type: \"knowledge\", clientSlug };\n\t}\n\n\tif (/^https?:\\/\\//i.test(trimmed)) {\n\t\treturn { type: \"url\", url: trimmed };\n\t}\n\n\tif (GLOB_CHARS.test(trimmed)) {\n\t\treturn { type: \"glob\", pattern: trimmed, cwd };\n\t}\n\n\treturn { type: \"file\", path: path.isAbsolute(trimmed) ? trimmed : path.join(cwd, trimmed) };\n}\n\n/** Loads the given {@link InputSource}, returning its content and the context type to advertise to the RLM root loop. */\nexport async function loadInput(source: InputSource): Promise<LoadedInput> {\n\tswitch (source.type) {\n\t\tcase \"file\":\n\t\t\treturn loadFile(source.path);\n\t\tcase \"glob\":\n\t\t\treturn loadGlob(source.pattern, source.cwd);\n\t\tcase \"url\":\n\t\t\treturn loadUrl(source.url);\n\t\tcase \"knowledge\":\n\t\t\treturn loadKnowledge(source.clientSlug);\n\t\tdefault: {\n\t\t\t// Exhaustiveness check -- widen InputSource, forget a branch, get a compile error here.\n\t\t\tconst _never: never = source;\n\t\t\tthrow new Error(`loadInput: unknown source type \"${(_never as InputSource).type}\"`);\n\t\t}\n\t}\n}\n\nasync function loadFile(filePath: string): Promise<LoadedInput> {\n\tconst content = await readFile(filePath, \"utf-8\");\n\treturn { content, contextType: inferContextType(filePath) };\n}\n\nasync function loadGlob(pattern: string, cwd: string): Promise<LoadedInput> {\n\tconst matches: string[] = [];\n\tfor await (const match of glob(pattern, { cwd })) {\n\t\tmatches.push(match);\n\t}\n\tmatches.sort();\n\n\tif (matches.length === 0) {\n\t\tthrow new Error(`loadInput: glob pattern \"${pattern}\" matched no files (cwd: ${cwd})`);\n\t}\n\n\tconst contextTypes = new Set<string>();\n\tconst parts = await Promise.all(\n\t\tmatches.map(async (relPath) => {\n\t\t\tconst absPath = path.isAbsolute(relPath) ? relPath : path.join(cwd, relPath);\n\t\t\tconst content = await readFile(absPath, \"utf-8\");\n\t\t\tcontextTypes.add(inferContextType(absPath));\n\t\t\treturn `--- source: ${absPath} ---\\n${content}`;\n\t\t}),\n\t);\n\n\t// A single matched file's context type carries through; a mixed match falls back to \"text\".\n\tconst contextType = contextTypes.size === 1 ? [...contextTypes][0] : \"text\";\n\treturn { content: parts.join(\"\\n\\n\"), contextType };\n}\n\nasync function loadUrl(url: string): Promise<LoadedInput> {\n\tconst response = await fetch(url);\n\tif (!response.ok) {\n\t\tthrow new Error(`loadInput: fetching \"${url}\" failed with status ${response.status}`);\n\t}\n\tconst content = await response.text();\n\tconst contentType = response.headers.get(\"content-type\") ?? \"\";\n\treturn { content, contextType: contentType.includes(\"json\") ? \"json\" : \"text\" };\n}\n\n/** Chunks per section pulled from the client's knowledge store -- generous enough to cover most real stores. */\nconst KNOWLEDGE_SEARCH_LIMIT = 20;\n\nasync function loadKnowledge(clientSlug: string): Promise<LoadedInput> {\n\tconst { KnowledgeManager } = await import(\"@draht/knowledge\");\n\tconst manager = new KnowledgeManager(clientSlug);\n\ttry {\n\t\tconst [conventions, decisions] = await Promise.all([\n\t\t\tmanager.searchKnowledge(\"project conventions and AGENTS.md guidance\", \"general\", KNOWLEDGE_SEARCH_LIMIT),\n\t\t\tmanager.searchKnowledge(\"past decisions and rationale\", \"decide\", KNOWLEDGE_SEARCH_LIMIT),\n\t\t]);\n\n\t\tconst sections = [\n\t\t\tformatKnowledgeSection(\"AGENTS.md / conventions\", conventions),\n\t\t\tformatKnowledgeSection(\"Past decisions\", decisions),\n\t\t].filter((section): section is string => section !== null);\n\n\t\tif (sections.length === 0) {\n\t\t\tthrow new Error(`loadInput: no knowledge found for client \"${clientSlug}\"`);\n\t\t}\n\n\t\treturn { content: sections.join(\"\\n\\n\"), contextType: \"text\" };\n\t} finally {\n\t\tmanager.close();\n\t}\n}\n\nfunction formatKnowledgeSection(title: string, results: SearchResult[]): string | null {\n\tif (results.length === 0) return null;\n\tconst body = results.map((r) => r.content).join(\"\\n\\n\");\n\treturn `## ${title}\\n\\n${body}`;\n}\n\nfunction inferContextType(filePath: string): string {\n\tconst ext = path.extname(filePath).toLowerCase();\n\tif (ext === \".json\") return \"json\";\n\tif (ext === \".log\") return \"logs\";\n\tif (CODE_EXTENSIONS.has(ext)) return \"code\";\n\treturn \"text\";\n}\n"]}