diff --git a/.changeset/tracked-subsessions.md b/.changeset/tracked-subsessions.md index 75df729..b1012bd 100644 --- a/.changeset/tracked-subsessions.md +++ b/.changeset/tracked-subsessions.md @@ -1,7 +1,7 @@ --- -"@jmfederico/pi-web": minor +"@jmfederico/pi-web": patch --- -Add tracked subsessions (beta, off by default): agents can spawn child sessions they stay attached to. The new `spawn_subsession` tool starts a child session linked to its parent (recorded in the session tree), notifies the parent when the child stops working, and lets the parent inspect children via `list_subsessions` and `read_subsession`. The completion notice is delivered as a system-authored message (not attributed to the human), and still wakes an idle parent while queueing behind any in-flight work. Unlike the fire-and-forget `spawn_session`, subsessions are observable by their spawner. +Add tracked subsessions (beta, off by default): agents can spawn child sessions they stay attached to. The new `spawn_subsession` tool starts a child session linked to its parent (recorded in the session tree), notifies the parent when the child stops working, and lets the parent inspect children via `list_subsessions`, `check_subsession` (a quick glance at a child's status and latest output), and `read_subsession` (read through a child's transcript with role/content filters, full-content substring search, optional per-value `maxChars` truncation that flags clipped parts, and pagination). The completion notice is delivered as a system-authored message (not attributed to the human), and still wakes an idle parent while queueing behind any in-flight work. Unlike the fire-and-forget `spawn_session`, subsessions are observable by their spawner. The capability is gated behind a beta flag so it can ship without being exposed in releases: enable it with the `PI_WEB_SUBSESSIONS` env var, the `subsessions` config key, or the "Allow agents to start tracked subsessions" toggle in Settings → Session daemon. It also requires `spawnSessions` to be enabled. Requires a manual session daemon restart to take effect. diff --git a/src/client/src/components/settings/SettingsSessiondPanel.ts b/src/client/src/components/settings/SettingsSessiondPanel.ts index 1f58f01..9c1c9e1 100644 --- a/src/client/src/components/settings/SettingsSessiondPanel.ts +++ b/src/client/src/components/settings/SettingsSessiondPanel.ts @@ -67,7 +67,7 @@ export class SettingsSessiondPanel extends LitElement { > Enable the spawn_subsession tools - Beta: agents can start child sessions they stay attached to (spawn_subsession, list_subsessions, read_subsession) and are notified when a child finishes. Requires "Allow agents to start sessions". Off by default. + Beta: agents can start child sessions they stay attached to (spawn_subsession, list_subsessions, check_subsession, read_subsession) and are notified when a child finishes. Requires "Allow agents to start sessions". Off by default.

Effective after environment overrides

diff --git a/src/server/sessions/piSessionService.test.ts b/src/server/sessions/piSessionService.test.ts index 1063d2a..9de755f 100644 --- a/src/server/sessions/piSessionService.test.ts +++ b/src/server/sessions/piSessionService.test.ts @@ -960,12 +960,13 @@ describe("PiSessionService", () => { await service.dispose(); }); - it("read_subsession refuses sessions that are not the caller's children", async () => { + it("check_subsession and read_subsession refuse sessions that are not the caller's children", async () => { const { service } = subsessionService({ allowed: true, cwd: "/workspace-feature" }); await service.start("/workspace"); await service.spawnSubsession({ spawningCwd: "/workspace", parentSessionId: "parent-1", parentSessionFile: "/tmp/parent-1.jsonl", prompt: "go", cwd: "/workspace-feature" }); - await expect(service.readSubsession("someone-else", "child-1")).rejects.toThrow("not one of your subsessions"); + await expect(service.checkSubsession("someone-else", "child-1")).rejects.toThrow("not one of your subsessions"); + await expect(service.readSubsession("someone-else", "child-1", {})).rejects.toThrow("not one of your subsessions"); await service.dispose(); }); diff --git a/src/server/sessions/piSessionService.ts b/src/server/sessions/piSessionService.ts index f1a096d..3562925 100644 --- a/src/server/sessions/piSessionService.ts +++ b/src/server/sessions/piSessionService.ts @@ -32,7 +32,8 @@ import type { SavedPromptAttachment } from "../../shared/apiTypes.js"; import { cwdPathsEqual } from "../workingDirectory.js"; import type { WorkspaceActivityService } from "../activity/workspaceActivityService.js"; import { createSpawnSessionToolDefinition, type SpawnSessionInvocation, type SpawnSessionResult } from "./spawnSessionTool.js"; -import { createSubsessionToolDefinitions, type SpawnSubsessionInvocation, type SpawnSubsessionResult, type SubsessionReadResult, type SubsessionStatus, type SubsessionSummary, type SubsessionToolDeps } from "./spawnSubsessionTool.js"; +import { createSubsessionToolDefinitions, type SpawnSubsessionInvocation, type SpawnSubsessionResult, type SubsessionCheckResult, type SubsessionReadQuery, type SubsessionReadResult, type SubsessionStatus, type SubsessionSummary, type SubsessionToolDeps } from "./spawnSubsessionTool.js"; +import { buildTranscriptView } from "./subsessionTranscript.js"; import type { SpawnTargetDecision, SpawnTargetResolver } from "./spawnTargetResolver.js"; /** @@ -267,7 +268,8 @@ export interface PiSessionServiceDependencies { spawnTargets?: SpawnTargetResolver; /** * Beta: when true (and `spawnTargets` is provided), the tracked-subsession - * tools (`spawn_subsession`, `list_subsessions`, `read_subsession`) are + * tools (`spawn_subsession`, `list_subsessions`, `check_subsession`, + * `read_subsession`) are * registered on every session. Off by default so the capability can ship in * main without being exposed in releases. */ @@ -321,7 +323,8 @@ export class PiSessionService { !subsessionsActive ? undefined : { spawn: (input) => this.spawnSubsession(input), list: (parentSessionId) => this.listSubsessions(parentSessionId), - read: (parentSessionId, sessionId) => this.readSubsession(parentSessionId, sessionId), + check: (parentSessionId, sessionId) => this.checkSubsession(parentSessionId, sessionId), + read: (parentSessionId, sessionId, query) => this.readSubsession(parentSessionId, sessionId, query), }, ); this.createAgentRuntime = deps.createAgentRuntime ?? defaultCreateAgentRuntime; @@ -453,11 +456,8 @@ export class PiSessionService { } /** Status and final result of a subsession, scoped to the caller's children. */ - async readSubsession(parentSessionId: string, sessionId: string): Promise { - if (this.subsessionParents.get(sessionId) !== parentSessionId) { - throw new Error(`Session ${sessionId} is not one of your subsessions`); - } - const session = await this.getOrOpen(sessionId); + async checkSubsession(parentSessionId: string, sessionId: string): Promise { + const session = await this.openSubsession(parentSessionId, sessionId); const messages = historyMessages(session); return { sessionId, @@ -468,6 +468,26 @@ export class PiSessionService { }; } + /** Filtered, paginated transcript of a subsession, scoped to the caller's children. */ + async readSubsession(parentSessionId: string, sessionId: string, query: SubsessionReadQuery): Promise { + const session = await this.openSubsession(parentSessionId, sessionId); + const view = buildTranscriptView(historyMessages(session), query); + return { + sessionId, + cwd: session.sessionManager.getCwd(), + status: await this.subsessionStatus(session), + ...view, + }; + } + + /** Open a session after verifying it is one of the caller's tracked children. */ + private async openSubsession(parentSessionId: string, sessionId: string): Promise { + if (this.subsessionParents.get(sessionId) !== parentSessionId) { + throw new Error(`Session ${sessionId} is not one of your subsessions`); + } + return this.getOrOpen(sessionId); + } + private registerSubsession(parentSessionId: string, childSessionId: string): void { this.subsessionParents.set(childSessionId, parentSessionId); const children = this.subsessionChildren.get(parentSessionId) ?? new Set(); @@ -512,7 +532,7 @@ export class PiSessionService { const status: SubsessionStatus = this.activities.get(childId)?.phase === "error" ? "error" : "idle"; const finalText = finalAssistantText(historyMessages(session)); const preview = finalText === "" ? "(no output)" : truncateForNotification(finalText); - const text = `Subsession ${childId} stopped working (status: ${status}). Latest output:\n\n${preview}\n\nUse read_subsession with sessionId "${childId}" for the full result.`; + const text = `Subsession ${childId} stopped working (status: ${status}). Latest output:\n\n${preview}\n\nUse check_subsession with sessionId "${childId}" for its status and latest output, or read_subsession to look through its full transcript.`; void this.notifyParentOfSubsession(parentId, childId, text); } diff --git a/src/server/sessions/spawnSubsessionTool.test.ts b/src/server/sessions/spawnSubsessionTool.test.ts index 4d5e180..35b4311 100644 --- a/src/server/sessions/spawnSubsessionTool.test.ts +++ b/src/server/sessions/spawnSubsessionTool.test.ts @@ -14,7 +14,8 @@ function tools(deps: Partial) { const full: SubsessionToolDeps = { spawn: deps.spawn ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a" })), list: deps.list ?? vi.fn(() => Promise.resolve([])), - read: deps.read ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a", status: "idle" as const, finalText: "", messageCount: 0 })), + check: deps.check ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a", status: "idle" as const, finalText: "", messageCount: 0 })), + read: deps.read ?? vi.fn(() => Promise.resolve({ sessionId: "x", cwd: "/repos/a", status: "idle" as const, entries: [], total: 0, matched: 0, start: 0, hasMore: false })), }; const definitions = createSubsessionToolDefinitions("/repos/a", full); const find = (name: string) => { @@ -22,7 +23,7 @@ function tools(deps: Partial) { if (tool === undefined) throw new Error(`missing tool ${name}`); return tool; }; - return { spawn: find("spawn_subsession"), list: find("list_subsessions"), read: find("read_subsession") }; + return { spawn: find("spawn_subsession"), list: find("list_subsessions"), check: find("check_subsession"), read: find("read_subsession") }; } function firstText(content: readonly (TextContent | ImageContent)[]): string { @@ -71,22 +72,78 @@ describe("createSubsessionToolDefinitions", () => { expect(result.content[0]).toMatchObject({ type: "text", text: "You have not spawned any subsessions." }); }); - it("read_subsession scopes by parent and returns the final result", async () => { - const read = vi.fn(() => Promise.resolve({ sessionId: "child-1", cwd: "/repos/a", status: "idle" as const, finalText: "all done", messageCount: 4 })); - const { read: readTool } = tools({ read }); + it("check_subsession scopes by parent and returns the final result", async () => { + const check = vi.fn(() => Promise.resolve({ sessionId: "child-1", cwd: "/repos/a", status: "idle" as const, finalText: "all done", messageCount: 4 })); + const { check: checkTool } = tools({ check }); - const result = await readTool.execute("call-4", { sessionId: "child-1" }, undefined, undefined, ctxFor("parent-1", undefined)); + const result = await checkTool.execute("call-4", { sessionId: "child-1" }, undefined, undefined, ctxFor("parent-1", undefined)); - expect(read).toHaveBeenCalledWith("parent-1", "child-1"); + expect(check).toHaveBeenCalledWith("parent-1", "child-1"); expect(result.details).toMatchObject({ sessionId: "child-1", status: "idle", finalText: "all done" }); expect(firstText(result.content)).toContain("all done"); }); + it("check_subsession propagates scope errors so the agent loop reports them", async () => { + const check = vi.fn(() => Promise.reject(new Error("Session child-9 is not one of your subsessions"))); + const { check: checkTool } = tools({ check }); + + await expect(checkTool.execute("call-5", { sessionId: "child-9" }, undefined, undefined, ctxFor("parent-1", undefined))) + .rejects.toThrow("not one of your subsessions"); + }); + + it("read_subsession forwards filter params and renders the transcript", async () => { + const read = vi.fn(() => Promise.resolve({ + sessionId: "child-1", cwd: "/repos/a", status: "idle" as const, + entries: [{ index: 2, role: "assistant" as const, parts: [{ kind: "text" as const, text: "the answer" }] }], + total: 5, matched: 1, start: 2, hasMore: false, + })); + const { read: readTool } = tools({ read }); + + const result = await readTool.execute("call-6", { sessionId: "child-1", roles: ["assistant"], maxChars: 200 }, undefined, undefined, ctxFor("parent-1", undefined)); + + expect(read).toHaveBeenCalledWith("parent-1", "child-1", { roles: ["assistant"], maxChars: 200 }); + expect(result.details).toMatchObject({ sessionId: "child-1", matched: 1 }); + expect(firstText(result.content)).toContain("the answer"); + }); + + it("read_subsession renders raw tool-call args and the truncation marker in the model-facing text", async () => { + const read = vi.fn(() => Promise.resolve({ + sessionId: "child-1", cwd: "/repos/a", status: "idle" as const, + entries: [{ + index: 1, role: "assistant" as const, parts: [ + { kind: "tool_call" as const, toolName: "bash", summary: "ls", args: { command: "ls -la" } }, + { kind: "text" as const, text: "clipped", truncated: { shown: 7, full: 50 } }, + ], + }], + total: 3, matched: 1, start: 1, hasMore: false, + })); + const { read: readTool } = tools({ read }); + + const result = await readTool.execute("call-7", { sessionId: "child-1", includeToolArgs: true }, undefined, undefined, ctxFor("parent-1", undefined)); + const text = firstText(result.content); + expect(text).toContain("command"); // raw args surfaced in text, not only details + expect(text).toContain("ls -la"); + expect(text).toContain("[+43 chars truncated"); // 50 - 7 + }); + + it("read_subsession distinguishes an empty page-window from a zero-match result", async () => { + const read = vi.fn(() => Promise.resolve({ + sessionId: "child-1", cwd: "/repos/a", status: "idle" as const, + entries: [], total: 5, matched: 4, start: 0, hasMore: false, + })); + const { read: readTool } = tools({ read }); + + const result = await readTool.execute("call-8", { sessionId: "child-1", before: 0 }, undefined, undefined, ctxFor("parent-1", undefined)); + const text = firstText(result.content); + expect(text).toContain("4 matched"); // not "nothing matched" + expect(text).not.toContain("nothing matched"); + }); + it("read_subsession propagates scope errors so the agent loop reports them", async () => { const read = vi.fn(() => Promise.reject(new Error("Session child-9 is not one of your subsessions"))); const { read: readTool } = tools({ read }); - await expect(readTool.execute("call-5", { sessionId: "child-9" }, undefined, undefined, ctxFor("parent-1", undefined))) + await expect(readTool.execute("call-9", { sessionId: "child-9" }, undefined, undefined, ctxFor("parent-1", undefined))) .rejects.toThrow("not one of your subsessions"); }); }); diff --git a/src/server/sessions/spawnSubsessionTool.ts b/src/server/sessions/spawnSubsessionTool.ts index a5f447b..5ce2405 100644 --- a/src/server/sessions/spawnSubsessionTool.ts +++ b/src/server/sessions/spawnSubsessionTool.ts @@ -1,5 +1,6 @@ import { Type } from "typebox"; import { defineTool } from "@earendil-works/pi-coding-agent"; +import type { TranscriptContentKind, TranscriptEntry, TranscriptRole, TranscriptView } from "./subsessionTranscript.js"; /** Lifecycle phase of a tracked subsession as seen by its parent. */ export type SubsessionStatus = "working" | "idle" | "error" | "archived" | "unknown"; @@ -26,7 +27,8 @@ export interface SubsessionSummary { status: SubsessionStatus; } -export interface SubsessionReadResult { +/** Quick glance at a subsession: status plus its most recent assistant output. */ +export interface SubsessionCheckResult { sessionId: string; cwd: string; status: SubsessionStatus; @@ -34,10 +36,29 @@ export interface SubsessionReadResult { messageCount: number; } +/** Exploratory transcript read: a filtered, paginated slice of the subsession's history. */ +export interface SubsessionReadResult extends TranscriptView { + sessionId: string; + cwd: string; + status: SubsessionStatus; +} + +/** Filters the parent passes to narrow a transcript read; mirrors {@link TranscriptQuery}. */ +export interface SubsessionReadQuery { + roles?: TranscriptRole[]; + include?: TranscriptContentKind[]; + search?: string; + maxChars?: number; + includeToolArgs?: boolean; + before?: number; + limit?: number; +} + export interface SubsessionToolDeps { spawn(input: SpawnSubsessionInvocation): Promise; list(parentSessionId: string): Promise; - read(parentSessionId: string, sessionId: string): Promise; + check(parentSessionId: string, sessionId: string): Promise; + read(parentSessionId: string, sessionId: string, query: SubsessionReadQuery): Promise; } const SpawnSubsessionParams = Type.Object({ @@ -51,16 +72,95 @@ const SpawnSubsessionParams = Type.Object({ const ListSubsessionsParams = Type.Object({}); -const ReadSubsessionParams = Type.Object({ +const CheckSubsessionParams = Type.Object({ sessionId: Type.String({ description: "Id of a subsession you spawned (as returned by spawn_subsession or list_subsessions).", }), }); +const ReadSubsessionParams = Type.Object({ + sessionId: Type.String({ + description: "Id of a subsession you spawned (as returned by spawn_subsession or list_subsessions).", + }), + roles: Type.Optional(Type.Array( + Type.Union([Type.Literal("assistant"), Type.Literal("user"), Type.Literal("tool"), Type.Literal("system"), Type.Literal("custom")]), + { description: "Message roles to include. Omit for all roles." }, + )), + include: Type.Optional(Type.Array( + Type.Union([Type.Literal("text"), Type.Literal("thinking"), Type.Literal("tool_call"), Type.Literal("tool_result"), Type.Literal("image")]), + { description: "Content kinds to keep within messages. Omit for all kinds." }, + )), + search: Type.Optional(Type.String({ + description: "Case-insensitive substring; keep only messages whose text or tool name matches. Always searches full message content, even when maxChars is set.", + })), + maxChars: Type.Optional(Type.Integer({ + minimum: 0, + description: "Truncate each text/thinking/tool-result value to this many characters; clipped parts are marked '[+N chars truncated]'. Omit for full, untruncated text (there is no default, so truncation only happens when you ask for it).", + })), + includeToolArgs: Type.Optional(Type.Boolean({ + description: "Include raw tool-call arguments (can be large). A compact one-line summary of each call is always shown regardless.", + })), + before: Type.Optional(Type.Integer({ + minimum: 0, + description: "Return only messages before this transcript index; page backward by passing the previous response's 'start'.", + })), + limit: Type.Optional(Type.Integer({ + minimum: 1, + description: "Maximum number of most-recent matching messages to return within the window (returned in chronological order). Defaults to 50.", + })), +}); + function statusLine(summary: SubsessionSummary): string { return `- ${summary.sessionId} [${summary.status}] in ${summary.cwd}`; } +function renderEntry(entry: TranscriptEntry): string { + const header = `#${String(entry.index)} ${entry.role}`; + const body = entry.parts.map(renderPart).filter((line) => line !== "").join("\n"); + return body === "" ? header : `${header}\n${body}`; +} + +function clipNotice(part: TranscriptEntry["parts"][number]): string { + if ((part.kind === "text" || part.kind === "thinking" || part.kind === "tool_result") && part.truncated !== undefined) { + return ` [+${String(part.truncated.full - part.truncated.shown)} chars truncated; re-read with a larger maxChars]`; + } + return ""; +} + +function renderPart(part: TranscriptEntry["parts"][number]): string { + if (part.kind === "text") return `${part.text}${clipNotice(part)}`; + if (part.kind === "thinking") return `[thinking] ${part.text}${clipNotice(part)}`; + if (part.kind === "tool_call") { + // Raw args are only present when the caller asked (includeToolArgs); when + // present, surface them in the model-facing text, not just `details`. + const args = "args" in part && part.args !== undefined ? `\n args: ${JSON.stringify(part.args)}` : ""; + return `[tool ${part.toolName}] ${part.summary}${args}`; + } + if (part.kind === "tool_result") return `[result${part.isError ? " error" : ""}${part.toolName === undefined ? "" : ` ${part.toolName}`}] ${part.text}${clipNotice(part)}`; + return "[image]"; +} + +function renderTranscript(result: SubsessionReadResult): string { + const last = result.entries[result.entries.length - 1]; + // Distinguish "nothing matched at all" (widen filters) from "matches exist but + // this page/window is empty" (page differently) so the agent isn't misled. + const range = last === undefined + ? (result.matched === 0 + ? "no messages matched your filters" + : `no messages in this window (${String(result.matched)} matched outside it)`) + : `messages ${String(result.start)}–${String(last.index)} of ${String(result.total)} (${String(result.matched)} matched)`; + const more = result.hasMore ? `\n\nMore matching messages exist earlier; page back with before: ${String(result.start)}.` : ""; + // Empty entries with matches means the `before` cursor excluded every match + // (they all sit at index >= before): the agent paged too far back and should + // raise `before` or omit it, not page back further. + const body = result.entries.length > 0 + ? result.entries.map(renderEntry).join("\n\n") + : (result.matched === 0 + ? "(nothing matched; try widening roles/include, dropping search, or raising limit)" + : `(no messages before index ${String(result.start)}; all ${String(result.matched)} matches are later — raise 'before' or omit it)`); + return `Subsession ${result.sessionId} [${result.status}] — ${range}:\n\n${body}${more}`; +} + /** * Tools that let an agent spawn *tracked* child sessions and inspect them. * @@ -74,7 +174,7 @@ export function createSubsessionToolDefinitions(spawningCwd: string, deps: Subse const spawnTool = defineTool({ name: "spawn_subsession", label: "Spawn subsession", - description: "Start a tracked child session and send it an initial prompt. The subsession runs independently and a human can interact with it, but unlike spawn_session it is linked to you: you are notified when it stops working (finished, idle, or errored), and you can inspect it with list_subsessions and read_subsession. Use this to delegate work you intend to follow up on.", + description: "Start a tracked child session and send it an initial prompt. The subsession runs independently and a human can interact with it, but unlike spawn_session it is linked to you: you are notified when it stops working (finished, idle, or errored), and you can inspect it with list_subsessions, check_subsession (a quick glance at its latest output), and read_subsession (read through its transcript). Use this to delegate work you intend to follow up on.", promptSnippet: "spawn_subsession: start a tracked child session you will be notified about", parameters: SpawnSubsessionParams, async execute(_toolCallId, params, _signal, _onUpdate, ctx) { @@ -104,15 +204,15 @@ export function createSubsessionToolDefinitions(spawningCwd: string, deps: Subse }, }); - const readTool = defineTool({ - name: "read_subsession", - label: "Read subsession", - description: "Read a subsession you spawned: its status and final result. Returns the subsession's most recent assistant output so you can react to what it produced.", - promptSnippet: "read_subsession: read the result of a subsession you spawned", - parameters: ReadSubsessionParams, + const checkTool = defineTool({ + name: "check_subsession", + label: "Check subsession", + description: "Quick glance at a subsession you spawned: its current status and most recent assistant output. Use this to react to what a subsession produced. When the summary is not enough, use read_subsession to look through its full transcript.", + promptSnippet: "check_subsession: glance at a subsession's status and latest output", + parameters: CheckSubsessionParams, async execute(_toolCallId, params, _signal, _onUpdate, ctx) { const parentSessionId = ctx.sessionManager.getSessionId(); - const result = await deps.read(parentSessionId, params.sessionId); + const result = await deps.check(parentSessionId, params.sessionId); const body = result.finalText === "" ? "(no output yet)" : result.finalText; return { content: [{ type: "text", text: `Subsession ${result.sessionId} [${result.status}]:\n\n${body}` }], @@ -121,5 +221,22 @@ export function createSubsessionToolDefinitions(spawningCwd: string, deps: Subse }, }); - return [spawnTool, listTool, readTool]; + const readTool = defineTool({ + name: "read_subsession", + label: "Read subsession", + description: "Read through the transcript of a subsession you spawned. Returns its messages filtered and paginated however you ask: choose which roles (assistant, user, tool, system, custom) and content kinds (text, thinking, tool_call, tool_result, image) to include, search for a substring (always over full content), cap each value's length with maxChars (omit for full text; clipped parts are flagged so truncation is never silent), optionally include raw tool args, and page backward with 'before'/'limit'. Start narrow (e.g. assistant text with a small maxChars) and widen the filters, raise maxChars, or page further back if you don't find what you need. For just the final result, use check_subsession instead.", + promptSnippet: "read_subsession: read through a subsession's transcript with filters", + parameters: ReadSubsessionParams, + async execute(_toolCallId, params, _signal, _onUpdate, ctx) { + const parentSessionId = ctx.sessionManager.getSessionId(); + const { sessionId, ...query } = params; + const result = await deps.read(parentSessionId, sessionId, query); + return { + content: [{ type: "text", text: renderTranscript(result) }], + details: result, + }; + }, + }); + + return [spawnTool, listTool, checkTool, readTool]; } diff --git a/src/server/sessions/subsessionTranscript.test.ts b/src/server/sessions/subsessionTranscript.test.ts new file mode 100644 index 0000000..4821740 --- /dev/null +++ b/src/server/sessions/subsessionTranscript.test.ts @@ -0,0 +1,206 @@ +import { describe, expect, it } from "vitest"; +import { buildTranscriptView } from "./subsessionTranscript.js"; + +const user = (text: string) => ({ role: "user", content: text }); +const assistant = (text: string) => ({ role: "assistant", content: [{ type: "text", text }] }); +const thinking = (text: string) => ({ role: "assistant", content: [{ type: "thinking", thinking: text }] }); +const toolCall = (name: string, args?: unknown) => ({ role: "assistant", content: [{ type: "toolCall", name, ...(args === undefined ? {} : { arguments: args }) }] }); +const toolResult = (text: string, toolName = "bash", isError = false) => ({ role: "toolResult", toolName, content: text, isError }); +const custom = (text: string) => ({ role: "custom", content: text, customType: "subsession.completion" }); + +describe("buildTranscriptView", () => { + it("returns all entries with stable indices by default", () => { + const messages = [user("do it"), thinking("plan"), toolCall("bash"), toolResult("ok"), assistant("done")]; + const view = buildTranscriptView(messages); + + expect(view.total).toBe(5); + expect(view.matched).toBe(5); + expect(view.entries.map((entry) => entry.index)).toEqual([0, 1, 2, 3, 4]); + expect(view.hasMore).toBe(false); + }); + + it("filters by role", () => { + const messages = [user("do it"), thinking("plan"), assistant("done")]; + const view = buildTranscriptView(messages, { roles: ["assistant"] }); + + expect(view.matched).toBe(2); // thinking + text are both assistant-role + expect(view.entries.every((entry) => entry.role === "assistant")).toBe(true); + }); + + it("filters by content kind, dropping entries left empty", () => { + const messages = [user("do it"), thinking("plan"), assistant("answer"), toolCall("bash")]; + const view = buildTranscriptView(messages, { include: ["text"] }); + + // user text + assistant text survive; thinking-only and tool_call-only entries drop out + expect(view.matched).toBe(2); + expect(view.entries.flatMap((entry) => entry.parts.map((part) => part.kind))).toEqual(["text", "text"]); + }); + + it("does not truncate by default and omits tool args", () => { + const long = "x".repeat(800); + const messages = [assistant(long), toolCall("bash", { command: "ls", extra: "y" })]; + const view = buildTranscriptView(messages); + + const textPart = view.entries[0]?.parts[0]; + if (textPart?.kind !== "text") throw new Error("expected text part"); + expect(textPart.text).toBe(long); + expect(textPart.truncated).toBeUndefined(); + + const callPart = view.entries[1]?.parts[0]; + if (callPart?.kind !== "tool_call") throw new Error("expected tool_call part"); + expect(callPart.summary).toBe("ls"); + expect("args" in callPart).toBe(false); + }); + + it("maxChars clips text and flags it with the full length", () => { + const long = "x".repeat(800); + const messages = [assistant(long)]; + const view = buildTranscriptView(messages, { maxChars: 100 }); + + const textPart = view.entries[0]?.parts[0]; + if (textPart?.kind !== "text") throw new Error("expected text part"); + expect(textPart.text).toBe("x".repeat(100)); + expect(textPart.truncated).toEqual({ shown: 100, full: 800 }); + }); + + it("maxChars does not flag values at or under the cap", () => { + const messages = [assistant("short")]; + const view = buildTranscriptView(messages, { maxChars: 100 }); + const textPart = view.entries[0]?.parts[0]; + if (textPart?.kind !== "text") throw new Error("expected text part"); + expect(textPart.text).toBe("short"); + expect(textPart.truncated).toBeUndefined(); + }); + + it("includeToolArgs returns raw args alongside the summary", () => { + const messages = [toolCall("bash", { command: "ls" })]; + const view = buildTranscriptView(messages, { includeToolArgs: true }); + const callPart = view.entries[0]?.parts[0]; + if (callPart?.kind !== "tool_call") throw new Error("expected tool_call part"); + expect(callPart.summary).toBe("ls"); + expect(callPart.args).toEqual({ command: "ls" }); + }); + + it("search keeps only matching entries across text and tool names", () => { + const messages = [assistant("the auth flow"), assistant("unrelated"), toolResult("error in auth.ts", "read")]; + const view = buildTranscriptView(messages, { search: "auth" }); + + expect(view.matched).toBe(2); + expect(view.entries.map((entry) => entry.index)).toEqual([0, 2]); + }); + + it("search runs against full content even when maxChars would clip the match away", () => { + // The match sits past the clip point; a window-first or clip-first search would miss it. + const text = `${"a".repeat(300)} NEEDLE ${"b".repeat(300)}`; + const messages = [assistant(text)]; + const view = buildTranscriptView(messages, { search: "needle", maxChars: 50 }); + + expect(view.matched).toBe(1); + const textPart = view.entries[0]?.parts[0]; + if (textPart?.kind !== "text") throw new Error("expected text part"); + // The match is found, and the returned (clipped) text honestly flags truncation. + expect(textPart.truncated).toEqual({ shown: 50, full: text.length }); + }); + + it("search matches tool-call arguments even without includeToolArgs", () => { + const messages = [toolCall("bash", { command: "grep NEEDLE src" })]; + const view = buildTranscriptView(messages, { search: "needle" }); + expect(view.matched).toBe(1); + }); + + it("search finds args the display summary would drop (edit/write content, nested, beyond first 3 keys)", () => { + // summarizeToolArgs collapses these to 'edit text replacement' / 'object' / first-3-keys, + // so matching must serialize the full args, not the summary. + const editArgs = { oldText: "before", newText: "NEEDLE_IN_NEWTEXT" }; + const nestedArgs = { a: 1, b: 2, c: 3, payload: { deep: "NEEDLE_NESTED" } }; + const messages = [toolCall("edit", editArgs), toolCall("write", nestedArgs)]; + + expect(buildTranscriptView(messages, { search: "needle_in_newtext" }).matched).toBe(1); + expect(buildTranscriptView(messages, { search: "needle_nested" }).matched).toBe(1); + }); + + it("maxChars boundary: exact length is not flagged, one over is", () => { + const exact = buildTranscriptView([assistant("x".repeat(50))], { maxChars: 50 }).entries[0]?.parts[0]; + if (exact?.kind !== "text") throw new Error("expected text part"); + expect(exact.truncated).toBeUndefined(); + + const over = buildTranscriptView([assistant("x".repeat(51))], { maxChars: 50 }).entries[0]?.parts[0]; + if (over?.kind !== "text") throw new Error("expected text part"); + expect(over.truncated).toEqual({ shown: 50, full: 51 }); + }); + + it("maxChars: 0 clips everything and flags it (not treated as 'no cap')", () => { + const part = buildTranscriptView([assistant("abc")], { maxChars: 0 }).entries[0]?.parts[0]; + if (part?.kind !== "text") throw new Error("expected text part"); + expect(part.text).toBe(""); + expect(part.truncated).toEqual({ shown: 0, full: 3 }); + }); + + it("negative or fractional maxChars is coerced to a safe non-negative integer, never 'no cap'", () => { + const negative = buildTranscriptView([assistant("abc")], { maxChars: -5 }).entries[0]?.parts[0]; + if (negative?.kind !== "text") throw new Error("expected text part"); + expect(negative.text).toBe(""); // coerced to 0, still truncates + expect(negative.truncated).toEqual({ shown: 0, full: 3 }); + + const fractional = buildTranscriptView([assistant("abcdef")], { maxChars: 2.9 }).entries[0]?.parts[0]; + if (fractional?.kind !== "text") throw new Error("expected text part"); + expect(fractional.text).toBe("ab"); // floored to 2 + expect(fractional.truncated).toEqual({ shown: 2, full: 6 }); + }); + + it("empty window with matches reports matched > 0 (paged past all matches)", () => { + const messages = [assistant("a"), assistant("b"), assistant("c")]; + const view = buildTranscriptView(messages, { before: 0 }); + expect(view.entries).toEqual([]); + expect(view.matched).toBe(3); // matches exist, the window just excluded them + expect(view.start).toBe(0); + expect(view.hasMore).toBe(false); + }); + + it("pages from the end and reports hasMore", () => { + const messages = [assistant("a"), assistant("b"), assistant("c"), assistant("d")]; + const view = buildTranscriptView(messages, { limit: 2 }); + + expect(view.entries.map((entry) => entry.index)).toEqual([2, 3]); + expect(view.matched).toBe(4); + expect(view.start).toBe(2); + expect(view.hasMore).toBe(true); + }); + + it("pages backward using before: previous start", () => { + const messages = [assistant("a"), assistant("b"), assistant("c"), assistant("d")]; + const view = buildTranscriptView(messages, { limit: 2, before: 2 }); + + expect(view.entries.map((entry) => entry.index)).toEqual([0, 1]); + expect(view.start).toBe(0); + expect(view.hasMore).toBe(false); + }); + + it("limit bounds matched entries, not raw messages", () => { + const messages = [user("u1"), assistant("a1"), user("u2"), assistant("a2"), user("u3"), assistant("a3")]; + const view = buildTranscriptView(messages, { roles: ["assistant"], limit: 2 }); + + expect(view.matched).toBe(3); + expect(view.entries.map((entry) => entry.index)).toEqual([3, 5]); + expect(view.hasMore).toBe(true); + }); + + it("reports start as before when nothing matches in the window", () => { + const messages = [assistant("a"), assistant("b")]; + const view = buildTranscriptView(messages, { search: "absent" }); + + expect(view.entries).toEqual([]); + expect(view.matched).toBe(0); + expect(view.start).toBe(2); + expect(view.hasMore).toBe(false); + }); + + it("includes custom and system roles", () => { + const messages = [custom("subsession done"), { role: "system", source: "compaction", content: "Compacted history:\n\nstuff" }]; + const all = buildTranscriptView(messages); + expect(all.entries.map((entry) => entry.role)).toEqual(["custom", "system"]); + + const onlyCustom = buildTranscriptView(messages, { roles: ["custom"] }); + expect(onlyCustom.matched).toBe(1); + }); +}); diff --git a/src/server/sessions/subsessionTranscript.ts b/src/server/sessions/subsessionTranscript.ts new file mode 100644 index 0000000..a34126a --- /dev/null +++ b/src/server/sessions/subsessionTranscript.ts @@ -0,0 +1,312 @@ +/** + * Pure helpers for the `read_subsession` tool: turn a subsession's normalized + * history (as produced by `historyMessages`) into a filtered, projected, + * paginated view the parent agent can explore. + * + * The agent drives the read: it picks which roles and content kinds it cares + * about, how much detail it wants, and how far back to look. If a narrow read + * does not answer its question it can widen the filters or page further back, + * the same grep-then-read loop it already uses on files. Everything here is a + * pure transform over an array so it can be unit-tested without a live session. + */ + +/** Message roles the parent can ask for, mapped from raw history roles. */ +export type TranscriptRole = "assistant" | "user" | "tool" | "system" | "custom"; + +/** Content kinds the parent can keep within retained messages. */ +export type TranscriptContentKind = "text" | "thinking" | "tool_call" | "tool_result" | "image"; + +/** + * Marks a text value that the caller's `maxChars` clipped. Carries the full + * length so the consumer knows *how much* was dropped and can re-read with a + * larger `maxChars` (or none). Truncation only ever happens when the caller + * passes `maxChars`, so a `truncated` marker is always something they asked + * for and should expect, never a silent surprise. Its presence (not a `…` + * glyph, which is indistinguishable from real content) is the reliable signal. + */ +export interface TranscriptTruncation { + /** Characters retained in `text`. */ + shown: number; + /** Length of the original, untruncated text. */ + full: number; +} + +export type TranscriptPart = + | { kind: "text"; text: string; truncated?: TranscriptTruncation } + | { kind: "thinking"; text: string; truncated?: TranscriptTruncation } + | { kind: "tool_call"; toolName: string; summary: string; args?: unknown } + | { kind: "tool_result"; toolName?: string; text: string; isError: boolean; truncated?: TranscriptTruncation } + | { kind: "image" }; + +export interface TranscriptEntry { + /** Position of this message in the full transcript (stable across reads). */ + index: number; + role: TranscriptRole; + parts: TranscriptPart[]; +} + +export interface TranscriptQuery { + /** Message roles to include. Omit for all roles. */ + roles?: TranscriptRole[]; + /** Content kinds to keep within retained messages. Omit for all kinds. */ + include?: TranscriptContentKind[]; + /** Case-insensitive substring; keep only entries whose text matches. */ + search?: string; + /** + * Truncate each text/thinking/tool_result value to this many characters, + * flagging clipped parts with `truncated`. Omit for full, untruncated text: + * there is deliberately no default, so truncation only happens when asked for + * and a `truncated` marker is always expected. `search` always runs against + * the full content regardless, so clipping never hides a match. + */ + maxChars?: number; + /** Include raw tool-call arguments (can be large). The compact `summary` is always present. */ + includeToolArgs?: boolean; + /** Upper bound (exclusive) on original index; page backward by passing the previous `start`. */ + before?: number; + /** Keep at most this many of the most-recent matches in the window; entries are returned in chronological order. */ + limit?: number; +} + +export interface TranscriptView { + entries: TranscriptEntry[]; + /** Total messages in the full transcript, before any filtering. */ + total: number; + /** Entries matching the role/content/search filters across the whole transcript. */ + matched: number; + /** Original index of the first returned entry, or `before` when nothing matched in-window. */ + start: number; + /** True when matching entries exist before `start` (page back with `before: start`). */ + hasMore: boolean; +} + +const DEFAULT_LIMIT = 50; +const MAX_LIMIT = 200; + +/** + * Build a filtered, projected, paginated view of a normalized transcript. + * + * Filtering happens before paging for *semantics*, not speed: `search`, the + * `matched` count, and "page backward through matches" all require scanning the + * whole transcript, so a window-first approach could not answer them. The + * tradeoff is an O(total) scan per call (paging a raw window first would be + * cheaper), but `total` is a single session's history and this runs once per + * tool call, so the scan is negligible. The cost that matters for an LLM tool, + * the tokens returned, is bounded by `limit` regardless of ordering; `matched` + * is only a count, so the agent learns whether widening or paging is worthwhile + * without paying to receive every match. + */ +export function buildTranscriptView(messages: readonly unknown[], query: TranscriptQuery = {}): TranscriptView { + const total = messages.length; + // Explicit, caller-owned truncation: only when provided, and a malformed + // value (negative/fractional) is coerced to a safe non-negative integer + // rather than silently meaning "no cap". + const maxChars = query.maxChars === undefined ? undefined : Math.max(0, Math.floor(query.maxChars)); + const includeToolArgs = query.includeToolArgs === true; + const roleFilter = query.roles === undefined ? undefined : new Set(query.roles); + const includeFilter = query.include === undefined ? undefined : new Set(query.include); + const search = query.search !== undefined && query.search !== "" ? query.search.toLowerCase() : undefined; + + // Extract *full* (untruncated) parts and run all filtering/search on them, so + // matching never depends on `maxChars`. Projection (clipping, arg dropping) + // happens later and only on the entries we actually return. + const matchedEntries: FullEntry[] = []; + for (let index = 0; index < total; index++) { + const role = roleOf(messages[index]); + if (role === undefined) continue; + if (roleFilter !== undefined && !roleFilter.has(role)) continue; + + let parts = fullPartsOf(messages[index], role); + if (includeFilter !== undefined) parts = parts.filter((part) => includeFilter.has(part.kind)); + if (parts.length === 0) continue; + if (search !== undefined && !partsMatchSearch(parts, search)) continue; + + matchedEntries.push({ index, role, parts }); + } + + const matched = matchedEntries.length; + const before = clampInteger(query.before ?? total, 0, total); + const limit = clampInteger(query.limit ?? DEFAULT_LIMIT, 1, MAX_LIMIT); + + const inWindow = matchedEntries.filter((entry) => entry.index < before); + const windowed = inWindow.slice(Math.max(0, inWindow.length - limit)); + const entries = windowed.map((entry) => projectEntry(entry, maxChars, includeToolArgs)); + const first = windowed[0]; + const start = first === undefined ? before : first.index; + const hasMore = inWindow.length > windowed.length; + + return { entries, total, matched, start, hasMore }; +} + +/** + * A part before projection: tool calls keep their raw `args`, text-bearing + * parts keep their full untruncated `text`. Search and filtering run on these + * so a match is never hidden by `summary` truncation. + */ +type FullPart = + | { kind: "text"; text: string } + | { kind: "thinking"; text: string } + | { kind: "tool_call"; toolName: string; args?: unknown } + | { kind: "tool_result"; toolName?: string; text: string; isError: boolean } + | { kind: "image" }; + +interface FullEntry { + index: number; + role: TranscriptRole; + parts: FullPart[]; +} + +function partsMatchSearch(parts: readonly FullPart[], needle: string): boolean { + return parts.some((part) => { + if (part.kind === "text" || part.kind === "thinking") return part.text.toLowerCase().includes(needle); + if (part.kind === "tool_result") return part.text.toLowerCase().includes(needle) || (part.toolName?.toLowerCase().includes(needle) ?? false); + // Search the *full* serialized args, not the lossy one-line summary, so a + // term inside edit/write content, nested objects, or long values is found. + if (part.kind === "tool_call") return part.toolName.toLowerCase().includes(needle) || stringifyArgs(part.args).toLowerCase().includes(needle); + return false; + }); +} + +/** Full, search-friendly serialization of tool-call args (distinct from the lossy display summary). */ +function stringifyArgs(args: unknown): string { + if (args === undefined) return ""; + if (typeof args === "string") return args; + try { + // JSON.stringify can return undefined at runtime (e.g. a function/symbol), + // despite its string-typed signature; normalize that to "". + const json: unknown = JSON.stringify(args); + return typeof json === "string" ? json : ""; + } catch { + return ""; + } +} + +/** Project a fully-extracted entry into the returned shape, clipping only when `maxChars` is set. */ +function projectEntry(entry: FullEntry, maxChars: number | undefined, includeToolArgs: boolean): TranscriptEntry { + return { index: entry.index, role: entry.role, parts: entry.parts.map((part) => projectPart(part, maxChars, includeToolArgs)) }; +} + +function projectPart(part: FullPart, maxChars: number | undefined, includeToolArgs: boolean): TranscriptPart { + if (part.kind === "text") return { kind: "text", ...clip(part.text, maxChars) }; + if (part.kind === "thinking") return { kind: "thinking", ...clip(part.text, maxChars) }; + if (part.kind === "tool_result") { + return { + kind: "tool_result", + ...(part.toolName === undefined ? {} : { toolName: part.toolName }), + isError: part.isError, + ...clip(part.text, maxChars), + }; + } + if (part.kind === "tool_call") { + return { + kind: "tool_call", + toolName: part.toolName, + summary: summarizeToolArgs(part.args), + ...(includeToolArgs && part.args !== undefined ? { args: part.args } : {}), + }; + } + return { kind: "image" }; +} + +/** Clip text to `maxChars`, attaching a `truncated` marker when it actually shortens. */ +function clip(text: string, maxChars: number | undefined): { text: string; truncated?: TranscriptTruncation } { + if (maxChars === undefined || text.length <= maxChars) return { text }; + return { text: text.slice(0, maxChars), truncated: { shown: maxChars, full: text.length } }; +} + +/** Map a raw history message to one of the agent-facing roles, or undefined to drop it. */ +function roleOf(message: unknown): TranscriptRole | undefined { + const role = getString(message, "role"); + if (role === "assistant") return "assistant"; + if (role === "user") return "user"; + if (role === "toolResult") return "tool"; + if (role === "custom") return "custom"; + if (role === "system") return "system"; + return undefined; +} + +/** Extract a message's *full* (untruncated) parts; projection happens later. */ +function fullPartsOf(message: unknown, role: TranscriptRole): FullPart[] { + if (role === "tool") return toolResultParts(message); + const content = getProperty(message, "content"); + if (typeof content === "string") return content === "" ? [] : [{ kind: "text", text: content }]; + if (!Array.isArray(content)) return []; + return content.flatMap(contentPart); +} + +function toolResultParts(message: unknown): FullPart[] { + const text = stringifyContent(getProperty(message, "content")) || (getString(message, "text") ?? ""); + const toolName = getString(message, "toolName"); + const isError = getProperty(message, "isError") === true; + return [{ kind: "tool_result", ...(toolName === undefined ? {} : { toolName }), text, isError }]; +} + +function contentPart(part: unknown): FullPart[] { + const type = getString(part, "type"); + if (type === "text") { + const text = getString(part, "text") ?? ""; + return text === "" ? [] : [{ kind: "text", text }]; + } + if (type === "thinking") { + const text = getString(part, "thinking") ?? getString(part, "text") ?? ""; + return text === "" ? [] : [{ kind: "thinking", text }]; + } + if (type === "toolCall") { + const toolName = getString(part, "name") ?? "tool"; + const args = getProperty(part, "arguments"); + return [{ kind: "tool_call", toolName, ...(args === undefined ? {} : { args }) }]; + } + if (type === "image") return [{ kind: "image" }]; + return []; +} + +/** Compact one-line description of tool arguments (mirrors the UI's summary). */ +function summarizeToolArgs(args: unknown): string { + if (!isRecord(args)) return typeof args === "string" ? args : ""; + const command = getString(args, "command"); + if (command !== undefined) return command; + const path = getString(args, "path"); + if (path !== undefined) return path; + if (typeof args["oldText"] === "string" && typeof args["newText"] === "string") return "edit text replacement"; + const edits = args["edits"]; + if (Array.isArray(edits)) return `${String(edits.length)} edit${edits.length === 1 ? "" : "s"}`; + const entries = Object.entries(args).filter(([, value]) => value != null).slice(0, 3); + return entries.map(([key, value]) => `${key}: ${shortValue(value)}`).join(" · "); +} + +function shortValue(value: unknown): string { + if (typeof value === "string") return value.length > 80 ? `${value.slice(0, 77)}…` : value; + if (typeof value === "number" || typeof value === "boolean") return String(value); + if (Array.isArray(value)) return `${String(value.length)} item${value.length === 1 ? "" : "s"}`; + if (typeof value === "object" && value !== null) return "object"; + return ""; +} + +function stringifyContent(content: unknown): string { + if (typeof content === "string") return content; + if (Array.isArray(content)) { + return content + .map((part) => (getString(part, "type") === "image" ? "[image]" : getString(part, "text") ?? "")) + .filter((text) => text !== "") + .join("\n"); + } + return ""; +} + +function clampInteger(value: number, min: number, max: number): number { + if (!Number.isFinite(value)) return max; + return Math.max(min, Math.min(max, Math.floor(value))); +} + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null; +} + +function getProperty(value: unknown, key: string): unknown { + return isRecord(value) ? value[key] : undefined; +} + +function getString(value: unknown, key: string): string | undefined { + const property = getProperty(value, key); + return typeof property === "string" ? property : undefined; +} diff --git a/src/shared/apiTypes.ts b/src/shared/apiTypes.ts index c14fe1e..b1816e2 100644 --- a/src/shared/apiTypes.ts +++ b/src/shared/apiTypes.ts @@ -63,7 +63,8 @@ export interface PiWebConfigValues { spawnSessions?: boolean; /** * Beta: when true, LLMs can start tracked child sessions via the - * spawn_subsession / list_subsessions / read_subsession tools. Off by default + * spawn_subsession / list_subsessions / check_subsession / read_subsession + * tools. Off by default * while the capability stabilizes. Requires spawnSessions to be enabled. */ subsessions?: boolean;