@vincemakes/kiso-runtime 0.52.0 → 0.53.0

package/dist/fork.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A fork (owner 2026-11-03: one rule for the terminal, the web app and the products that embed kiso): a new session
+ * holding the conversation up to the end of one of the parent's runs, and nothing after it. It is the parent's local
+ * files under a new id: the log's lines up to that run's `terminal`, byte for byte (no line names its session and none
+ * chains to another), and a sidecar with the parent's execution profile, the name "… (fork)" and the fork's origin. Not
+ * carried: the lock and the background tasks, which belong to the parent's process, and the parent's summary, which may
+ * describe runs after the cut. The parent is only read; lines it appends meanwhile are after the cut. The sidecar is
+ * written first: the runtime reads a session's profile before its first event.
+ */
+import { type ForkOrigin } from "./profile.js";
+/** A fork the store will not make, said in words (the caller shows them). */
+export declare class ForkRefusedError extends Error {
+    constructor(message: string);
+}
+/** Fork `parent` in `root` after the run that ended at `afterSeq` (absent: the last finished run). */
+export declare function forkSession(root: string, parent: string, afterSeq?: number): {
+    readonly id: string;
+    readonly origin: ForkOrigin;
+};
+/** Whether a text block is the fork note (the apps show the person's words, never this). */
+export declare const isForkNote: (text: string) => boolean;
+/**
+ * What a fork's model is told, once, with the fork's first input after the copied history (never in the system prompt:
+ * a cache is a prefix, and a note there made the fork's first request read the whole history fresh, 0% against 88%
+ * measured on co, plan fork rev 2): what the conversation it continues does not bring with it.
+ */
+export declare const forkNote: (parentTitle: string) => string;

package/dist/fork.js

@@ -0,0 +1,84 @@
+/**
+ * A fork (owner 2026-11-03: one rule for the terminal, the web app and the products that embed kiso): a new session
+ * holding the conversation up to the end of one of the parent's runs, and nothing after it. It is the parent's local
+ * files under a new id: the log's lines up to that run's `terminal`, byte for byte (no line names its session and none
+ * chains to another), and a sidecar with the parent's execution profile, the name "… (fork)" and the fork's origin. Not
+ * carried: the lock and the background tasks, which belong to the parent's process, and the parent's summary, which may
+ * describe runs after the cut. The parent is only read; lines it appends meanwhile are after the cut. The sidecar is
+ * written first: the runtime reads a session's profile before its first event.
+ */
+import { closeSync, fsyncSync, openSync, readFileSync, renameSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { readSessionName, tenantsOf, writeForkSidecar } from "./profile.js";
+/** A fork the store will not make, said in words (the caller shows them). */
+export class ForkRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ForkRefusedError";
+    }
+}
+/** The id a fork is given: the time to the second and four random characters, the way a session's id is made. */
+const newId = (now = new Date()) => `${now.toISOString().slice(0, 19).replace(/:/g, "-")}-${Math.floor(Math.random() * 0x10000).toString(16).padStart(4, "0")}`;
+/** Write a file whole or not at all: a temp file, its bytes synced, then renamed over the name. */
+function durable(path, bytes) {
+    const tmp = `${path}.fork-${process.pid}`;
+    const fd = openSync(tmp, "w", 0o600);
+    try {
+        writeSync(fd, bytes);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(tmp, path);
+}
+/** Fork `parent` in `root` after the run that ended at `afterSeq` (absent: the last finished run). */
+export function forkSession(root, parent, afterSeq) {
+    let log;
+    try {
+        log = readFileSync(join(root, `${parent}.jsonl`));
+    }
+    catch {
+        throw new ForkRefusedError(`no session ${parent} to fork`);
+    }
+    // the lines, with where each ends, and the event each holds
+    const lines = [];
+    for (let from = 0; from < log.length;) {
+        const nl = log.indexOf(10, from);
+        if (nl < 0)
+            break; // a line still being written is after any cut
+        const event = JSON.parse(log.subarray(from, nl).toString("utf8")).event;
+        lines.push({ end: nl + 1, seq: event["seq"], type: event["type"], event });
+        from = nl + 1;
+    }
+    const cut = afterSeq === undefined ? [...lines].reverse().find((l) => l.type === "terminal") : lines.find((l) => l.seq === afterSeq);
+    if (cut === undefined)
+        throw new ForkRefusedError(afterSeq === undefined ? "this session has no finished run to fork from yet" : `no event ${afterSeq} in this session`);
+    if (cut.type !== "terminal")
+        throw new ForkRefusedError("a fork starts at the end of a run: pick a reply that finished");
+    const kept = lines.filter((l) => l.end <= cut.end);
+    // an execution still waiting for a verdict belongs to the world the parent ran in: settle it there first
+    const resolved = new Set(kept.filter((l) => l.type === "tool_execution_resolved").map((l) => l.event["executionId"]));
+    if (kept.some((l) => l.type === "uncertain_pending" && !resolved.has(l.event["executionId"])))
+        throw new ForkRefusedError("an action before this point is still waiting for your verdict in the original session: settle it there, then fork");
+    // its name, else its first line (only this log is read)
+    const first = kept.find((l) => l.type === "user_input")?.event;
+    const said = typeof first?.via?.line === "string" ? first.via.line : typeof first?.content === "string" ? first.content : Array.isArray(first?.content) ? first.content.map((p) => (typeof p.text === "string" ? p.text : "")).join(" ") : "";
+    const title = readSessionName(root, parent) ?? said.replace(/\s+/g, " ").trim().slice(0, 60);
+    const id = newId();
+    const origin = { session: parent, afterSeq: cut.seq, at: Date.now(), title };
+    writeForkSidecar(root, id, { profile: tenantsOf(root, parent)["profile"], name: `${(title || "Session").slice(0, 110)} (fork)`, forkedFrom: origin });
+    durable(join(root, `${id}.jsonl`), log.subarray(0, cut.end));
+    return { id, origin };
+}
+const FORK_NOTE_HEAD = 'This session was forked from the session "';
+/** Whether a text block is the fork note (the apps show the person's words, never this). */
+export const isForkNote = (text) => text.startsWith(FORK_NOTE_HEAD);
+/**
+ * What a fork's model is told, once, with the fork's first input after the copied history (never in the system prompt:
+ * a cache is a prefix, and a note there made the fork's first request read the whole history fresh, 0% against 88%
+ * measured on co, plan fork rev 2): what the conversation it continues does not bring with it.
+ */
+export const forkNote = (parentTitle) => `${FORK_NOTE_HEAD}${parentTitle}" at the end of one of its runs. The conversation above it is copied; two things are not. ` +
+    "Background tasks started there are not running here (a task id from that conversation names nothing in this session). " +
+    "The folder is shared with it: its files are as they are on disk now, not as they were when the run above ended, and the original session may still change them.";

package/dist/index.d.ts

@@ -21,13 +21,15 @@
 export { AgentRuntime, AgentRuntime as Agent, createAgent } from "./agent.js";
 export type { AgentDefinition, PermissionPolicy, PermissionRule } from "./agent.js";
 export { AgentSession, AgentSession as Session } from "./session.js";
-export type { SideQueryOptions } from "./session.js";
+export type { FollowUpOptions, SideQueryOptions } from "./session.js";
 export { PoisonedSessionError, ResumeBlockedError } from "./session.js";
 export type { ApprovalRequest, CompactInfo, ContextPolicy, SessionConfig, SummarizeResult } from "./session.js";
 export { DEFAULT_CHECKPOINT_SECTIONS } from "./summarize.js";
 export type { CheckpointSection } from "./summarize.js";
 export { Run, RunClosedError } from "./run.js";
 export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
+export { ForkRefusedError } from "./fork.js";
+export type { ForkOrigin } from "./profile.js";
 export type { Event, SessionMeta, StoreRecord } from "./store.js";
 export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./extensions.js";
 export type { KisoExtension } from "./extensions.js";

package/dist/index.js

@@ -29,6 +29,7 @@ export { DEFAULT_CHECKPOINT_SECTIONS } from "./summarize.js";
 export { Run, RunClosedError } from "./run.js";
 // store
 export { SessionStore, StaleWriterError, StoreCorruptionError } from "./store.js";
+export { ForkRefusedError } from "./fork.js";
 // extensions
 export { disposeExtensions, loadExtensions, loadProjectExtensions } from "./extensions.js";
 // tasks (ADR-0058): a host that wires background tasks needs the manager

package/dist/internal.d.ts

@@ -29,7 +29,8 @@ export { canonicalizeUsageForModel } from "./usage/canonical.js";
 export { BUILTIN_MANIFESTS, resolveContinuationScope, type ModelRef, type ProviderManifest } from "./provider/manifest.js";
 export * from "./checkpoint.js";
 export * from "./request-budget.js";
-export { readProfile, readSessionName, readSummary, writeSessionName, writeSummary, type ExecutionProfile, type ProfileReadResult } from "./profile.js";
+export { isForkNote } from "./fork.js";
+export { readForkOrigin, readProfile, readSessionName, readSummary, writeSessionName, writeSummary, type ExecutionProfile, type ProfileReadResult } from "./profile.js";
 export { SUMMARY_MIGRATION_MARKER, listSessionSidecars, migrateSummaries, sessionSummary, summarizeEvents, summaryMigrationPending, type SessionListing, type SessionSummary } from "./session-summary.js";
 export * from "./tasks/journal.js";
 export * from "./tasks/manager.js";

package/dist/internal.js

@@ -38,7 +38,8 @@ export { BUILTIN_MANIFESTS, resolveContinuationScope } from "./provider/manifest
 export * from "./checkpoint.js";
 export * from "./request-budget.js";
 // 0.40.0: the listing reads the recorded workspace and profile name.
-export { readProfile, readSessionName, readSummary, writeSessionName, writeSummary } from "./profile.js";
+export { isForkNote } from "./fork.js";
+export { readForkOrigin, readProfile, readSessionName, readSummary, writeSessionName, writeSummary } from "./profile.js";
 export { SUMMARY_MIGRATION_MARKER, listSessionSidecars, migrateSummaries, sessionSummary, summarizeEvents, summaryMigrationPending } from "./session-summary.js";
 // ADR-0058 §6: the task journal and the TaskManager (internal until the
 // public shape is proven by the shell and delegate steps)

package/dist/profile.d.ts

@@ -94,6 +94,25 @@ export declare function readSessionName(root: string, sessionId: string): string
 /** Name the session, or clear its name (`null`). Atomic and fail-closed
  *  like every tenant's write; the others' bytes ride through. */
 export declare function writeSessionName(root: string, sessionId: string, name: string | null): void;
+/** Where a fork came from (SessionStore.fork): the parent session, the seq of the parent's `terminal` it was cut after,
+ *  when, and the parent's title then. The sidecar's fourth tenant; lineage, not authority. */
+export interface ForkOrigin {
+    readonly session: string;
+    readonly afterSeq: number;
+    readonly at: number;
+    readonly title: string;
+}
+/** The fork's origin, or null (not a fork, no sidecar, unreadable). */
+export declare function readForkOrigin(root: string, sessionId: string): ForkOrigin | null;
+/** A new fork's sidecar, whole: the parent's execution profile, the fork's name, and its origin. The parent's summary is
+ *  not carried: it may describe runs after the cut, and the fork writes its own. */
+export declare function writeForkSidecar(root: string, sessionId: string, tenants: {
+    readonly profile?: unknown;
+    readonly name: string;
+    readonly forkedFrom: ForkOrigin;
+}): void;
+/** The parent's tenants, read for a fork. */
+export declare function tenantsOf(root: string, sessionId: string): Record<string, unknown>;
 export type ProfileReadResult = {
     readonly kind: "ok";
     readonly profile: ExecutionProfile;

package/dist/profile.js

@@ -98,6 +98,20 @@ export function writeSessionName(root, sessionId, name) {
     delete tenants.name;
     writeTenants(root, sessionId, name === null ? tenants : { ...tenants, name });
 }
+/** The fork's origin, or null (not a fork, no sidecar, unreadable). */
+export function readForkOrigin(root, sessionId) {
+    const f = currentTenants(root, sessionId).forkedFrom;
+    return f !== undefined && typeof f.session === "string" && typeof f.afterSeq === "number" && typeof f.at === "number" && typeof f.title === "string" ? f : null;
+}
+/** A new fork's sidecar, whole: the parent's execution profile, the fork's name, and its origin. The parent's summary is
+ *  not carried: it may describe runs after the cut, and the fork writes its own. */
+export function writeForkSidecar(root, sessionId, tenants) {
+    writeTenants(root, sessionId, { ...(tenants.profile !== undefined ? { profile: tenants.profile } : {}), name: tenants.name, forkedFrom: tenants.forkedFrom });
+}
+/** The parent's tenants, read for a fork. */
+export function tenantsOf(root, sessionId) {
+    return currentTenants(root, sessionId);
+}
 function writeTenants(root, sessionId, tenants) {
     const path = profilePath(root, sessionId);
     const tmpDir = mkdtempSync(join(root, ".meta-"));

package/dist/session.d.ts

@@ -51,6 +51,13 @@ export interface SideQueryOptions {
     /** cancels the request — the CLI wires esc to it. */
     readonly signal?: AbortSignalLike;
 }
+export interface FollowUpOptions {
+    /** what is asked after the run's last reply, as the person's next message; absent: the built-in ask for the line the
+     *  person may send next (FOLLOW_UP_ASK), and the answer comes back as that one line (cleaned as the apps show it) */
+    readonly ask?: string;
+    readonly maxTokens?: number;
+    readonly signal?: AbortSignalLike;
+}
 /** A session whose disk write was rejected (stale handle) is PERMANENTLY
  * poisoned: its in-memory log no longer matches the disk, so no further
  * run may proceed — reload the session (round 1). */
@@ -92,6 +99,17 @@ export interface CompactInfo {
     /** The covered content's estimated tokens (the chars/4 proxy). */
     readonly tokens: number;
 }
+/** 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 declare 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, at most 200
+ *  characters; "" for none. */
+export declare function followUpLine(text: string): string;
+/** The session title's ask (Session.title): no language named, the model follows the message's own. */
+export declare const TITLE_PROMPT = "Write a short title (2 to 8 words) for a conversation that opens with the user's message. Only the title: no quotes, no punctuation at the end.";
+/** 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 declare function cleanTitle(text: string): string;
 /** 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 declare const AUTO_DETACH_MIN_AGE_MS = 2000;
@@ -320,6 +338,18 @@ export declare class AgentSession {
      * CLI's honest degradation.
      */
     sideQuery(options: SideQueryOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    title(firstMessage: string, options?: {
+        readonly signal?: AbortSignalLike;
+    }): Promise<string>;
     /** 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
@@ -341,6 +371,7 @@ export declare class AgentSession {
      * Yields nothing when the session already completed.
      */
     resume(): Run;
+    followUp(options: FollowUpOptions): Promise<string>;
     /**
      * /compact (ADR-0044): compress the older conversation with a model
      * summary. Covers the range (previous summary point, boundary] —

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,39 @@ 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, at most 200
+ *  characters; "" for none. */
+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].slice(0, 199).join("")}\u2026` : bare;
+}
+/** The session title's ask (Session.title): no language named, the model follows the message's own. */
+export const TITLE_PROMPT = "Write a short title (2 to 8 words) for a conversation that opens with the user's 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 +135,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 +814,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 +850,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 +862,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 +899,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 +909,84 @@ 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));
+        let text = "";
+        try {
+            for await (const ev of guarded.stream({
+                ...last,
+                messages: [...last.messages, ...this.#after(last.messages), { role: "user", content: options.ask ?? FOLLOW_UP_ASK }],
+                ...(options.maxTokens !== undefined ? { maxTokens: options.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,7 +45,8 @@
 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";
 /** History that does not parse as a contiguous kiso trajectory. */
 export class StoreCorruptionError extends Error {
@@ -415,6 +416,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 +456,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.53.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.53.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.53.0",
+		"@vincemakes/kiso-provider-openai": "0.53.0",
+		"@vincemakes/kiso-provider-openai-responses": "0.53.0"
 	},
 	"peerDependenciesMeta": {
 		"@vincemakes/kiso-provider-anthropic": {
@@ -44,7 +44,7 @@
 		}
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.52.0",
+		"@vincemakes/kiso-evals": "0.53.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"