@vincemakes/kiso-runtime 0.52.0 → 0.54.0

package/dist/session.js

@@ -32,7 +32,8 @@ import { executionLedger } from "./ledger.js";
 import { overflowBelt } from "./overflow-belt.js";
 import { windowLearner } from "./window-learner.js";
 import { denialResult } from "@vincemakes/kiso-core";
-import { buildProfile, readProfile, writeProfile, writeSummary } from "./profile.js";
+import { buildProfile, readForkOrigin, readProfile, writeProfile, writeSummary } from "./profile.js";
+import { forkNote } from "./fork.js";
 import { summarizeEvents } from "./session-summary.js";
 import { lookupModelMetadata, resolveReasoning } from "./provider/metadata.js";
 import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, MANUAL_SUMMARY_BUDGET, SUMMARY_MAX_OUTPUT, resolveCheckpoint, snapshotCheckpointSections, summarizeConversation, SummaryBudgetExhausted, summaryBoundarySeq, } from "./summarize.js";
@@ -91,6 +92,43 @@ function summaryReasoning(model, baseUrl) {
     const r = resolveReasoning(model, { thinking: "disabled", effort: "default" }, baseUrl);
     return r.ok && r.wire.thinking !== undefined ? { reasoning: r.wire } : {};
 }
+/** The follow-up's built-in ask (Session.followUp with no `ask`): the line the person may send next. No language is
+ *  named: without the clause, Chinese conversations still gave Chinese lines (measured, owner 2026-11-03). */
+export const FOLLOW_UP_ASK = "Write the one message the person is most likely to send you next, as they would type it, and nothing else. If the work is done and nothing naturally follows, answer with nothing.";
+/** The built-in follow-up's answer as a line: its first non-empty line, without quotes around it; "" for none, and ""
+ *  for a line over 200 characters (a cut message is not one the person would send, so it is dropped, not shortened). */
+export function followUpLine(text) {
+    const first = text.split("\n").map((l) => l.trim()).find((l) => l !== "") ?? "";
+    const bare = first.replace(/^["'`\u201c\u2018\u300c]+|["'`\u201d\u2019\u300d]+$/g, "").trim();
+    return [...bare].length > 200 ? "" : bare;
+}
+/** The built-in follow-up's room when its thinking cannot be turned off: a one-line answer after the model's own thinking. */
+const FOLLOW_UP_THINKING_ROOM = 600;
+/** The session title's ask (Session.title). The language is named, unlike the follow-up's: the title sees one message
+ *  and no history, and a short greeting under an English ask came back English (ds, a three-character Chinese
+ *  greeting: 5 of 10 English titles without the clause, 0 of 10 with it; owner 2026-11-04). */
+export const TITLE_PROMPT = "Write a short title (2 to 8 words) for a conversation that opens with the user's message, in the language of that message. Only the title: no quotes, no punctuation at the end.";
+/** No thinking for a side answer, where the model table says how: thinking disabled, else effort `none`; null when the
+ *  table knows neither (then nothing is sent: a raw field to an unknown model can be a 400). */
+function quietReasoning(model, baseUrl) {
+    const off = resolveReasoning(model, { thinking: "disabled", effort: "default" }, baseUrl);
+    if (off.ok && off.wire.thinking !== undefined)
+        return off.wire;
+    const none = resolveReasoning(model, { thinking: "default", effort: "none" }, baseUrl);
+    return none.ok && none.wire.effort !== undefined ? none.wire : null;
+}
+/** A model's title as a name: its first non-empty line, without quotes around it or punctuation at its end, its spaces
+ *  collapsed, at most 60 characters; "" when no letter or digit is left. */
+export function cleanTitle(text) {
+    const line = text.split("\n").map((l) => l.trim()).find((l) => l !== "") ?? "";
+    // quotes and ending punctuation can wrap each other ("Title." / Title"."): strip both until neither is left
+    let bare = line;
+    for (let was = ""; was !== bare;)
+        (was = bare), (bare = bare.replace(/^["'`\u201c\u2018\u300c]+|["'`\u201d\u2019\u300d]+$/g, "").replace(/[.!?;:,\u3002\uff01\uff1f\uff1b\uff1a\uff0c]+$/u, "").trim());
+    bare = bare.replace(/\s+/g, " ");
+    const cut = [...bare].length > 60 ? `${[...bare].slice(0, 59).join("")}…` : bare;
+    return /[\p{L}\p{N}]/u.test(cut) ? cut : "";
+}
 /** ADR-0057 §5 (3e D1): a steer detaches a foreground command only once it
  *  is this old — a command about to end on its own is left to end. */
 export const AUTO_DETACH_MIN_AGE_MS = 2_000;
@@ -101,6 +139,8 @@ export class AgentSession {
     // NOT readonly since 0.1.23: /model replaces it between runs (the
     // constructor, setAdapter, and setModelBinding are the only writers).
     #adapter;
+    /** the last request a run sent, as the provider adapter got it (in memory only): what followUp sends again */
+    #lastRequest = null;
     #config;
     /** 0.51.0: the checkpoint every summary call is built from — resolved ONCE at construction from a snapshot of `contextPolicy.checkpointSections`; the raw host array is never read again. */
     #checkpoint;
@@ -778,6 +818,10 @@ export class AgentSession {
      * CLI's honest degradation.
      */
     async sideQuery(options) {
+        return this.#sideQuery(options);
+    }
+    /** sideQuery's body; `reasoning` (resolved, native) is the title's way to ask for no thinking, not a public option. */
+    async #sideQuery(options) {
         this.ensureHealthy();
         // a fresh id: this request is not the paused run's work, and giving
         // it the run's id would put on-demand rent inside a run's total.
@@ -810,6 +854,7 @@ export class AgentSession {
                 messages: [{ role: "user", content: options.prompt }],
                 systemPrompt: options.systemPrompt,
                 ...(options.maxTokens !== undefined ? { maxTokens: options.maxTokens } : {}),
+                ...(options.reasoning !== undefined ? { reasoning: options.reasoning } : {}),
                 ...(options.signal !== undefined ? { signal: options.signal } : {}),
             })) {
                 if (ev.type === "text_delta")
@@ -821,6 +866,27 @@ export class AgentSession {
         }
         return text;
     }
+    /**
+     * A title for the conversation `firstMessage` opens (owner 2026-11-03: the person's first line is not a title): one
+     * side query with its own short prompt and that message (its first 500 characters), no tools, no history, purpose
+     * "title" in the trace. It asks for no thinking where the route allows it (measured on co: 6-10 tokens out instead of
+     * 100 cut short): thinking disabled, else effort `none`, resolved through the model table as the manual summary is;
+     * for a model the table does not know it sends no reasoning field and allows more output. The answer is cleaned to
+     * one line (no quotes, no ending punctuation, at most 60 characters); "" when nothing is left. It writes nothing: the
+     * caller keeps the title where it keeps names, and only for a session the person has not named.
+     */
+    async title(firstMessage, options) {
+        const quiet = quietReasoning(this.#model, this.#baseUrl);
+        const text = await this.#sideQuery({
+            purpose: "title",
+            systemPrompt: TITLE_PROMPT,
+            prompt: firstMessage.slice(0, 500),
+            maxTokens: quiet === null ? 400 : 100,
+            ...(quiet !== null ? { reasoning: quiet } : {}),
+            ...(options?.signal !== undefined ? { signal: options.signal } : {}),
+        });
+        return cleanTitle(text);
+    }
     /** Run one user turn. Iterate to consume; `run.abort()` cancels. */
     /** REL-0152-D11: `input` is text, or the content blocks a turn with an
      *  attachment carries. The durable event, the projection and both
@@ -837,7 +903,7 @@ export class AgentSession {
         if (this.#profilePending)
             this.#recordProfile(); // XP-1: legacy revision 1, before the first request
         const config = options?.maxTurns !== undefined ? { ...this.#effectiveConfig(), maxTurns: options.maxTurns } : this.#effectiveConfig();
-        return new Run(this.#store, this.#learning(this.#adapter), config, this, input, options?.signal, false, options?.source, options?.via);
+        return new Run(this.#store, this.#remembering(this.#learning(this.#adapter)), config, this, this.#withForkNote(input, options?.source), options?.signal, false, options?.source, options?.via);
     }
     /**
      * Continue the interrupted run (Area 2): apply durable decisions,
@@ -847,7 +913,91 @@ export class AgentSession {
      */
     resume() {
         this.ensureHealthy();
-        return new Run(this.#store, this.#learning(this.#adapter), this.#effectiveConfig(), this, undefined, undefined, true);
+        return new Run(this.#store, this.#remembering(this.#learning(this.#adapter)), this.#effectiveConfig(), this, undefined, undefined, true);
+    }
+    /** A fork's first input carries the fork note before the person's words, once (plan fork rev 2): after the copied
+     *  history, so the request's prefix is the parent's and a caching route reads it from the cache. "First" is the log
+     *  still ending where it was cut; a runtime notice (source "system") never carries it. */
+    #withForkNote(input, source) {
+        if (source === "system")
+            return input;
+        const origin = readForkOrigin(this.#store.root, this.id);
+        if (origin === null || this.log.lastSeq !== origin.afterSeq)
+            return input;
+        return [{ type: "text", text: forkNote(origin.title) }, ...(typeof input === "string" ? [{ type: "text", text: input }] : input)];
+    }
+    /** The adapter a run uses, noting each request it carries (the last one stands, without its signal) for followUp. */
+    #remembering(adapter) {
+        return {
+            stream: (options) => {
+                const { signal: _signal, ...request } = options;
+                this.#lastRequest = request;
+                return adapter.stream(options);
+            },
+        };
+    }
+    /**
+     * A follow-up of the last run: its last request sent again, byte for byte as the run sent it, then what came after it
+     * in the conversation (the run's last reply, as the projection has it, reasoning included) and `ask` as a user message,
+     * through the session's own adapter; the model's text comes back. The prefix is the run's own, so a route
+     * that caches reads nearly all of it from the cache: the web app asks it for the line the person may send next.
+     *
+     * Like sideQuery it writes nothing durable and lands one trace line with a fresh runId and purpose "follow-up". It
+     * sends nothing, and answers "", when no run has sent a request since this session was opened, or when the model has
+     * been switched since (that prefix would not be this model's). Tools stay in the request (they are part of the
+     * prefix); a tool call in the answer is ignored.
+     */
+    /** What the conversation holds after a request's messages: the projection's rest when it starts with them (the usual
+     *  case), else only its last reply. */
+    #after(sent) {
+        const now = this.projected();
+        if (JSON.stringify(now.slice(0, sent.length)) === JSON.stringify(sent))
+            return now.slice(sent.length);
+        const last = now.at(-1);
+        return last?.role === "assistant" ? [last] : [];
+    }
+    async followUp(options) {
+        this.ensureHealthy();
+        const last = this.#lastRequest;
+        if (last === null || last.model !== this.#model)
+            return "";
+        const tracer = new RequestTracer({
+            root: this.#store.root,
+            sessionId: this.id,
+            runId: crypto.randomUUID(),
+            provider: this.#provider ?? "adapter",
+            model: this.#model,
+            ...(this.#baseUrl !== undefined ? { endpoint: this.#baseUrl } : {}),
+            adapterVersion: runtimeVersion(),
+            purpose: "follow-up",
+            log: [],
+            rentParts: { base: last.systemPrompt ?? "", appends: [] },
+        });
+        tracer.init();
+        const guarded = traceGuard(tracer, idleGuard(this.#adapter, this.#config.streamIdleMs ?? DEFAULT_STREAM_IDLE_MS));
+        // The built-in line asks for no thinking where the model table says how, as the title does: half of the measured
+        // follow-ups spent 80-200 output tokens thinking about one line, and some were cut off by the budget. Not on the
+        // anthropic route, where changing the thinking setting drops the cached prefix this request exists to reuse. A model
+        // that cannot be quieted keeps its own setting and gets room for its thinking. A host's own `ask` is sent as before.
+        const quiet = options.ask === undefined && this.#provider !== "anthropic" ? quietReasoning(this.#model, this.#baseUrl) : null;
+        const maxTokens = options.ask === undefined && quiet === null && options.maxTokens !== undefined ? Math.max(options.maxTokens, FOLLOW_UP_THINKING_ROOM) : options.maxTokens;
+        let text = "";
+        try {
+            for await (const ev of guarded.stream({
+                ...last,
+                ...(quiet !== null ? { reasoning: quiet } : {}),
+                messages: [...last.messages, ...this.#after(last.messages), { role: "user", content: options.ask ?? FOLLOW_UP_ASK }],
+                ...(maxTokens !== undefined ? { maxTokens } : {}),
+                ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            })) {
+                if (ev.type === "text_delta")
+                    text += ev.text;
+            }
+        }
+        finally {
+            tracer.finishRun();
+        }
+        return options.ask === undefined ? followUpLine(text) : text;
     }
     /**
      * /compact (ADR-0044): compress the older conversation with a model

package/dist/store.d.ts

@@ -43,6 +43,7 @@
  *   tolerated damage; everything else throws StoreCorruptionError.
  */
 import { type Event } from "@vincemakes/kiso-core";
+import { type ForkOrigin } from "./profile.js";
 import { type LockAdapter } from "./lock-adapter.js";
 /** History that does not parse as a contiguous kiso trajectory. */
 export declare class StoreCorruptionError extends Error {
@@ -65,6 +66,8 @@ export interface SessionMeta {
     readonly runs: number;
     readonly createdAt: number;
     readonly updatedAt: number;
+    /** the session this one was forked from (SessionStore.fork), when it is a fork */
+    readonly forkedFrom?: string;
 }
 export declare function sessionTitle(records: readonly StoreRecord[]): string;
 export declare class SessionStore {
@@ -121,6 +124,14 @@ export declare class SessionStore {
      * needs only the ids must never pay that. An empty log is skipped, as
      * list() skips it.
      */
+    /** Fork `parent` after the run that ended at `afterSeq` (absent: its last finished run): a new session with the
+     *  conversation up to there and nothing after (fork.ts). Throws ForkRefusedError, in words, when it cannot. */
+    fork(parent: string, options?: {
+        readonly afterSeq?: number;
+    }): {
+        readonly id: string;
+        readonly origin: ForkOrigin;
+    };
     ids(): string[];
     list(): SessionMeta[];
     /** Release a session's fd and OUR writer lock. Idempotent. */

package/dist/store.js

@@ -45,8 +45,10 @@
 import { appendFileSync, closeSync, constants, existsSync, fsyncSync, fstatSync, statSync, ftruncateSync, mkdirSync, openSync, readFileSync, readdirSync, readSync, writeSync, } from "node:fs";
 import { dirname, join } from "node:path";
 import { isKisoEvent } from "@vincemakes/kiso-core";
-import { readSessionName } from "./profile.js";
+import { readForkOrigin, readSessionName } from "./profile.js";
+import { forkSession } from "./fork.js";
 import { LockedError, nativeLockAdapter, } from "./lock-adapter.js";
+import { isEnvironmentNote } from "./environment.js";
 /** History that does not parse as a contiguous kiso trajectory. */
 export class StoreCorruptionError extends Error {
     constructor(message) {
@@ -126,8 +128,10 @@ function contentText(content) {
         if (block === null || typeof block !== "object")
             continue;
         const b = block;
-        if (b.type === "text" && typeof b.text === "string")
-            parts.push(b.text);
+        if (b.type === "text" && typeof b.text === "string") {
+            if (!isEnvironmentNote(b.text))
+                parts.push(b.text); // the host's line about a folder, never the person's words
+        }
         else if (b.type === "image")
             parts.push("(image)");
     }
@@ -159,6 +163,8 @@ export class SessionStore {
     #fds = new Map();
     /** sessionId → the lock handle THIS instance holds (ADR-0050). */
     #lockHandles = new Map();
+    /** sessionId → what the last load read: the file it was (device, inode, size, mtime), the byte after its last committed line, and the records (load's tail read). */
+    #loaded = new Map();
     #lockAdapter;
     /** round 4 (adversarial): serialize concurrent acquireLock calls ON this instance —
      *  two racing appends must not issue two acquisitions and fight each other. */
@@ -366,9 +372,92 @@ export class SessionStore {
      */
     load(sessionId) {
         const path = this.pathFor(sessionId);
-        if (!existsSync(path))
+        if (!existsSync(path)) {
+            this.#loaded.delete(sessionId);
             return [];
-        const raw = readFileSync(path, "utf8");
+        }
+        const fresh = this.#loadTail(sessionId, path);
+        if (fresh !== null)
+            return fresh;
+        const st = statSync(path);
+        const raw = readFileSync(path);
+        const records = this.#loadWhole(raw.toString("utf8"));
+        const end = raw.lastIndexOf(0x0a);
+        let lines = 0;
+        for (let i = 0; i <= end; i++)
+            if (raw[i] === 0x0a)
+                lines += 1;
+        this.#loaded.set(sessionId, { dev: st.dev, ino: st.ino, size: st.size, mtimeMs: st.mtimeMs, committed: end + 1, lines, records });
+        return records.slice();
+    }
+    /**
+     * The log read again only from where the last load stopped, when the file is the same file (device and inode) and has
+     * only grown past that point, which is how this store writes it: append-only, a torn tail truncated. Anything else (a
+     * shorter file, another inode, the same size with a new mtime, a last committed byte that is not a newline) is read whole
+     * by the strict path below, so a cached read never stands in for one that would have refused. Each caller gets its own
+     * array; the records themselves are shared and never mutated.
+     */
+    #loadTail(sessionId, path) {
+        const held = this.#loaded.get(sessionId);
+        if (held === undefined)
+            return null;
+        let st;
+        try {
+            st = statSync(path);
+        }
+        catch {
+            return null;
+        }
+        if (st.dev !== held.dev || st.ino !== held.ino || st.size < held.committed)
+            return null;
+        if (st.size === held.size && st.mtimeMs === held.mtimeMs)
+            return held.records.slice();
+        if (st.size === held.size)
+            return null;
+        const fd = openSync(path, "r");
+        let chunk;
+        try {
+            const from = held.committed - 1;
+            chunk = Buffer.alloc(st.size - from);
+            let got = 0;
+            while (got < chunk.length) {
+                const n = readSync(fd, chunk, got, chunk.length - got, from + got);
+                if (n === 0)
+                    break;
+                got += n;
+            }
+            chunk = chunk.subarray(0, got);
+        }
+        finally {
+            closeSync(fd);
+        }
+        if (held.committed > 0 && chunk[0] !== 0x0a)
+            return null; // the byte before the new part must end a committed line
+        const body = held.committed > 0 ? chunk.subarray(1) : chunk;
+        const end = body.lastIndexOf(0x0a);
+        const records = held.records.slice();
+        let line = held.lines;
+        if (end >= 0) {
+            for (const text of body.subarray(0, end).toString("utf8").split("\n")) {
+                line += 1;
+                if (text === "")
+                    continue;
+                let parsed;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    return null; // the strict path names it
+                }
+                if (!isRecord(parsed) || parsed.event.seq !== records.length)
+                    return null;
+                records.push(parsed);
+            }
+        }
+        this.#loaded.set(sessionId, { dev: st.dev, ino: st.ino, size: st.size, mtimeMs: st.mtimeMs, committed: held.committed + (end >= 0 ? end + 1 : 0), lines: line, records });
+        return records.slice();
+    }
+    #loadWhole(raw) {
         const lines = raw.split("\n");
         const nonEmpty = [];
         for (let i = 0; i < lines.length; i++) {
@@ -415,6 +504,12 @@ export class SessionStore {
      * needs only the ids must never pay that. An empty log is skipped, as
      * list() skips it.
      */
+    /** Fork `parent` after the run that ended at `afterSeq` (absent: its last finished run): a new session with the
+     *  conversation up to there and nothing after (fork.ts). Throws ForkRefusedError, in words, when it cannot. */
+    fork(parent, options) {
+        this.pathFor(parent); // the id is checked before any file is read
+        return forkSession(this.root, parent, options?.afterSeq);
+    }
     ids() {
         const out = [];
         for (const entry of readdirSync(this.root)) {
@@ -449,6 +544,7 @@ export class SessionStore {
                 runs: new Set(records.map((r) => r.runId)).size,
                 createdAt: records[0]?.ts ?? 0,
                 updatedAt: records.at(-1)?.ts ?? 0,
+                ...((origin) => (origin === null ? {} : { forkedFrom: origin.session }))(readForkOrigin(this.root, id)),
             });
         }
         return metas.sort((a, b) => a.id.localeCompare(b.id));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-runtime",
-	"version": "0.52.0",
+	"version": "0.54.0",
 	"description": "kiso runtime \u2014 durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
 	"type": "module",
 	"license": "MIT",
@@ -25,12 +25,12 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.52.0"
+		"@vincemakes/kiso-core": "0.54.0"
 	},
 	"peerDependencies": {
-		"@vincemakes/kiso-provider-anthropic": "0.52.0",
-		"@vincemakes/kiso-provider-openai": "0.52.0",
-		"@vincemakes/kiso-provider-openai-responses": "0.52.0"
+		"@vincemakes/kiso-provider-anthropic": "0.54.0",
+		"@vincemakes/kiso-provider-openai": "0.54.0",
+		"@vincemakes/kiso-provider-openai-responses": "0.54.0"
 	},
 	"peerDependenciesMeta": {
 		"@vincemakes/kiso-provider-anthropic": {
@@ -44,7 +44,7 @@
 		}
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.52.0",
+		"@vincemakes/kiso-evals": "0.54.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"