@tangleai/agents 0.21.1 → 0.25.0

package/src/refine.d.ts

@@ -1,21 +1,59 @@
+/**
+ * Refinement: how an agent's durable state improves without anyone
+ * rewriting it.
+ *
+ * After a run, the model is asked what it learned. The answer is not
+ * prose and it is not a new system prompt — it is an RFC 6902 JSON Patch
+ * over the ledger's supplemental state, generated through
+ * `createStructuredOutput` and put through four stages before any of it
+ * lands:
+ *
+ *  1. **shape** — the patch validates against the constrained schema
+ *     (`schemas/patch.ts`): three verbs, a path pattern that matches
+ *     only the supplemental subtree, a cap on the number of operations.
+ *  2. **semantics** — the patch is applied to a COPY of the state
+ *     through the injected patch engine. An operation that cannot apply
+ *     is a compile-style error with a pointer into the patch document,
+ *     which is exactly the error class this package's field notes say
+ *     small models repair well.
+ *  3. **legality** — every record the patched document would store is
+ *     validated against the LEDGER's own schemas. A memory without
+ *     evidence dies here, before anything is written, so the model can
+ *     be told why and try again.
+ *  4. **commit** — a snapshot is taken, then the writes go through the
+ *     ledger's own API. Any rejection rolls the whole thing back: there
+ *     is no half-applied refinement.
+ *
+ * Why a patch rather than a rewrite: a rewrite is unreviewable and
+ * unbounded, and a model asked to restate its memories will drift them.
+ * A patch is small, auditable, and undone by the snapshot from the
+ * ledger. Two things follow from that and are worth saying out loud:
+ *
+ *  - **The base system prompt is not a patch target.** Not "should not
+ *    be" — it is not IN the document a patch is applied to, and no path
+ *    that could reach it matches the schema's pattern. There is no
+ *    operation a model can write that edits its own instructions.
+ *  - **Every stored memory carries evidence**, because the ledger
+ *    rejects one that does not. That is the mechanism by which
+ *    "evidence-backed updates" is enforced rather than hoped for.
+ *
+ * The patch engine is INJECTED (`applyPatch`), like every other heavy
+ * thing this package touches: `@jarenjs/json` ships an RFC 6902 engine
+ * and this package must not import it. With the seam empty, refinement
+ * declines with a stated reason and the rest of the ledger is unaffected
+ * — the same degrade-to-nothing posture as the retrieval seam.
+ */
 /**
  * The run, as the few hundred characters worth putting in front of the
  * model. Tool steps are preferred over wire messages: the steps ARE the
  * evidence a memory would cite, and a transcript's assistant turns are
  * mostly the model reading its own prose back.
- * @param {any} trajectory - a `send` result, its `steps`, or wire messages
- * @param {number} max
- * @returns {string}
+ * @param trajectory - a `send` result, its `steps`, or wire messages
  */
-export function describeTrajectory(trajectory: any, max?: number): string;
+export declare function describeTrajectory(trajectory: any, max?: number): string;
 /**
  * Create a refiner over a ledger.
  *
- * @param {{ client: any, ledger: any,
- *   applyPatch?: ((document: any, patch: any[]) => any) | null,
- *   maxOps?: number, maxRepairs?: number, validator?: any,
- *   now?: () => string, trajectoryChars?: number,
- *   instructions?: string, deduplicate?: 'exact-evidence' }} options
  *   - `applyPatch` is the RFC 6902 seam: `(document, patch) => document`,
  *     normally `(doc, patch) => applyJSONPatch(doc, patch)` from
  *     `@jarenjs/json`. Absent, `refine`/`commit` decline with a stated
@@ -32,12 +70,8 @@ export function describeTrajectory(trajectory: any, max?: number): string;
  *     text and evidence and the same tags. Existing records are never merged
  *     or removed by this option; case, whitespace and independent citations
  *     remain distinct. The result reports every skipped proposal in `deduplicated`.
- * @returns {{ state: () => Promise<any>,
- *   commit: (patch: any[]) => Promise<any>,
- *   refine: (trajectory: any, hooks?: { signal?: AbortSignal }) => Promise<any>,
- *   patchSchema: any }}
  */
-export function createRefiner(options: {
+export declare function createRefiner(options: {
     client: any;
     ledger: any;
     applyPatch?: ((document: any, patch: any[]) => any) | null;
@@ -47,7 +81,7 @@ export function createRefiner(options: {
     now?: () => string;
     trajectoryChars?: number;
     instructions?: string;
-    deduplicate?: "exact-evidence";
+    deduplicate?: 'exact-evidence';
 }): {
     state: () => Promise<any>;
     commit: (patch: any[]) => Promise<any>;