@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/engines/pi/session-settings.d.ts

@@ -1,13 +1,4 @@
-/**
- * What a session is SET TO, and what it may be set to. Model and thinking level are ONE setting —
- * which levels exist is a property of the model — so they resolve together, here, and `state()`, the
- * `update({ thinkingLevel })` gate and the per-invoke binding all read this rather than deriving their own.
- *
- * Read-only by design. The durable record may hold a level the current model cannot do; that record
- * is the user's PREFERENCE, so resolving per read restores it when the session returns to a capable
- * model. (It could not be made unrepresentable anyway: `model_change`/`thinking_level_change` are
- * pi's entries, and pi appends them itself.)
- */
+/** What a session is SET TO, and what it may be set to. */
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { type Models } from "@earendil-works/pi-ai";
 import type { SessionManager } from "@earendil-works/pi-coding-agent";
@@ -20,8 +11,10 @@ export interface OverrideEntryLike {
     modelId?: string;
     thinkingLevel?: string;
 }
-/** The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through
- *  to an earlier record — which record is "the" override must not depend on who is asking. */
+/**
+ * The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through to an earlier
+ * record.
+ */
 export declare function lastOverrideEntries(entries: OverrideEntryLike[]): {
     model?: {
         provider: string;
@@ -50,14 +43,5 @@ export declare function resolveSessionSettings(entries: OverrideEntryLike[], mod
     model: AnyModel;
     thinkingLevel: ThinkingLevel;
 }): SessionSettings;
-/**
- * The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks.
- * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a leaf move,
- * and reading it flat would run the session on a setting it moved away from.
- *
- * A chain that is not intact THROWS. `getBranch()` stops where a parent is missing and answers the
- * SHORT path, which reads exactly like a short session — every override above the gap gone, the next
- * turn silently on assembly defaults. The caller decides what to do with the fault (state() reports
- * the settings as absent, dispatch answers with a code); what it must not do is guess.
- */
+/** The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks. */
 export declare function activePath(record: SessionManager, from?: string): OverrideEntryLike[];

package/dist/engines/pi/session-settings.js

@@ -1,8 +1,5 @@
 import { clampThinkingLevel, getSupportedThinkingLevels } from "@earendil-works/pi-ai";
-/** Which strings are levels at all — the vocabulary. What a MODEL supports is
- *  `getSupportedThinkingLevels`. The `satisfies` anchor keeps this exhaustive against pi's union: a
- *  level pi adds becomes a type error here rather than a value `update({ thinkingLevel })` silently
- *  rejects. */
+/** Which strings are levels at all — the vocabulary. */
 const ALL_THINKING_LEVELS = {
     off: true,
     minimal: true,
@@ -13,8 +10,10 @@ const ALL_THINKING_LEVELS = {
     max: true,
 };
 export const THINKING_LEVELS = new Set(Object.keys(ALL_THINKING_LEVELS));
-/** The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through
- *  to an earlier record — which record is "the" override must not depend on who is asking. */
+/**
+ * The last entry of each kind wins, and a malformed one reads as ABSENT rather than falling through to an earlier
+ * record.
+ */
 export function lastOverrideEntries(entries) {
     let model;
     let modelSeen = false;
@@ -56,9 +55,8 @@ export function resolveSessionSettings(entries, models, defaults) {
             dropped.thinkingLevel = { recorded: level, running: thinkingLevel, known: false };
         }
         else {
-            // pi's clamp takes the lowest supported level AT OR ABOVE the recorded one, falling back
-            // downward only when nothing is above: a gap resolves UPWARD and costs more, not less. Which is
-            // why `dropped` names both levels rather than reporting a substitution.
+            // pi's clamp takes the lowest supported level AT OR ABOVE the recorded one, falling back downward only when
+            // nothing is above.
             thinkingLevel = clampThinkingLevel(model, level);
             if (thinkingLevel !== level) {
                 dropped.thinkingLevel = { recorded: level, running: thinkingLevel, known: true };
@@ -72,19 +70,10 @@ export function resolveSessionSettings(entries, models, defaults) {
         ...(dropped.model || dropped.thinkingLevel ? { dropped } : {}),
     };
 }
-/**
- * The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks.
- * `getBranch()` is exactly that walk: the journal can hold abandoned branches after a leaf move,
- * and reading it flat would run the session on a setting it moved away from.
- *
- * A chain that is not intact THROWS. `getBranch()` stops where a parent is missing and answers the
- * SHORT path, which reads exactly like a short session — every override above the gap gone, the next
- * turn silently on assembly defaults. The caller decides what to do with the fault (state() reports
- * the settings as absent, dispatch answers with a code); what it must not do is guess.
- */
+/** The entries on the session's ACTIVE path, root→leaf — what every last-wins settings read walks. */
 export function activePath(record, from) {
-    // `from` asks a different question: the path a leaf move is ABOUT to make active, which a caller
-    // validating a patch needs before the move exists. Absent, it is the session's current path.
+    // `from` asks a different question: the path a leaf move is ABOUT to make active, which a caller validating a patch
+    // needs before the move exists.
     const path = record.getBranch(from);
     const root = path[0];
     if (root?.parentId != null) {

package/dist/engines/pi/session-store.d.ts

@@ -2,50 +2,27 @@ import { SessionManager } from "@earendil-works/pi-coding-agent";
 import type { SessionSummary, SessionUpdateField } from "../../session.ts";
 import { type OverrideEntryLike } from "./session-settings.ts";
 import { type SessionInheritance } from "./session-inheritance.ts";
-/**
- * The session RECORDS, as operations rather than as pi handles.
- *
- * The distinction is the point. `openOrCreate`/`openIfExists` hand out a live `SessionManager` for
- * the two things that genuinely need one — driving a turn, and reading a session's contents — and
- * everything else is a whole-record operation implemented HERE. That line was drawn after the
- * lifecycle work: when the control plane wrote properties by calling pi's append methods itself, it
- * had to know pi's rules to do it (every append advances the single leaf pointer, so order decides
- * where a fork's head lands; `appendSessionInfo` rewrites the name it is given; a record buffers in
- * memory until its first assistant message). Every caller learning those separately is how the same
- * fact ended up half-known in two modules — so they are known once, here.
- */
+/** The session RECORDS, as operations rather than as pi handles. */
 export interface PiSessionRecordStore {
     openOrCreate(sessionId: string, inherit?: SessionInheritance): Promise<SessionManager>;
-    /** OPEN-EXISTING sibling: an unknown session answers undefined, never creates one — sessions are
-     *  the data plane's monopoly. The READ path (state/entries) and the turn binding use this; the
-     *  write path does not, because a caller holding a handle is a caller learning pi's rules. */
-    openIfExists(sessionId: string): Promise<SessionManager | undefined>;
     /**
-     * Write session properties, in the order pi's leaf pointer requires, and report what LANDED.
-     *
-     * Each property is its own journal entry — pi has no "append these together" — so a failure
-     * partway is a real state, and this answers it rather than pretending a rollback happened. The
-     * caller supplies an already-VALIDATED patch (a model resolved to provider+id, a level this model
-     * accepts): what belongs here is how a record is written, not what a value means.
-     *
-     * `undefined` = no such record (it vanished between the caller's check and this call).
+     * OPEN-EXISTING sibling: an unknown session answers undefined, never creates one — sessions are the data plane's
+     * monopoly.
      */
+    openIfExists(sessionId: string): Promise<SessionManager | undefined>;
+    /** Write session properties, in the order pi's leaf pointer requires, and report what LANDED. */
     applyProperties(sessionId: string, writes: PropertyWrites): Promise<AppliedProperties | undefined>;
-    /** Every record this store holds, in CALLER ids. Rejects when the store cannot be enumerated —
-     *  `[]` means "no sessions", so it must not double as "could not look". Answers the CONTRACT's row
-     *  type: the hub forwards it, and a second identical shape here would only be a thing to keep in
-     *  sync. */
+    /** Every record this store holds, in CALLER ids. */
     list(): Promise<SessionSummary[]>;
-    /** Copy `from`'s history up to entry `at` into a new record named `into`, stamped with `provenance`
-     *  so a repeat of the SAME fork can be recognised as one ({@link forkProvenance}) instead of
-     *  becoming a second record or an overwrite. Throws on any failure: a half-copied fork is never
-     *  left in place, and the caller turns the throw into a coded result. */
+    /**
+     * Copy `from`'s history up to entry `at` into a new record named `into`, stamped with `provenance` so a repeat of
+     * the SAME fork can be recognised as one ({@link forkProvenance}) instead of becoming a second record or an
+     * overwrite.
+     */
     fork(from: string, at: string, into: string, provenance: string): Promise<void>;
-    /** Destroy a record. `false` = there was none (the caller answers `no_such_session`). */
     delete(sessionId: string): Promise<boolean>;
 }
-/** A validated property patch, in the shape a RECORD takes it: the model already resolved to the
- *  provider + id pi's append wants, so this layer never asks what a model spec means. */
+/** A validated property patch, in the shape a RECORD takes it. */
 export interface PropertyWrites {
     name?: string;
     model?: {
@@ -57,73 +34,30 @@ export interface PropertyWrites {
 }
 /** What a property write actually did, and what the record holds after it. */
 interface AppliedProperties {
-    /** In write order. A field asked for but absent here did not land. */
+    /** In write order. */
     landed: SessionUpdateField[];
-    /** Why the rest stopped, if anything did. The caller turns this into a coded result; the record
-     *  already reflects `landed`. */
+    /** Why the rest stopped, if anything did. */
     failure?: unknown;
-    /** The record AFTER the writes — what the caller reports, rather than echoing the request. pi
-     *  rewrites a name (newlines collapse, ends trim), so the request is not what was stored. */
+    /**
+     * The record AFTER the writes — what the caller reports, rather than echoing the request. pi rewrites a name
+     * (newlines collapse, ends trim), so the request is not what was stored.
+     */
     name?: string;
     leafEntryId?: string;
-    /** The active path after the writes, for a caller that resolves settings against a model registry
-     *  this layer has no business knowing. Absent when the chain cannot be walked — the caller decides
-     *  what an unreadable chain means (design §7); it is never silently a short path. */
+    /**
+     * The active path after the writes, for a caller that resolves settings against a model registry this layer has no
+     * business knowing.
+     */
     path?: OverrideEntryLike[];
 }
-/**
- * A Caller's session id, as a name pi will accept.
- *
- * `SessionManager` enforces `^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$` — which no built-in
- * channel satisfies: telegram's `-1001234567890` leads with a dash, feishu and slack keys carry
- * `:` and `/`, and any custom `route()` may mint anything at all.
- *
- * The mapping is INJECTIVE, because two conversations resolving to one record is two rooms sharing a
- * memory. `s` prefix (the pattern demands an alphanumeric head, and prefixing unconditionally is what
- * keeps it injective — a conditional one would map `-a` and `s-a` alike), then each character
- * outside `[A-Za-z0-9.-]` becomes `_XX` / `_uXXXX`, self-describing widths so no two inputs can
- * produce one output. `_` escapes itself for the same reason. A trailing `.` or `-` is legal
- * mid-name but not at the end, so it escapes too.
- *
- * Injective within this encoding — which is only sufficient because this store's records live in
- * their own directory. A name this store did not write draws from the same character set and can
- * still decode: a file called `s42` is also this encoding of `42`, so one directory would make some
- * names ambiguous no matter how this side spells them.
- *
- * Readability is deliberate: `-1001234567890` becomes `s-1001234567890`, so an operator can still
- * tell which room a file belongs to.
- */
+/** A Caller's session id, as a name pi will accept. */
 export declare function piSessionId(sessionId: string): string;
 /**
- * {@link piSessionId} backwards — what `list()` needs, because a session id belongs to the CALLER and
- * a record name is storage detail. The encoding is self-describing (fixed widths, `_` escapes
- * itself), so this is a decode rather than a guess; a name this store did not write (no `s` head, a
- * truncated escape) answers undefined and is left out of the listing rather than reported under a
- * name nobody can dial.
+ * {@link piSessionId} backwards — what `list()` needs, because a session id belongs to the CALLER and a record name is
+ * storage detail.
  */
 export declare function callerSessionId(recordId: string): string | undefined;
-/**
- * Disk-backed store under `dir`: restart the process, conversations continue.
- *
- * Lookup is a directory scan of THIS store's own directory, reading ids out of the filenames pi
- * writes (`<timestamp>_<id>.jsonl`) — not `SessionManager.list`, which filters by the cwd recorded in
- * each header and would make a renamed agent directory look like an empty store (see
- * {@link recordFiles}).
- *
- * Records live in a subdirectory of their own, because a name this store did not write can still
- * decode to a Caller id: a file called `s42` beside them is also this encoding of `42`, so a shared
- * directory would answer `42` with a record it does not own. Only this directory is scanned, which
- * makes this encoding's own injectivity sufficient — a record written before this store existed
- * lies outside it and is never read.
- *
- * SCOPE OF "open-or-create": idempotent against a store that is serialized per session, which is what
- * the serving path provides — the single-writer lease is taken before any store call, so no two
- * turns of one conversation reach this at once. What it does NOT do is arbitrate a FIRST open racing
- * across processes: two instances that scan before either writes will both create, and the
- * conversation forks into two records. A horizontally-scaled deployment that wants more owes a lease
- * that spans its instances — an in-process one cannot arbitrate between them, and a file lock here
- * would only look like it could.
- */
+/** Disk-backed store under `dir`: restart the process, conversations continue. */
 export declare function piSessionRecordStore(options: {
     dir: string;
     cwd?: string;