From 8c42d321194c24d24da7b1b4396480eaf208575a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 18:34:36 +0000 Subject: [PATCH 01/58] feat(engine): record where a turn's history starts and open the window reads (FIX-1613) Each turn records historyStart on its request once earlier turns fall out of its history window (one extra row read tells). Blocks get a read-only ctx.session.window, history({ afterRequestId }), and items.turns() listing the window's turns and open ones, or named turns by id within the session. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01NczDiEHd9ZKT1vum6nfnPs --- packages/core/src/index.ts | 3 + packages/core/src/types/index.ts | 3 + packages/core/src/types/scope.ts | 61 ++++++ .../src/context/createExecutionContext.ts | 107 +++++++++- packages/engine/src/context/history.ts | 18 +- packages/engine/src/stores/types.ts | 8 + packages/engine/test/history-start.test.ts | 201 ++++++++++++++++++ packages/engine/test/history-window.test.ts | 6 +- 8 files changed, 396 insertions(+), 11 deletions(-) create mode 100644 packages/engine/test/history-start.test.ts diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index ab634173f2..2cacf6425a 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -13,8 +13,11 @@ export type { LooseBlockContext, } from "./types/block"; export type { + HistoryTurn, + HistoryTurnQuery, OrgScopeHandle, RequestScopeHandle, + SessionHistoryWindow, SessionScopeHandle, StopRequestOutcome, UserScopeHandle, diff --git a/packages/core/src/types/index.ts b/packages/core/src/types/index.ts index 511e828230..2b7c4ebe46 100644 --- a/packages/core/src/types/index.ts +++ b/packages/core/src/types/index.ts @@ -362,6 +362,8 @@ export { export type { JournalEntry, JournalEntryInput, + HistoryTurn, + HistoryTurnQuery, ItemQuery, LLMMessage, Message, @@ -373,6 +375,7 @@ export type { ScopeIdentity, ScopeType, SessionItem, + SessionHistoryWindow, SessionItemViews, SessionMetadata, SessionMetadataInput, diff --git a/packages/core/src/types/scope.ts b/packages/core/src/types/scope.ts index 76d65f5702..80ca6424d3 100644 --- a/packages/core/src/types/scope.ts +++ b/packages/core/src/types/scope.ts @@ -85,6 +85,54 @@ export type ItemQuery = { * conversation without the request that is running now. */ includeInFlight?: boolean; + /** + * `history()` only: start after this turn (a request id), leaving it and + * every earlier turn out. A turn the window no longer holds is older than + * every turn it does, so naming one leaves the history whole. Applied before + * `limit`. A history summary narrows with it: the summary stands for the + * turns up to its mark. + */ + afterRequestId?: string; +}; + +/** + * One past turn of a session, as `items.turns()` lists it: the request that is + * the turn, when it started, whether it has settled, and the messages the model + * would read for it. + */ +export type HistoryTurn = { + requestId: string; + startedAtMs: number; + /** + * Whether the turn has finished for good. A turn still running, suspended on + * a gate, or interrupted and parked to run again has not, and carries no + * messages: what it says is not final until it settles. + */ + settled: boolean; + messages: LLMMessage[]; +}; + +/** Which turns `items.turns()` lists. */ +export type HistoryTurnQuery = { + /** + * These turns, by request id, whether or not the window still holds them. + * Only this session's turns are read; an id that names none is left out. + */ + requestIds?: readonly string[]; +}; + +/** + * The history window this request loaded (`session.historyWindow`), read-only. + */ +export type SessionHistoryWindow = { + /** How many past turns the window holds. */ + readonly turns: number; + /** + * The first turn the window holds, when earlier turns have fallen out of it. + * Absent while every earlier turn is still in the window. The request record + * carries the same mark as `historyStart`. + */ + readonly startRequestId?: string; }; export type SessionItemViews = { @@ -108,6 +156,14 @@ export type SessionItemViews = { * default (e.g., a long-running sub-agent pulling its own prior outputs). */ selectForContext: (query?: ItemQuery) => SessionItem[]; + /** + * The session's past turns, oldest first. With no query: the turns the + * window holds, plus any turn of this session that has not settled yet + * (running, suspended, or parked), so a caller can tell which turns are + * still open. With `requestIds`: those turns, read from the store when the + * window no longer holds them. + */ + turns: (query?: HistoryTurnQuery) => Promise; }; export type Message = { @@ -220,6 +276,11 @@ export type SessionScopeHandle< state: Readonly; metadata: Readonly; items: SessionItemViews; + /** + * The history window this request loaded. Absent on a context that loads no + * history (a test double, for one). + */ + readonly window?: SessionHistoryWindow; appendJournal(entry: JournalEntryInput): Promise; getJournal(options?: { limit?: number; offset?: number }): Promise; setMetadata(input: SessionMetadataInput): Promise; diff --git a/packages/engine/src/context/createExecutionContext.ts b/packages/engine/src/context/createExecutionContext.ts index 6f73ab3386..f826dc8aac 100644 --- a/packages/engine/src/context/createExecutionContext.ts +++ b/packages/engine/src/context/createExecutionContext.ts @@ -6,6 +6,8 @@ import type { JournalEntry, JournalEntryInput, JsonObject, + HistoryTurn, + HistoryTurnQuery, LLMMessage, OrgScopeHandle, RequestScopeHandle, @@ -145,6 +147,8 @@ import { outputItemToSessionItem, createSessionItemViews, buildJournalEntry, + expandRequestToMessages, + LLM_AUDIENCE_TYPES, } from "./history"; import { shouldPersistScopeChange, wrapStateOpsWithEmit } from "./scope-emit"; import { @@ -758,9 +762,16 @@ export async function createExecutionContext< throw new RequestOwnerMismatchError(requestId); } + // The same filter as the session's reads; see `sessionRequestScope`. + const turnScope = sessionRequestScope( + sessionId, + loadedSession ?? { userId, orgId: options.orgId, flowKind: flow.kind, flowId: flow.id }, + options.tenantId + ); + // Parallelize the remaining independent store lookups — user, org, and the // history window don't depend on each other for the initial load. - const [loadedUser, loadedOrg, priorRequests] = await Promise.all([ + const [loadedUser, loadedOrg, listedPriorRequests] = await Promise.all([ userKey !== undefined ? stores.user.get(userKey) : undefined, optionsOrgKey !== undefined ? stores.org.get(optionsOrgKey) : undefined, // The N most-recently-started past turns (`PAST_TURN_STATUSES`). The @@ -771,14 +782,12 @@ export async function createExecutionContext< // robust to out-of-order metadata writes. `items` reconstruct cross-turn // history. stores.request.list({ - // The same filter as the session's reads; see `sessionRequestScope`. - ...sessionRequestScope( - sessionId, - loadedSession ?? { userId, orgId: options.orgId, flowKind: flow.kind, flowId: flow.id }, - options.tenantId - ), + ...turnScope, status: PAST_TURN_STATUSES, - limit: historyWindowTurns, + // One row past the window, read only to learn whether an earlier turn + // fell out of it (FIX-1613's `historyStart`); it is dropped below, + // before anything reads the window. + limit: historyWindowTurns + 1, orderBy: "startedAtMs", withItems: true }) @@ -791,6 +800,15 @@ export async function createExecutionContext< // off has no result to show), then sort ascending for stable history // ordering. Reused by all()/client() (via priorItems) and history() (via // loadLLMHistory). + // The window itself: the N most recently started, oldest dropped when the + // read found one more. `historyStart` names the first turn the window holds + // when that extra row says an earlier turn is out of view. + const byStart = [...listedPriorRequests].sort((a, b) => a.startedAtMs - b.startedAtMs); + const priorRequests = byStart.length > historyWindowTurns ? byStart.slice(byStart.length - historyWindowTurns) : byStart; + const historyStart = + byStart.length > historyWindowTurns && priorRequests[0] !== undefined + ? { requestId: priorRequests[0].id } + : undefined; const retried = retriedIds(priorRequests, options.metadata); // A gate read that fails costs this turn a view that may show a parked // turn, never the turn itself: nothing is treated as parked, and it is logged. @@ -810,6 +828,59 @@ export async function createExecutionContext< .map((r) => (r.status === "interrupted" && r.items !== undefined ? { ...r, items: r.items.filter((i) => i.status !== "in_progress") } : r)) .sort((a, b) => a.startedAtMs - b.startedAtMs); + // `items.turns()` (FIX-1613): the window's turns and every turn of this + // session still open, each marked settled or not, or named turns read by id + // wherever they are. A history summary reads it to fold settled turns + // before they leave the window and to come back for one that left open. + const turnMessages = (record: RequestRecord): LLMMessage[] => + expandRequestToMessages( + record.status === "interrupted" + ? (record.items ?? []).filter((i) => i.status !== "in_progress") + : record.items ?? [], + LLM_AUDIENCE_TYPES, + undefined + ); + const historyTurn = (record: RequestRecord, settled: boolean): HistoryTurn => ({ + requestId: record.id, + startedAtMs: record.startedAtMs, + settled, + messages: settled ? turnMessages(record) : [] + }); + const isParked = async (record: RequestRecord): Promise => { + if (record.status !== "interrupted") return false; + try { + return (await parkedInterruptedIds(options.effectiveRuntimeConfig?.durabilityProvider, [record])).has(record.id); + } catch { + // The same reading the window load takes when a gate read fails. + return false; + } + }; + const readTurns = async (query?: HistoryTurnQuery): Promise => { + if (query?.requestIds !== undefined) { + const turns: HistoryTurn[] = []; + for (const id of new Set(query.requestIds)) { + if (id === requestId) continue; + const record = priorRequests.find((r) => r.id === id) ?? (await stores.request.get(id)); + // Read by id, so held to the session's scope: an id from anywhere + // never reads another session's turn. + if (record === undefined || !requestInSessionScope(record, turnScope)) continue; + const open = record.status === "in_progress" || record.status === "suspended" || (await isParked(record)); + turns.push(historyTurn(record, !open)); + } + return turns.sort((a, b) => a.startedAtMs - b.startedAtMs); + } + const windowTurns = priorRequests + .filter((r) => r.id !== requestId && !(r.status === "interrupted" && retried.has(r.id))) + .map((r) => historyTurn(r, !parked.has(r.id))); + const listed = new Set(windowTurns.map((t) => t.requestId)); + const openTurns = ( + await stores.request.list({ ...turnScope, status: ["in_progress", "suspended"], orderBy: "startedAtMs" }) + ) + .filter((r) => r.id !== requestId && !listed.has(r.id)) + .map((r) => historyTurn(r, false)); + return [...windowTurns, ...openTurns].sort((a, b) => a.startedAtMs - b.startedAtMs); + }; + // Build prior items from the settled prior request records. This replaces the // deprecated SessionRecord.items field — items are canonical on request records. const priorItems: SessionItem[] = []; @@ -1588,6 +1659,20 @@ export async function createExecutionContext< throw new Error(`Request "${requestId}" could not be initialized`); } + // Where the turns this request reads begin (FIX-1613), on the record a + // screen lists. Written onto the held record too: every full-record writer + // builds from it, and a stale copy would write the mark back out. + if (historyStart !== undefined && requestRecord.historyStart?.requestId !== historyStart.requestId) { + await stores.request.setFieldsIfStatus( + requestId, + { historyStart }, + ["in_progress", "suspended"], + Date.now(), + resolveRequestIncarnation(requestRecord as RequestRecord) + ); + requestRecord = { ...requestRecord, historyStart }; + } + const wave1Start = Date.now(); const [sessionContentFromStore, userContentFromStore, orgContentFromStore] = await Promise.all([ loadScopeContentByBuckets("session", sessionFlowLevelConfigs), @@ -2853,7 +2938,13 @@ export async function createExecutionContext< ...(s.tags !== undefined ? { tags: s.tags } : {}) }; }, + // The window this request loaded (FIX-1613), read-only. + window: { + turns: historyWindowTurns, + ...(historyStart !== undefined ? { startRequestId: historyStart.requestId } : {}) + }, items: createSessionItemViews(priorItems, settledPriorRequests, { + readTurns, tokenCounter, readLiveItems, resolveModelId: () => { diff --git a/packages/engine/src/context/history.ts b/packages/engine/src/context/history.ts index 3f0bdaa53a..51a86686c1 100644 --- a/packages/engine/src/context/history.ts +++ b/packages/engine/src/context/history.ts @@ -8,6 +8,8 @@ */ import type { + HistoryTurn, + HistoryTurnQuery, ItemQuery, JournalEntry, JournalEntryInput, @@ -343,7 +345,7 @@ export async function loadLLMHistory( const allowedRoles = query?.roles ? new Set(query.roles) : undefined; const selectedTurns = await selectRequestsByLimit( - priorRequests, + afterRequest(priorRequests, query?.afterRequestId), query?.limit, tokenCounter, resolveModelId, @@ -370,6 +372,17 @@ export async function loadLLMHistory( return trimOrphanedToolMessages(messages); } +/** + * The turns after `requestId`, for `history({ afterRequestId })`. A turn the + * window does not hold is older than every turn it does, so naming one (or + * none) leaves the turns whole. + */ +function afterRequest(priorRequests: RequestRecord[], requestId: string | undefined): RequestRecord[] { + if (requestId === undefined) return priorRequests; + const index = priorRequests.findIndex((r) => r.id === requestId); + return index === -1 ? priorRequests : priorRequests.slice(index + 1); +} + /** * Converts an OutputItem (from the response emitter) to a SessionItem * so it can be included in the all() view alongside historical items. @@ -467,6 +480,8 @@ export function createSessionItemViews( tokenCounter: TokenCounter; resolveModelId: () => string; readLiveItems?: () => RuntimeItem[]; + /** Backs `turns()`; it reads beyond the loaded window, so the context supplies it. */ + readTurns?: (query?: HistoryTurnQuery) => Promise; } ): SessionItemViews { // Compute once — priorItems is immutable for the request lifetime. @@ -533,6 +548,7 @@ export function createSessionItemViews( options.readLiveItems ), selectForContext: (query) => select(query), + turns: (query) => options.readTurns?.(query) ?? Promise.resolve([]), }; } diff --git a/packages/engine/src/stores/types.ts b/packages/engine/src/stores/types.ts index b95586d48e..2aef726eb8 100644 --- a/packages/engine/src/stores/types.ts +++ b/packages/engine/src/stores/types.ts @@ -173,6 +173,14 @@ export type RequestRecord = ScopeRecordB source: string; status: RequestStatus; startedAtMs: number; + /** + * Where the turns this request read begin (FIX-1613): the first past turn + * its history window held, when earlier turns had fallen out of it. A + * screen draws its divider before that request and says the turns above it + * are out of view. Absent when every earlier turn was in the window, and on + * records written before this field existed (guard with `== null`, BP-030). + */ + historyStart?: { requestId: string }; completedAtMs?: number; /** * When the request's run finished writing under this id: set as the run's diff --git a/packages/engine/test/history-start.test.ts b/packages/engine/test/history-start.test.ts new file mode 100644 index 0000000000..45517ab2a0 --- /dev/null +++ b/packages/engine/test/history-start.test.ts @@ -0,0 +1,201 @@ +/** + * Tests for the history window's mark and the generic reads a history summary + * builds on (FIX-1613): `historyStart` on the request record, the read-only + * `ctx.session.window`, `history({ afterRequestId })`, and `items.turns()`. + * + * Each turn records where the turns it read begin, so a screen can draw a + * divider before them and say the turns above are out of view. A summary + * (core's `historySummary`) reads the window to know which turns are about to + * leave it, narrows history to the turns after its mark, and reads a turn that + * left the window by id once it settles. + */ +import type { MessageItem, OutputItem } from "@flow-state-dev/core/items"; +import { DEFAULT_ORG_ID, defineFlow, handler } from "@flow-state-dev/core"; +import { describe, expect, it } from "vitest"; +import { z } from "zod"; +import { createExecutionContext, createInMemoryStores } from "../src"; +import type { RequestRecord, StoreRegistry } from "../src/stores/types"; + +const noopHandler = handler({ name: "noop", execute: () => "ok" }); + +function assistantMessage(requestId: string, text: string): MessageItem { + return { + id: `${requestId}_msg`, + type: "message", + role: "assistant", + content: [{ type: "output_text", text }], + status: "completed", + requestId, + itemIndex: 0, + provenance: { blockName: "gen", blockInstanceId: "gen_1", phase: "main" }, + ts: 100 + }; +} + +function turn(sessionId: string, n: number, overrides: Partial = {}): RequestRecord { + const id = `req_${n}`; + return { + id, + flowKind: "mark-flow", + flowId: "mark-flow", + orgId: DEFAULT_ORG_ID, + actionName: "run", + source: "http", + userId: "u1", + sessionId, + status: "completed", + startedAtMs: 1000 + n, + completedAtMs: 1000 + n + 1, + version: 1, + createdAt: 1000 + n, + updatedAt: 1000 + n + 1, + state: {}, + items: [assistantMessage(id, `turn ${n}`) as unknown as OutputItem], + ...overrides + }; +} + +async function seedTurns(stores: StoreRegistry, sessionId: string, count: number): Promise { + for (let n = 1; n <= count; n++) { + await stores.request.set(`req_${n}`, turn(sessionId, n), "any"); + } +} + +function makeFlow(turns: number) { + return defineFlow({ + kind: "mark-flow", + session: { historyWindow: { turns } }, + actions: { run: { inputSchema: z.string(), block: noopHandler } } + })(); +} + +async function contextFor(stores: StoreRegistry, sessionId: string, turns: number) { + return createExecutionContext({ + orgId: DEFAULT_ORG_ID, + flow: makeFlow(turns), + actionName: "run", + requestId: "req_cur", + sessionId, + userId: "u1", + stores + }); +} + +function textOf(message: { content: unknown }): string { + return Array.isArray(message.content) + ? message.content.map((c: { text?: string }) => c.text ?? "").join("") + : String(message.content); +} + +describe("historyStart: where the turns a request read begin", () => { + it("records the first turn the window holds once earlier turns fall out of it", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_out", 5); + + const ctx = await contextFor(stores, "sess_out", 3); + + // The window still holds exactly three turns: the extra row read to learn + // whether anything fell out never reaches history. + expect((await ctx.session.items.history()).map(textOf)).toEqual(["turn 3", "turn 4", "turn 5"]); + expect(ctx.session.window).toEqual({ turns: 3, startRequestId: "req_3" }); + const record = await stores.request.get("req_cur"); + expect(record?.historyStart).toEqual({ requestId: "req_3" }); + }); + + it("records nothing while every earlier turn is still in the window", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_in", 3); + + const ctx = await contextFor(stores, "sess_in", 3); + + expect(ctx.session.window).toEqual({ turns: 3 }); + const record = await stores.request.get("req_cur"); + expect(record?.historyStart).toBeUndefined(); + }); +}); + +describe("history({ afterRequestId })", () => { + it("starts the history after the named turn", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_after", 5); + + const ctx = await contextFor(stores, "sess_after", 5); + + const messages = await ctx.session.items.history({ afterRequestId: "req_3" }); + expect(messages.map(textOf)).toEqual(["turn 4", "turn 5"]); + }); + + it("leaves the history whole when the named turn is older than the window", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_old", 5); + + const ctx = await contextFor(stores, "sess_old", 3); + + const messages = await ctx.session.items.history({ afterRequestId: "req_1" }); + expect(messages.map(textOf)).toEqual(["turn 3", "turn 4", "turn 5"]); + }); + + it("applies a limit after the narrowing", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_lim", 5); + + const ctx = await contextFor(stores, "sess_lim", 5); + + const messages = await ctx.session.items.history({ afterRequestId: "req_3", limit: { turns: 5 } }); + expect(messages.map(textOf)).toEqual(["turn 4", "turn 5"]); + }); +}); + +describe("items.turns()", () => { + it("lists the window's turns oldest first, each with its id, start and messages", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_turns", 4); + + const ctx = await contextFor(stores, "sess_turns", 3); + + const turns = await ctx.session.items.turns(); + expect(turns.map((t) => [t.requestId, t.startedAtMs, t.settled, t.messages.map(textOf)])).toEqual([ + ["req_2", 1002, true, ["turn 2"]], + ["req_3", 1003, true, ["turn 3"]], + ["req_4", 1004, true, ["turn 4"]] + ]); + }); + + it("lists a turn that has not settled as unsettled, with no messages", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_open", 3); + await stores.request.set("req_2", turn("sess_open", 2, { status: "suspended", completedAtMs: undefined }), "any"); + + const ctx = await contextFor(stores, "sess_open", 5); + + const turns = await ctx.session.items.turns(); + expect(turns.map((t) => [t.requestId, t.settled, t.messages.length])).toEqual([ + ["req_1", true, 1], + ["req_2", false, 0], + ["req_3", true, 1] + ]); + }); + + it("reads a turn that left the window by id", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_byid", 5); + + const ctx = await contextFor(stores, "sess_byid", 2); + + const turns = await ctx.session.items.turns({ requestIds: ["req_1"] }); + expect(turns.map((t) => [t.requestId, t.settled, t.messages.map(textOf)])).toEqual([ + ["req_1", true, ["turn 1"]] + ]); + }); + + it("never reads another session's turn by id", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_mine", 2); + await stores.request.set("req_other", { ...turn("sess_theirs", 9), id: "req_other" }, "any"); + + const ctx = await contextFor(stores, "sess_mine", 5); + + const turns = await ctx.session.items.turns({ requestIds: ["req_other", "req_missing"] }); + expect(turns).toEqual([]); + }); +}); diff --git a/packages/engine/test/history-window.test.ts b/packages/engine/test/history-window.test.ts index 27b2a6572f..f2f9932cb8 100644 --- a/packages/engine/test/history-window.test.ts +++ b/packages/engine/test/history-window.test.ts @@ -92,7 +92,9 @@ describe("history windowing (Slice C)", () => { flowKind: "win-flow", flowId: "win-flow", status: ["completed", "interrupted"], - limit: 50, + // The 50-turn window plus the one row read to learn whether an earlier + // turn fell out of it (FIX-1613's `historyStart`). + limit: 51, orderBy: "startedAtMs", withItems: true }); @@ -112,7 +114,7 @@ describe("history windowing (Slice C)", () => { stores }); - expect(listSpy).toHaveBeenCalledWith(expect.objectContaining({ limit: 7 })); + expect(listSpy).toHaveBeenCalledWith(expect.objectContaining({ limit: 8 })); }); it("bounds the default history() to the window, keeping the most recent turns", async () => { From 822db6965ea12bac053ad457b0474653f7215ee1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 18:43:54 +0000 Subject: [PATCH 02/58] feat(core): historySummary capability and fold, and a capability history key (FIX-1613) utility.historySummary({ summarize }) returns a capability (a session resource holding the running summary, the summary as context, history read after its mark) and a fold step the flow runs before the answering generator. The fold starts while the oldest unfolded turn is in the oldest quarter of the window, keeps unsettled turns by id and folds them once they settle, and writes with a version check. Capabilities gain a generator-only history preset key that narrows every history read of the block. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01NczDiEHd9ZKT1vum6nfnPs --- packages/core/src/blocks/generator.ts | 69 ++++- packages/core/src/capability/merge.ts | 14 + packages/core/src/capability/types.ts | 12 + packages/core/src/utility/history-summary.ts | 254 ++++++++++++++++++ packages/core/src/utility/index.ts | 11 + packages/core/test/capability-history.test.ts | 123 +++++++++ packages/engine/test/history-summary.test.ts | 184 +++++++++++++ 7 files changed, 665 insertions(+), 2 deletions(-) create mode 100644 packages/core/src/utility/history-summary.ts create mode 100644 packages/core/test/capability-history.test.ts create mode 100644 packages/engine/test/history-summary.test.ts diff --git a/packages/core/src/blocks/generator.ts b/packages/core/src/blocks/generator.ts index 5af2155f5b..5f1c8bee64 100644 --- a/packages/core/src/blocks/generator.ts +++ b/packages/core/src/blocks/generator.ts @@ -59,6 +59,7 @@ import type { InferCapabilitySessionState, MergeTargetSchemas, Prettify, + PresetDef, UsesEntry, } from "../capability/types"; @@ -110,6 +111,8 @@ const DEFAULT_REPAIR_ATTEMPTS = 1; interface DynamicCapSurface { contextEntries: Array; + /** History query entries (FIX-1613) — see `PresetDef.history`. */ + historyEntries: Array>; tools: GeneratorTool[]; /** Fence-exempt controls (FIX-1393) — see `PresetDef.controlTools`. */ controlTools: GeneratorTool[]; @@ -152,6 +155,7 @@ async function resolveDynamicCapSurface( } const contextEntries: Array = []; + const historyEntries: Array> = []; const tools: GeneratorTool[] = []; const controlTools: GeneratorTool[] = []; @@ -163,6 +167,7 @@ async function resolveDynamicCapSurface( for (const nested of flattened) { const nestedSurface = await resolveDynamicCapSurface(nested, ctx, collect); contextEntries.push(...nestedSurface.contextEntries); + historyEntries.push(...nestedSurface.historyEntries); tools.push(...nestedSurface.tools); controlTools.push(...nestedSurface.controlTools); } @@ -173,6 +178,9 @@ async function resolveDynamicCapSurface( const entries = Array.isArray(preset.context) ? preset.context : [preset.context]; contextEntries.push(...entries); } + if (preset.history !== undefined) { + historyEntries.push(preset.history); + } if (collect.tools && preset.tools) { if (Array.isArray(preset.tools)) { tools.push(...preset.tools); @@ -191,7 +199,55 @@ async function resolveDynamicCapSurface( } } - return { contextEntries, tools, controlTools }; + return { contextEntries, historyEntries, tools, controlTools }; +} + +/** + * The query the generator's capabilities add to its history reads (FIX-1613): + * every `history` entry, static then dynamic, resolved against this run's + * context and merged in order, later keys winning. `undefined` when none + * contributes. + */ +async function resolveCapabilityHistoryQuery( + staticEntries: ReadonlyArray>, + dynamicUses: ReadonlyArray<(ctx: BlockContext) => readonly CapabilityRef[]>, + blockItemVisibility: ItemVisibility | undefined, + ctx: BlockContext, +): Promise { + const entries = [...staticEntries]; + for (const resolver of dynamicUses) { + for (const cap of resolver(ctx)) { + if (!capabilityMatchesAgent(cap, blockItemVisibility)) continue; + const surface = await resolveDynamicCapSurface(cap, ctx, { tools: false, controlTools: false }); + entries.push(...surface.historyEntries); + } + } + if (entries.length === 0) return undefined; + let query: ItemQuery = {}; + for (const entry of entries) { + query = { ...query, ...(typeof entry === "function" ? await entry(ctx) : entry) }; + } + return query; +} + +/** + * `ctx` with `session.items.history` reading under `query`, the read's own keys + * on top. Built by prototype so every other property, getters included, still + * reads through to the run's context. + */ +function withHistoryQuery(ctx: BlockContext, query: ItemQuery): BlockContext { + const session = ctx.session as BlockContext["session"] | undefined; + if (session?.items === undefined) return ctx; + const baseItems = session.items; + const items = Object.create(baseItems) as typeof baseItems; + Object.defineProperty(items, "history", { + value: (own?: ItemQuery) => baseItems.history({ ...query, ...own }), + }); + const narrowedSession = Object.create(session) as typeof session; + Object.defineProperty(narrowedSession, "items", { value: items }); + const narrowed = Object.create(ctx) as BlockContext; + Object.defineProperty(narrowed, "session", { value: narrowedSession }); + return narrowed; } type MaybePromise = TValue | Promise; @@ -2754,6 +2810,7 @@ export function generator< const staticContextEntries = mergedSurface?.contextEntries ?? []; const staticToolEntries = mergedSurface?.toolEntries ?? []; const staticControlToolEntries = mergedSurface?.controlToolEntries ?? []; + const staticHistoryEntries = mergedSurface?.historyEntries ?? []; const hasStaticContext = staticContextEntries.length > 0; const hasStaticTools = staticToolEntries.length > 0; const hasStaticControlTools = staticControlToolEntries.length > 0; @@ -2991,7 +3048,15 @@ export function generator< } const historySlot = normalizeHistorySlot(normalizedConfig.history); - const historyValues = await resolveSlotValues(historySlot, input, ctx); + // A capability's `history` key narrows every read the slot makes (FIX-1613). + const capabilityHistoryQuery = historySlot === undefined + ? undefined + : await resolveCapabilityHistoryQuery(staticHistoryEntries, dynamicUses, blockItemVisibility, ctx); + const historyValues = await resolveSlotValues( + historySlot, + input, + capabilityHistoryQuery === undefined ? ctx : withHistoryQuery(ctx, capabilityHistoryQuery), + ); const userBrand = getPromptFileBrand(normalizedConfig.user); const { diff --git a/packages/core/src/capability/merge.ts b/packages/core/src/capability/merge.ts index b989825c23..792a06c3d2 100644 --- a/packages/core/src/capability/merge.ts +++ b/packages/core/src/capability/merge.ts @@ -276,6 +276,8 @@ export type MergedCapabilitySurface = { toolEntries: Array GeneratorTool[] | Promise)>; /** Fence-exempt control tools (FIX-1393) — see `PresetDef.controlTools`. */ controlToolEntries: Array GeneratorTool[] | Promise)>; + /** History query entries (FIX-1613) — see `PresetDef.history`. In merge order. */ + historyEntries: Array>; // Generator-only singletons. Last-wins among capabilities; block-level // setting wins over capability (handled in the generator block factory). // eslint-disable-next-line @typescript-eslint/no-explicit-any @@ -299,6 +301,7 @@ export function createEmptyMergedSurface(): MergedCapabilitySurface { contextEntries: [], toolEntries: [], controlToolEntries: [], + historyEntries: [], model: undefined, providerOptions: undefined, caching: undefined, @@ -585,6 +588,17 @@ export function mergeSurfaceInto( acc.controlToolEntries.push(surface.controlTools); } + // History query — generator only, like context (FIX-1613). + if (surface.history !== undefined) { + if (blockKind !== "generator") { + throw new Error( + `Capability "${capName}" ${source} declares history, ` + + `but the consuming block is a ${blockKind}. history is only valid on generator blocks.` + ); + } + acc.historyEntries.push(surface.history); + } + // Generator singletons — generator only. Last-wins among capabilities; // the generator block factory then prefers a block-level setting. if (surface.model !== undefined) { diff --git a/packages/core/src/capability/types.ts b/packages/core/src/capability/types.ts index 45249d6832..319c418538 100644 --- a/packages/core/src/capability/types.ts +++ b/packages/core/src/capability/types.ts @@ -23,6 +23,7 @@ import type { ResolvableProviderOptions, } from "../blocks/generator"; import type { ItemVisibility } from "../items/types"; +import type { ItemQuery } from "../types/scope"; type MaybePromise = T | Promise; @@ -122,6 +123,17 @@ export type PresetDef = { | GeneratorTool[] | ((ctx: CapabilityPresetCtx) => GeneratorTool[] | Promise); + /** + * A query added to every `ctx.session.items.history()` read of the generator + * that installs the capability (FIX-1613), whether through the `history` + * option's default or a history function of its own. The read's own keys win + * over it; among capabilities, later keys win. Generator only. + * + * A history summary uses it to read only the turns after its mark + * (`{ afterRequestId }`). A function is resolved on every run. + */ + history?: ItemQuery | ((ctx: BlockContext) => MaybePromise); + // Generator-only singletons. Block-kind validated at merge time — declaring // any of these on a capability used by a handler/sequencer/router throws a // clear error. Among capabilities, last-wins; among capability + block, the diff --git a/packages/core/src/utility/history-summary.ts b/packages/core/src/utility/history-summary.ts new file mode 100644 index 0000000000..eb0af9f6b7 --- /dev/null +++ b/packages/core/src/utility/history-summary.ts @@ -0,0 +1,254 @@ +/** + * History summary (FIX-1613): a long conversation keeps what it said before + * its history window. + * + * `historySummary({ summarize })` returns two halves, the way memory's + * `system()` does: + * + * - `capability`, installed on the generator that answers (`uses`). It holds + * the running summary in a session resource, gives it to the model as one + * context section, and starts that generator's history reads after the + * summary's mark, so no turn is read twice. + * - `fold`, a step the flow runs before that generator (`.tap(fold)`). Once the + * oldest unfolded turn reaches the oldest quarter of the window, it folds up + * to a quarter of the window into the summary with the author's `summarize` + * block, before anything leaves. A turn that has not settled (running, + * suspended, parked) is kept by id and folded once it settles. + * + * The engine knows nothing about summaries: it opens the window + * (`ctx.session.window`), the turn reads (`ctx.session.items.turns()`) and + * `history({ afterRequestId })`, and records `historyStart` on each request. + */ +import { z } from "zod"; +import { defineCapability } from "../capability"; +import { handler } from "../blocks/handler"; +import { sequencer } from "../blocks/sequencer"; +import { defineResource } from "../types/resource"; +import type { BlockContext, BlockDefinition } from "../types/block"; +import type { HistoryTurn, LLMMessage } from "../types/scope"; + +/** What `summarize` is handed on each fold. */ +export type HistorySummaryInput = { + /** The running summary so far; null on the first fold. */ + summary: string | null; + /** The turns being folded, oldest first, as the model would have read them. */ + turns: LLMMessage[]; +}; + +/** The session resource a history summary keeps. */ +export const historySummaryStateSchema = z.object({ + /** The running summary. */ + summary: z.string().nullable().default(null), + /** The high-water mark: the newest turn folded, or moved past and kept pending. */ + throughRequestId: z.string().nullable().default(null), + throughStartedAtMs: z.number().nullable().default(null), + /** The oldest turn after the mark at the last fold. Gone unfolded later means turns were lost. */ + nextRequestId: z.string().nullable().default(null), + /** Turns behind the mark that had not settled, by request id; folded once they do. */ + pending: z.array(z.string()).default([]), + /** A turn left the window unsummarized. Stays set: the summary has a hole. */ + gap: z.boolean().default(false), + /** Every turn before the mark is in the summary: no gap and nothing pending. */ + complete: z.boolean().default(true), + /** Folds written. */ + folds: z.number().int().default(0), + /** Folds tried, written or failed. A turn out of view with none tried: the fold step is missing. */ + attempts: z.number().int().default(0), +}); + +export type HistorySummaryState = z.infer; + +const HISTORY_SUMMARY_DEFAULT: HistorySummaryState = historySummaryStateSchema.parse({}); + +/** What the fold's first step decided: the turns to fold and where the mark lands. */ +type FoldPlan = { + summary: string | null; + turns: LLMMessage[]; + /** The mark this plan read; another turn moving it first discards this plan. */ + expectedThroughStartedAtMs: number | null; + next: Pick< + HistorySummaryState, + "throughRequestId" | "throughStartedAtMs" | "nextRequestId" | "pending" | "gap" | "complete" + >; +}; + +export interface HistorySummaryOptions { + /** + * The block that writes the summary: handed the summary so far and the turns + * to fold, returning `{ summary }`. Core's `summarizer(...)` fits as is. + */ + summarize: BlockDefinition; + /** The resource's accessor name and storage key. Default `historySummary`. */ + name?: string; +} + +/** + * Build a history summary: a capability for the generator that answers and a + * fold step the flow runs before it. + * + * ```ts + * const earlier = historySummary({ + * summarize: summarizer({ name: "earlier-turns", granularity: "detailed" }), + * }); + * + * sequencer({ name: "chat", inputSchema }) + * .tap(earlier.fold) + * .step(generator({ name: "answer", history: true, uses: [earlier.capability], ... })); + * ``` + */ +export function historySummary(options: HistorySummaryOptions) { + const name = options.name ?? "historySummary"; + + // One per conversation, however many generators install the capability. + // Public, so a screen can label its divider "earlier turns summarized". + const resource = defineResource({ + ref: name, + scope: "session", + stateSchema: historySummaryStateSchema, + default: HISTORY_SUMMARY_DEFAULT, + writable: true, + client: { expose: ["throughRequestId", "complete", "folds"] }, + }); + const resources = { [name]: resource }; + const stateOf = (ctx: BlockContext): HistorySummaryState => + ({ ...HISTORY_SUMMARY_DEFAULT, ...((ctx.resources as any)[name]?.state ?? {}) }) as HistorySummaryState; + const update = (ctx: BlockContext, updater: (state: HistorySummaryState) => HistorySummaryState) => + (ctx.resources as any)[name].updateState((state: HistorySummaryState) => + updater({ ...HISTORY_SUMMARY_DEFAULT, ...state }) + ) as Promise; + + const capability = defineCapability({ + name, + resources, + presets: { + default: ["context", "history"], + context: { + context: (_input: unknown, ctx: any) => { + const state = stateOf(ctx as BlockContext); + const window = (ctx as BlockContext).session?.window; + if (window?.startRequestId !== undefined && state.attempts === 0) { + throw new Error( + `historySummary "${name}": turns have left the history window and no fold has run. ` + + `Run its fold step before this generator (\`.tap(${name}.fold)\`, or workforce's \`beforeAnswer\`).` + ); + } + return state.summary === null + ? null + : `\n${state.summary}\n`; + }, + }, + // The summary stands for every turn up to its mark. + history: { + history: (ctx: BlockContext) => { + const through = stateOf(ctx).throughRequestId; + return through === null ? {} : { afterRequestId: through }; + }, + }, + }, + }); + + const plan = handler({ + name: `${name}-plan`, + inputSchema: z.unknown(), + resources, + execute: async (_input, ctx): Promise => { + const window = ctx.session.window; + if (window === undefined) return null; + const state = stateOf(ctx as BlockContext); + const quarter = Math.max(1, Math.floor(window.turns / 4)); + + // Turns that left open earlier: fold the ones that have settled since. + const pendingTurns = state.pending.length > 0 + ? await ctx.session.items.turns({ requestIds: state.pending }) + : []; + const settledPending = pendingTurns.filter((t) => t.settled); + const stillPending = pendingTurns.filter((t) => !t.settled).map((t) => t.requestId); + + const all = await ctx.session.items.turns(); + // After the mark by position while the window holds it (two turns can + // share a start millisecond), by start time once it has left. + const markAt = state.throughRequestId === null ? -1 : all.findIndex((t) => t.requestId === state.throughRequestId); + const after = markAt !== -1 + ? all.slice(markAt + 1) + : all.filter((t) => state.throughStartedAtMs === null || t.startedAtMs > state.throughStartedAtMs); + + // Turns lost: the oldest unfolded turn the last fold saw left unfolded, + // or the summary started after turns had already left the window. + const lost = + (state.nextRequestId !== null && !all.some((t) => t.requestId === state.nextRequestId)) || + (state.attempts === 0 && window.startRequestId !== undefined); + + const due = after.length > window.turns - quarter; + const batch: HistoryTurn[] = due ? after.slice(0, quarter) : []; + if (batch.length === 0 && settledPending.length === 0) return null; + + const folded = [...settledPending, ...batch.filter((t) => t.settled)]; + const pending = [...stillPending, ...batch.filter((t) => !t.settled).map((t) => t.requestId)]; + const last = batch.at(-1); + const gap = state.gap || lost; + return { + summary: state.summary, + turns: folded.flatMap((t) => t.messages), + expectedThroughStartedAtMs: state.throughStartedAtMs, + next: { + throughRequestId: last?.requestId ?? state.throughRequestId, + throughStartedAtMs: last?.startedAtMs ?? state.throughStartedAtMs, + nextRequestId: last === undefined ? state.nextRequestId : (after[batch.length]?.requestId ?? null), + pending, + gap, + complete: !gap && pending.length === 0, + }, + }; + }, + }); + + const write = handler({ + name: `${name}-write`, + inputSchema: z.object({ summary: z.string() }).passthrough(), + resources, + execute: async (output, ctx) => { + const decided = ctx.getBlockOutput(plan) as FoldPlan | null | undefined; + if (decided == null) return; + await update(ctx as BlockContext, (state) => + // Another turn of this conversation folded first: keep its write. + state.throughStartedAtMs !== decided.expectedThroughStartedAtMs + ? state + : { + ...state, + ...decided.next, + summary: output.summary, + folds: state.folds + 1, + attempts: state.attempts + 1, + } + ); + }, + }); + + const failed = handler({ + name: `${name}-failed`, + inputSchema: z.unknown(), + resources, + execute: async (error, ctx) => { + // The turn goes on with the summary it had; the next turn tries again, + // and the fold started early enough that nothing leaves meanwhile. + console.warn( + `[historySummary] "${name}" fold failed; the next turn retries:`, + error instanceof Error ? error.message : error + ); + await update(ctx as BlockContext, (state) => ({ ...state, attempts: state.attempts + 1 })); + }, + }); + + const fold = sequencer({ name: `${name}-fold`, inputSchema: z.unknown() }) + .step(plan) + .stepIf( + (planned: FoldPlan | null) => planned !== null, + (planned: FoldPlan | null) => ({ summary: planned!.summary, turns: planned!.turns }) satisfies HistorySummaryInput, + options.summarize + ) + // Only after a summary ran: a skipped step passes the plan (or null) on. + .stepIf((value: unknown) => value != null && !("next" in (value as object)), write) + .rescue([{ block: failed }]); + + return { capability, fold, resource }; +} diff --git a/packages/core/src/utility/index.ts b/packages/core/src/utility/index.ts index c04e57cc83..66190b0d46 100644 --- a/packages/core/src/utility/index.ts +++ b/packages/core/src/utility/index.ts @@ -40,6 +40,17 @@ export type { SummarizerGranularity } from "./summarizer"; +export { + historySummary, + historySummaryStateSchema +} from "./history-summary"; + +export type { + HistorySummaryInput, + HistorySummaryOptions, + HistorySummaryState +} from "./history-summary"; + export { decomposer, decomposerOutputSchema, diff --git a/packages/core/test/capability-history.test.ts b/packages/core/test/capability-history.test.ts new file mode 100644 index 0000000000..b2b6ea3e32 --- /dev/null +++ b/packages/core/test/capability-history.test.ts @@ -0,0 +1,123 @@ +/** + * A capability's `history` preset key (FIX-1613): a query a capability adds to + * every `ctx.session.items.history()` read of the generator that installs it. + * + * The case it exists for is a history summary: the summary stands for the turns + * up to its mark, so the generator must read only the turns after it, however + * that generator reads history (the `history: true` default, or a function slot + * such as Workforce's `routedTaskHistory`). + */ +import { describe, expect, it } from "vitest"; +import { z } from "zod"; +import { defineCapability } from "../src/capability"; +import { generator } from "../src/blocks/generator"; +import { handler } from "../src/blocks/handler"; +import type { BlockContext } from "../src"; +import type { ItemQuery } from "../src/types"; +import { createMockContext, runForTest } from "./helpers"; + +function contextRecording(queries: (ItemQuery | undefined)[]) { + return createMockContext({ + resolveModel: () => + ({ + modelId: "mock", + async generate() { + return { text: "ok" }; + } + }) as any, + session: { + items: { + history: async (query?: ItemQuery) => { + queries.push(query); + return []; + } + } + } as unknown as BlockContext["session"] + }); +} + +const afterTurnThree = defineCapability({ + name: "afterTurnThree", + presets: { + default: ["history"], + history: { history: { afterRequestId: "req_3" } } + } +}); + +describe("capability history preset key", () => { + it("narrows the generator's default history read", async () => { + const queries: (ItemQuery | undefined)[] = []; + const block = generator({ name: "answer", model: "mock", prompt: "p", history: true, uses: [afterTurnThree] }); + + await runForTest(block, "hi", contextRecording(queries)); + + expect(queries).toEqual([{ afterRequestId: "req_3" }]); + }); + + it("reaches a history function slot's own read, with the slot's keys on top", async () => { + const queries: (ItemQuery | undefined)[] = []; + const block = generator({ + name: "answer", + model: "mock", + prompt: "p", + history: (_input, ctx) => ctx.session.items.history({ limit: { turns: 2 } }), + uses: [afterTurnThree] + }); + + await runForTest(block, "hi", contextRecording(queries)); + + expect(queries).toEqual([{ afterRequestId: "req_3", limit: { turns: 2 } }]); + }); + + it("lets the block's explicit key win over the capability's", async () => { + const queries: (ItemQuery | undefined)[] = []; + const block = generator({ + name: "answer", + model: "mock", + prompt: "p", + history: (_input, ctx) => ctx.session.items.history({ afterRequestId: "req_1" }), + uses: [afterTurnThree] + }); + + await runForTest(block, "hi", contextRecording(queries)); + + expect(queries).toEqual([{ afterRequestId: "req_1" }]); + }); + + it("resolves a function of the context at run time", async () => { + const queries: (ItemQuery | undefined)[] = []; + const fromRequest = defineCapability({ + name: "fromRequest", + presets: { + default: ["history"], + history: { history: (ctx: BlockContext) => ({ afterRequestId: `after_${ctx.request.identity.id}` }) } + } + }); + const block = generator({ name: "answer", model: "mock", prompt: "p", history: true, uses: [fromRequest] }); + + await runForTest(block, "hi", contextRecording(queries)); + + expect(queries).toEqual([{ afterRequestId: "after_req_1" }]); + }); + + it("is off when the preset is switched off", async () => { + const queries: (ItemQuery | undefined)[] = []; + const block = generator({ + name: "answer", + model: "mock", + prompt: "p", + history: true, + uses: [afterTurnThree.presets({ history: false })] + }); + + await runForTest(block, "hi", contextRecording(queries)); + + expect(queries).toEqual([undefined]); + }); + + it("is refused on a block that is not a generator", () => { + expect(() => + handler({ name: "h", inputSchema: z.any(), uses: [afterTurnThree], execute: () => "ok" }) + ).toThrow(/declares history, but the consuming block is a handler/); + }); +}); diff --git a/packages/engine/test/history-summary.test.ts b/packages/engine/test/history-summary.test.ts new file mode 100644 index 0000000000..9229755fdd --- /dev/null +++ b/packages/engine/test/history-summary.test.ts @@ -0,0 +1,184 @@ +/** + * Core's `historySummary` running on the engine (FIX-1613): a conversation past + * its history window still reaches the turns that left it, through a running + * summary the fold step writes before the answer and the capability hands the + * answering generator. + * + * The summarize block here is a handler that folds deterministically, so each + * assertion names exactly which turns are in the summary and which the model + * reads word for word. The real-model proof is the goal check. + */ +import { DEFAULT_ORG_ID, defineFlow, generator, handler, sequencer, utility } from "@flow-state-dev/core"; +import type { GeneratorModel, LLMMessage } from "@flow-state-dev/core/types"; +import { describe, expect, it } from "vitest"; +import { z } from "zod"; +import { createInMemoryStores, runAction } from "../src"; +import type { StoreRegistry } from "../src/stores/types"; + +type ModelCall = { messages: LLMMessage[] }; + +function recordingResolver(calls: ModelCall[]) { + const resolver = ((modelId: string) => + ({ + modelId, + async generate(options: { messages: LLMMessage[] }) { + calls.push({ messages: options.messages }); + return { text: `answer ${calls.length}` }; + } + }) as unknown as GeneratorModel) as ((modelId: string) => GeneratorModel) & { resolveId: (id: string) => string }; + resolver.resolveId = (id) => id; + return resolver; +} + +function textOf(content: unknown): string { + if (typeof content === "string") return content; + if (Array.isArray(content)) return content.map((c: { text?: string }) => c.text ?? "").join(""); + return JSON.stringify(content); +} + +/** Folds each turn's user words into the summary: "u1 u2 …". */ +function foldingSummarize(options: { failTimes?: number } = {}) { + let failuresLeft = options.failTimes ?? 0; + return handler({ + name: "earlier-turns", + inputSchema: z.object({ summary: z.string().nullable(), turns: z.array(z.any()) }), + outputSchema: z.object({ summary: z.string() }), + execute: ({ summary, turns }) => { + if (failuresLeft > 0) { + failuresLeft -= 1; + throw new Error("summary model unavailable"); + } + const said = (turns as LLMMessage[]).filter((m) => m.role === "user").map((m) => textOf(m.content)); + return { summary: [summary, ...said].filter((part) => part !== null && part !== "").join(" ") }; + } + }); +} + +function chatFlow(options: { window: number; summarize?: ReturnType; withFold?: boolean }) { + const earlier = options.summarize ? utility.historySummary({ summarize: options.summarize }) : undefined; + const answer = generator({ + name: "answer", + model: "mock", + prompt: "You answer.", + history: true, + ...(earlier ? { uses: [earlier.capability] } : {}) + }); + const base = sequencer({ name: "chat", inputSchema: z.string() }); + const block = earlier && options.withFold !== false ? base.tap(earlier.fold).step(answer) : base.step(answer); + return defineFlow({ + kind: "summary-chat", + session: { historyWindow: { turns: options.window } }, + actions: { run: { inputSchema: z.string(), block, userMessage: (input: string) => input } } + })(); +} + +async function talk(stores: StoreRegistry, flow: ReturnType, calls: ModelCall[], turns: number, from = 1) { + const results = []; + for (let n = from; n < from + turns; n++) { + results.push( + await runAction({ + orgId: DEFAULT_ORG_ID, + flow, + actionName: "run", + input: `u${n}`, + requestId: `req_${String(n).padStart(3, "0")}`, + userId: "u", + sessionId: "s", + stores, + runtimeConfig: { modelResolver: recordingResolver(calls) } + }) + ); + // Distinct start times, so the window's order is the order spoken. + await new Promise((resolve) => setTimeout(resolve, 2)); + } + return results; +} + +function lastInput(calls: ModelCall[]) { + const messages = calls.at(-1)!.messages; + const system = messages.filter((m) => m.role === "system").map((m) => textOf(m.content)).join("\n"); + const users = messages.filter((m) => m.role === "user").map((m) => textOf(m.content)); + return { system, users }; +} + +describe("historySummary on the engine", () => { + it("keeps turns that left the window in a summary the model reads, and reads only the turns after it", async () => { + const stores = createInMemoryStores(); + const calls: ModelCall[] = []; + await talk(stores, chatFlow({ window: 4, summarize: foldingSummarize() }), calls, 7); + + // Turn 7: the window holds turns 3–6. A turn is folded the turn before it + // would leave, so turns 1–3 are in the summary and only 4–6 are read word + // for word. + const { system, users } = lastInput(calls); + expect(system).toContain("\nu1 u2 u3\n"); + expect(users).toEqual(["u4", "u5", "u6", "u7"]); + }); + + it("changes nothing for a flow without it", async () => { + const stores = createInMemoryStores(); + const calls: ModelCall[] = []; + await talk(stores, chatFlow({ window: 4 }), calls, 7); + + const { system, users } = lastInput(calls); + expect(system).not.toContain("earlier-conversation"); + expect(users).toEqual(["u3", "u4", "u5", "u6", "u7"]); + }); + + it("goes on through a failed summary and folds the turn on the next one, before it leaves", async () => { + const stores = createInMemoryStores(); + const calls: ModelCall[] = []; + const results = await talk(stores, chatFlow({ window: 8, summarize: foldingSummarize({ failTimes: 1 }) }), calls, 10); + + // An 8-turn window folds two turns at a time, starting while the oldest + // has two turns left. Turn 8's fold failed and the turn still answered; + // turn 9 folded turns 1–2 before turn 1 left, turn 10 folded 3–4. + expect(results.map((r) => r.error)).toEqual(Array(10).fill(undefined)); + const { system, users } = lastInput(calls); + expect(system).toContain("\nu1 u2 u3 u4\n"); + expect(users).toEqual(["u5", "u6", "u7", "u8", "u9", "u10"]); + }); + + it("keeps a turn that had not settled by id and folds it once it does, never twice", async () => { + const stores = createInMemoryStores(); + const calls: ModelCall[] = []; + const flow = chatFlow({ window: 4, summarize: foldingSummarize() }); + await talk(stores, flow, calls, 3); + + // A turn waiting on an approval, started after turn 3. + const third = (await stores.request.get("req_003"))!; + const waiting = { ...third, id: "req_wait", status: "suspended" as const, startedAtMs: third.startedAtMs + 1, items: [] }; + await stores.request.set("req_wait", waiting, "any"); + await new Promise((resolve) => setTimeout(resolve, 2)); + + await talk(stores, flow, calls, 5, 4); + // An open turn counts toward the window's fill, so folding starts a turn + // sooner. Turn 7 reached the waiting turn and moved past it, keeping it by + // id; turn 8 folded turn 4 after it. + expect(lastInput(calls).system).toContain("\nu1 u2 u3 u4\n"); + + // It settles; the next turn folds it before folding turn 4. + const userItem = (third.items ?? []).find((i) => i.type === "message" && (i as { role?: string }).role === "user")!; + await stores.request.set( + "req_wait", + { + ...waiting, + status: "completed", + items: [{ ...userItem, id: "wait_msg", requestId: "req_wait", content: [{ type: "output_text", text: "ux" }] } as never] + }, + "any" + ); + await talk(stores, flow, calls, 1, 9); + + expect(lastInput(calls).system).toContain("\nu1 u2 u3 u4 ux u5\n"); + }); + + it("refuses to run quietly without its fold step once a turn has left the window", async () => { + const stores = createInMemoryStores(); + const calls: ModelCall[] = []; + const results = await talk(stores, chatFlow({ window: 4, summarize: foldingSummarize(), withFold: false }), calls, 6); + + expect(results.slice(0, 5).map((r) => r.error)).toEqual(Array(5).fill(undefined)); + expect(results[5]!.error?.message).toMatch(/no fold has run/); + }); +}); From f8afedbb0e9365dd5cea816b87f39b4cd78c8919 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 18:50:28 +0000 Subject: [PATCH 03/58] feat(workforce,client): beforeAnswer step and historyStart on the client type (FIX-1613) The agent worker flow runs an app's beforeAnswer block before the worker answers, where a history summary's fold goes. The client's request summary carries historyStart, and a route test proves it reaches a screen. The history preset key joins the dynamic keys a worker may pick. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01NczDiEHd9ZKT1vum6nfnPs --- packages/client/src/types/index.ts | 9 +++ packages/engine/test/history-start.test.ts | 26 ++++++- packages/workforce/src/agent-worker-flow.ts | 21 +++++- packages/workforce/src/worker-capabilities.ts | 5 +- .../test/agent-before-answer.test.ts | 69 +++++++++++++++++++ 5 files changed, 126 insertions(+), 4 deletions(-) create mode 100644 packages/workforce/test/agent-before-answer.test.ts diff --git a/packages/client/src/types/index.ts b/packages/client/src/types/index.ts index 5d4c9ef6ec..cc756c0e5f 100644 --- a/packages/client/src/types/index.ts +++ b/packages/client/src/types/index.ts @@ -258,6 +258,15 @@ export type SessionRequestSummary = { source?: string; status: RequestStatus; startedAtMs?: number; + /** + * Where the turns this request read begin: the first past turn its history + * window held, when earlier turns had fallen out of it. Draw a divider + * before that request; the turns above it are out of the model's view (or, + * on a flow with a history summary, in the summary). Absent when every + * earlier turn was in the window, and on servers that predate the field. + * Guard with `== null` (BP-030). + */ + historyStart?: { requestId: string }; completedAtMs?: number; failedAtMs?: number; metadata?: Record; diff --git a/packages/engine/test/history-start.test.ts b/packages/engine/test/history-start.test.ts index 45517ab2a0..4e83ad17ea 100644 --- a/packages/engine/test/history-start.test.ts +++ b/packages/engine/test/history-start.test.ts @@ -13,7 +13,7 @@ import type { MessageItem, OutputItem } from "@flow-state-dev/core/items"; import { DEFAULT_ORG_ID, defineFlow, handler } from "@flow-state-dev/core"; import { describe, expect, it } from "vitest"; import { z } from "zod"; -import { createExecutionContext, createInMemoryStores } from "../src"; +import { createExecutionContext, createFlowApiRouter, createFlowRegistry, createInMemoryStores } from "../src"; import type { RequestRecord, StoreRegistry } from "../src/stores/types"; const noopHandler = handler({ name: "noop", execute: () => "ok" }); @@ -102,6 +102,30 @@ describe("historyStart: where the turns a request read begin", () => { expect(record?.historyStart).toEqual({ requestId: "req_3" }); }); + it("reaches a screen through the session's request list", async () => { + const stores = createInMemoryStores(); + await seedTurns(stores, "sess_list", 5); + const flow = makeFlow(3); + await createExecutionContext({ + orgId: DEFAULT_ORG_ID, + flow, + actionName: "run", + requestId: "req_cur", + sessionId: "sess_list", + userId: "u1", + stores + }); + const registry = createFlowRegistry(); + registry.register(flow); + const router = createFlowApiRouter({ registry, stores }); + + const path = ["sessions", "sess_list", "requests"]; + const response = await router.GET(new Request(`http://localhost/api/flows/${path.join("/")}`), { params: { path } }); + + const { requests } = (await response.json()) as { requests: { id: string; historyStart?: unknown }[] }; + expect(requests.find((r) => r.id === "req_cur")?.historyStart).toEqual({ requestId: "req_3" }); + }); + it("records nothing while every earlier turn is still in the window", async () => { const stores = createInMemoryStores(); await seedTurns(stores, "sess_in", 3); diff --git a/packages/workforce/src/agent-worker-flow.ts b/packages/workforce/src/agent-worker-flow.ts index aaa33bd9b0..1672adcb0d 100644 --- a/packages/workforce/src/agent-worker-flow.ts +++ b/packages/workforce/src/agent-worker-flow.ts @@ -354,6 +354,20 @@ export interface AgentWorkerFlowOptions { * Omitted, the flow's sequence is exactly what it is today. */ afterAnswer?: BlockDefinition; + /** + * A block run on every turn just before the worker answers, the mirror of + * {@link afterAnswer}. It runs as a `.tap`: it sees the turn's input and + * cannot change it, and its output is dropped. Unlike `afterAnswer`, a + * failure in it fails the turn, so a block that must not (a history + * summary's fold, say) rescues its own. + * + * A history summary's fold goes here (`beforeAnswer: earlier.fold`, with + * `earlier.capability` in {@link uses}), so the answer reads a summary that + * already holds the turns about to leave the window. + * + * Omitted, the flow's sequence is exactly what it is today. + */ + beforeAnswer?: BlockDefinition; /** * Answer again, in the same request, with the tasks that finished while the * worker answered (FIX-2159). After the worker answers, this block runs; when @@ -1240,10 +1254,13 @@ export function agentWorkerTurn(given: AgentWorkerFlowOptions = {}, share: Agent } }); - const answered = sequencer({ name: "agent-run", inputSchema, flowConfigSchema: settings }) + const prepared = sequencer({ name: "agent-run", inputSchema, flowConfigSchema: settings }) .tapIf((_input, ctx) => turnConfig(ctx).skills.enableLlmClassifier !== true, matcherWithoutClassifier) .tapIf((_input, ctx) => turnConfig(ctx).skills.enableLlmClassifier === true, matcherWithClassifier) - .tap(appendWorkerDefaults) + .tap(appendWorkerDefaults); + // Appended only when the app passed one, like afterAnswer below, so a call + // without it builds the sequence it built before the option existed. + const answered = (options.beforeAnswer ? prepared.tap(options.beforeAnswer) : prepared) // Two arms rather than two `.stepIf`s: the answer is the sequencer's OUTPUT, // and a second conditional step would have to be typed against the first // one's result. A branch says what this is — one answer, built two ways — diff --git a/packages/workforce/src/worker-capabilities.ts b/packages/workforce/src/worker-capabilities.ts index c763d4cfaf..9ae361ae34 100644 --- a/packages/workforce/src/worker-capabilities.ts +++ b/packages/workforce/src/worker-capabilities.ts @@ -118,8 +118,11 @@ const BUILD_TIME_ONLY_KEYS = [ * the behaviour — *"carries a selected preset's context but not its tool past * the worker's fence"* and *"lets a selected preset's CONTROL tool through the * same empty tools list"*, one key apart on the same worker. + * + * `history` (FIX-1613) is dynamic for the same reason: core collects a + * dynamic entry's `history` query with its context. */ -const DYNAMIC_KEYS = ["context", "tools", "controlTools"] as const satisfies readonly (keyof PresetDef)[]; +const DYNAMIC_KEYS = ["context", "tools", "controlTools", "history"] as const satisfies readonly (keyof PresetDef)[]; /** * Compile-time proof that every `PresetDef` key is classified as one or the diff --git a/packages/workforce/test/agent-before-answer.test.ts b/packages/workforce/test/agent-before-answer.test.ts new file mode 100644 index 0000000000..afe8cf10e4 --- /dev/null +++ b/packages/workforce/test/agent-before-answer.test.ts @@ -0,0 +1,69 @@ +/** + * The agent worker flow's pre-answer step (FIX-1613): `beforeAnswer` runs a + * block on every turn before the worker answers, the mirror of `afterAnswer`. + * A history summary's fold goes here, so the answer reads a summary that + * already holds the turns about to leave the window. + */ +import { describe, expect, it } from "vitest"; +import { z } from "zod"; +import { handler } from "@flow-state-dev/core"; +import type { FlowInstance } from "@flow-state-dev/core/types"; +import { executeBlock } from "@flow-state-dev/engine"; +import { createTestContext, mockGenerator } from "@flow-state-dev/testing"; +import { AGENT_FLOW, defineAgentWorkerFlow } from "../src/agent-worker-flow"; +import { mintWorkers } from "../src/hire"; +import type { WorkerManifest } from "../src/manifest"; + +function lead(flow: ReturnType): FlowInstance { + const manifest: WorkerManifest = { id: "engineering.lead", declared: {}, body: "Lead." }; + return mintWorkers([manifest], { workerFlows: { [AGENT_FLOW]: flow } })[0]!; +} + +async function runTurn(worker: FlowInstance, message: string) { + const answer = mockGenerator({ name: "agent-answer", script: [{ text: "answered" }] }); + const runtime = await createTestContext({ + flow: { ...worker, cardinality: "singleton" }, + orgId: "test-org", + org: { state: {} }, + sessionId: "test-session", + sequencerName: worker.actions.respond!.block.name, + declaredResources: worker.actions.respond!.block.declaredResources, + generators: { "agent-answer": answer } + }); + const result = await executeBlock({ block: worker.actions.respond.block, input: { message }, ctx: runtime.ctx }); + return { result, answer }; +} + +type Named = { name: string; childBlocks?: readonly Named[] }; +const names = (block: Named): string[] => [block.name, ...(block.childBlocks ?? []).flatMap(names)]; + +describe("defineAgentWorkerFlow beforeAnswer", () => { + it("runs the block before the worker answers, and the answer still comes", async () => { + const seen: { answeredYet: boolean }[] = []; + const before = handler({ + name: "before-the-answer", + inputSchema: z.any(), + execute: (_input, ctx) => { + seen.push({ + answeredYet: ctx.response.getItems().some((item) => item.type === "message" && item.role === "assistant") + }); + return "this must not become the worker's input"; + } + }); + + const { result, answer } = await runTurn(lead(defineAgentWorkerFlow({ beforeAnswer: before })), "hello"); + + expect(result.error).toBeUndefined(); + expect(seen).toEqual([{ answeredYet: false }]); + expect(answer.calls).toHaveLength(1); + }); + + it("is a step of the turn only when the app passes one", () => { + const before = handler({ name: "before-the-answer", inputSchema: z.any(), execute: () => null }); + + expect(names(lead(defineAgentWorkerFlow({ beforeAnswer: before })).actions.respond!.block as Named)).toContain( + "before-the-answer" + ); + expect(names(lead(defineAgentWorkerFlow({})).actions.respond!.block as Named)).not.toContain("before-the-answer"); + }); +}); From 966b1d9dc8757d6e28635bdf6cb98ce21bbc014a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 28 Oct 2026 17:36:03 +0000 Subject: [PATCH 04/58] FIX-2154: wire the Teammates lab to the real packages The lab now runs on a real model and a durable SQLite store through `fsdev dev --app`: lead, researcher and writer on the built-in agent flow with memory composed in, coder on the lab's one coding flow (one harnessManager per harness over projectWorkspace(), routed by the worker's `harness:`), and the user's projects created at start. The adapter calls the workforce client, session items and streams, the message log, and setWorkProject; the fixtures are gone (kept only as a test double). Adds the goal check goals/teammates-lab/a-worker-talks-to-another-while-you-talk (steps 1-3 and 5 in a browser; step 4 waits on FIX-1613), and lets launchChromium find a pre-installed chrome-linux64 build. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01NczDiFEfpmT3smuFRj8ti2 --- goals/lib/playwright.mts | 7 +- .../fixtures/input.json | 20 + .../goal.md | 25 + .../run.mts | 479 ++++++++++++++++++ labs/teammates/.gitignore | 1 + labs/teammates/README.md | 81 +-- labs/teammates/fsdev.config.mts | 28 + labs/teammates/host.mts | 162 ++++++ labs/teammates/package.json | 19 +- labs/teammates/src/App.tsx | 3 +- labs/teammates/src/adapter.ts | 369 +++++++++++++- .../teammates/src/components/Conversation.tsx | 8 +- labs/teammates/src/components/Entry.tsx | 4 +- labs/teammates/src/components/Runs.tsx | 2 +- labs/teammates/src/components/TaskCard.tsx | 6 +- labs/teammates/src/components/WorkersList.tsx | 6 +- labs/teammates/src/flows/coder.ts | 148 ++++++ labs/teammates/src/lib/coder-flow.ts | 6 + labs/teammates/src/lib/session-feed.ts | 92 ++++ labs/teammates/src/lib/talk.ts | 2 +- .../{src/fixtures.ts => test/fake-lab.ts} | 20 +- labs/teammates/test/screen.test.tsx | 12 +- labs/teammates/tsconfig.json | 2 +- .../teams/teammates/workers/coder/WORKER.md | 1 + .../teams/teammates/workers/lead/WORKER.md | 10 +- .../teammates/workers/researcher/WORKER.md | 5 + pnpm-lock.yaml | 43 ++ 27 files changed, 1464 insertions(+), 97 deletions(-) create mode 100644 goals/teammates-lab/a-worker-talks-to-another-while-you-talk/fixtures/input.json create mode 100644 goals/teammates-lab/a-worker-talks-to-another-while-you-talk/goal.md create mode 100644 goals/teammates-lab/a-worker-talks-to-another-while-you-talk/run.mts create mode 100644 labs/teammates/fsdev.config.mts create mode 100644 labs/teammates/host.mts create mode 100644 labs/teammates/src/flows/coder.ts create mode 100644 labs/teammates/src/lib/coder-flow.ts create mode 100644 labs/teammates/src/lib/session-feed.ts rename labs/teammates/{src/fixtures.ts => test/fake-lab.ts} (95%) diff --git a/goals/lib/playwright.mts b/goals/lib/playwright.mts index dd96300282..5a1c4c12cc 100644 --- a/goals/lib/playwright.mts +++ b/goals/lib/playwright.mts @@ -32,8 +32,11 @@ export function preinstalledChromium(): string | undefined { if (pool === undefined || !existsSync(pool)) return undefined; for (const entry of readdirSync(pool)) { if (!entry.startsWith("chromium-")) continue; - const binary = join(pool, entry, "chrome-linux", "chrome"); - if (existsSync(binary)) return binary; + // Older builds unpack to `chrome-linux`, newer ones to `chrome-linux64`. + for (const folder of ["chrome-linux", "chrome-linux64"]) { + const binary = join(pool, entry, folder, "chrome"); + if (existsSync(binary)) return binary; + } } return undefined; } diff --git a/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/fixtures/input.json b/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/fixtures/input.json new file mode 100644 index 0000000000..fa652001e3 --- /dev/null +++ b/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/fixtures/input.json @@ -0,0 +1,20 @@ +{ + "port": 4620, + "lead": "teammates.lead", + "researcher": "teammates.researcher", + "coder": "teammates.coder", + "ask": "Ask researcher for our launch date, and help me outline the post.", + "second": "Make section 2 about pricing.", + "fix": "Have coder fix the typo in the README's first line.", + "project": { "id": "relay", "title": "Relay" }, + "typos": [ + { "readme": "# Relay — a tiny relay servce", "wrong": "servce", "right": "service" }, + { "readme": "# Relay — passes mesages along", "wrong": "mesages", "right": "messages" }, + { "readme": "# Relay — a small mesage relay", "wrong": "mesage", "right": "message" } + ], + "rest": "\nIt relays messages between services.\n", + "answerWithinMs": 180000, + "replyWithinMs": 240000, + "unpickedMs": 30000, + "runWithinMs": 900000 +} diff --git a/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/goal.md b/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/goal.md new file mode 100644 index 0000000000..f3ba20a5b7 --- /dev/null +++ b/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/goal.md @@ -0,0 +1,25 @@ +# teammates-lab › it a worker talks to another while you talk + +**Issue:** FIX-2154 (leg b of the FIX-2152 epic's goal) +**Outcome:** In the Teammates lab, a list-of-workers app on the Grok Bot pattern, you talk to lead, lead messages researcher, and researcher's reply reaches lead while you are still talking to it; lead uses it. A coding job lead hands coder runs through Claude Code in the project you picked for lead, and only after you picked it. +**Input:** held out. The launch date researcher knows is drawn at random each run and written into a copy of the workers' tree, so lead can only state it by hearing it from researcher. The README's typo is one of several (`fixtures/input.json`). The lines you send are in the fixture. +**Signal:** +- **1:** lead answers your first line in its conversation. +- **2:** a card *To researcher* in lead's conversation, a line *From lead* in researcher's, the exchange under *with researcher* in lead's Talk panel, and a delivered row lead → researcher in the message log. +- **3:** your second line goes in before researcher's reply has landed. The reply shows in lead's conversation under researcher's name, after lead's answer to you, carrying the date; the log holds it as a delivered reply; a line of lead's after it states the date. +- **4:** not run. It needs the history window's mark (G1, FIX-1613); the step waits on it. +- **5:** lead has no project. You ask for the fix; the task card asks for a project. For 30 s with no pick, no run starts and the checkout is unchanged. You pick `relay` on the card; your pick is said to lead as your line and lead files the task again. That run ends *done in relay*, its steps show Claude Code, the result lands in lead's conversation from coder after your pick. On disk: the checkout's HEAD and working tree are untouched, and exactly one worktree of it, under the lab's runs folder, carries a commit that changes README.md alone, fixing its first line and nothing else. +**Anti-game:** Graded on what the browser shows, the message log read through the public client, and git. Never on the lab's adapter or the server's own state. Lead can't state the launch date without the reply, because it is drawn per run. The disk check reads git, so a run that only says it fixed the typo fails. The step-3 order check reads entry order as drawn, so a reply drawn before lead's answer fails. Each graded list is floored with `tell.over`; an empty log or no worktree counts only where a control produces it, and says so. +**Model:** real — openai/gpt-5.4-mini (lead, researcher, writer); coder's run on Claude Code +**Run:** `pnpm tsx goals/teammates-lab/a-worker-talks-to-another-while-you-talk/run.mts` (needs `AI_GATEWAY_API_KEY`, and Claude Code signed in or `ANTHROPIC_API_KEY`) +**Controls:** each on the same command, failing the steps named and no other: +- `GOAL_CONTROL=no-model`: the workers answer on a model that doesn't exist. Steps 1, 2, 3 and 5 FAIL. +- `GOAL_CONTROL=no-lead-send`: lead's `sendMessage` is dropped from its tools (a scratch patch to `message-tool.ts`). Steps 2 and 3 FAIL. +- `GOAL_CONTROL=no-reply-tool`: researcher's `sendMessage` is dropped. Step 3 FAILS. +- `GOAL_CONTROL=pick-not-kept`: the pick answers as kept but `setWorkProject` stores nothing (a scratch patch to `work-project.ts`), so the task filed again still has no project and the README never changes. Step 5 FAILS. + +Steps 2 and 3 have no isolating red state for lead's side: without lead's message there is nothing to reply to, so `no-lead-send` reddens both. + +## Verdict log +| Date | Commit | Model | Verdict | Notes | +|------|--------|-------|---------|-------| diff --git a/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/run.mts b/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/run.mts new file mode 100644 index 0000000000..a96b741304 --- /dev/null +++ b/goals/teammates-lab/a-worker-talks-to-another-while-you-talk/run.mts @@ -0,0 +1,479 @@ +/** + * Goal check: in the Teammates lab, you talk to lead, lead messages + * researcher, researcher's reply reaches lead while you are still talking to + * it, and a coding job lead hands coder runs through Claude Code in lead's + * project. See goal.md for the contract. + * + * Real path, real model, out of CI. The lab's pages are built here and served + * by `fsdev dev --app` over a fresh SQLite store, with one project, `relay`, + * mapped to a scratch git checkout made here. One headless browser drives the + * screen as a person would. Graded, per step: + * + * 1 lead answers your first line in its conversation. + * 2 a card "To researcher" in lead's conversation, a line "From lead" in + * researcher's, the exchange under "with researcher" in the Talk panel, + * and a delivered row lead → researcher in the message log. + * 3 your second line goes in before researcher's reply has landed; the reply + * shows in lead's conversation under researcher's name after lead's answer + * to you, a delivered reply row is in the log, and a line of lead's after + * it carries the held-out launch date. + * 4 not run: the history window's mark is gap G1 (FIX-1613). + * 5 with no project, coder's run is refused and the task card asks for one; + * for 30 s nothing else runs and nothing on disk changes; you pick + * `relay`, lead files again, the run goes through Claude Code, a worktree + * of the checkout gets one commit that changes the README's first line and + * nothing else, the checkout itself is untouched, and the result lands in + * lead's conversation from coder. + * + * Inputs are held out: the launch date is drawn at random and written into a + * copy of the workers' tree, and the README's typo is one of several. + * + * Run: pnpm tsx goals/teammates-lab/a-worker-talks-to-another-while-you-talk/run.mts + * Controls: GOAL_CONTROL=no-model | no-lead-send | no-reply-tool | pick-not-kept (see goal.md) + */ +import { spawn, execFileSync, type ChildProcess } from "node:child_process"; +import { cpSync, readFileSync, writeFileSync, mkdirSync } from "node:fs"; +import { join } from "node:path"; +import type { Page } from "playwright"; +import { createClient, readEveryCollectionPage } from "@flow-state-dev/client"; +import { createWorkforceClient, WORKER_MESSAGES_RESOURCE, workerMessageRowSchema } from "@flow-state-dev/workforce/browser"; +import { + DEFAULT_MODEL, + assertPatched, + describePatches, + goalTmpDir, + intentFreeEnv, + loadFixture, + modulePatchEnv, + refuseIfAnswering, + repoPath, + REPO_ROOT, + runGoal, + stopProcessGroup, + type ModulePatch, +} from "../../lib/index.mts"; +import { launchChromium } from "../../lib/playwright.mts"; + +interface Fixture { + port: number; + lead: string; + researcher: string; + coder: string; + ask: string; + second: string; + fix: string; + project: { id: string; title: string }; + typos: { readme: string; wrong: string; right: string }[]; + rest: string; + answerWithinMs: number; + replyWithinMs: number; + unpickedMs: number; + runWithinMs: number; +} + +const fixture = loadFixture(import.meta.url); +const LAB = repoPath("labs", "teammates"); +const CONTROL = process.env.GOAL_CONTROL ?? ""; +const MODEL = process.env.GOAL_MODEL ?? DEFAULT_MODEL; +/** What the page says after you pick a project (the lab's `PICKED_LINE`). */ +const PICKED_LINE = "I picked a project for you. File the task again."; + +/** Drop one worker's `sendMessage`: the capability lists no tool on that worker's turns. */ +const dropSendFor = (worker: string): ModulePatch => ({ + module: "packages/workforce/src/messages/message-tool.ts", + from: String.raw`if \(typeof self !== "string"\) return \[\];`, + to: `if (typeof self !== "string" || self === ${JSON.stringify(worker)}) return [];`, +}); + +/** Each control: what it changes, and the steps it must redden, and only those. */ +const CONTROLS: Record = { + // No model answers: lead's conversation holds only your own lines. + "no-model": { model: "openai/no-such-model-goal-control", steps: ["1", "2", "3", "5"] }, + // lead can't message: no card, no line in researcher's conversation, no row, and so no reply. + "no-lead-send": { patches: [dropSendFor(fixture.lead)], steps: ["2", "3"] }, + // researcher hears lead but can't answer it. + "no-reply-tool": { patches: [dropSendFor(fixture.researcher)], steps: ["3"] }, + // The pick answers as kept but is never stored, so the task filed again still has no project. + "pick-not-kept": { + patches: [ + { + module: "packages/workforce/src/projects/work-project.ts", + from: String.raw`await ctx\.session\.patchState\(\{ \[WORK_PROJECT_STATE_KEY\]: projectRef\(input\.project\) \}\);`, + to: "/* goal control pick-not-kept: not stored */", + }, + ], + steps: ["5"], + }, +}; +if (CONTROL !== "" && CONTROLS[CONTROL] === undefined) { + throw new Error(`unknown GOAL_CONTROL "${CONTROL}"; known: ${Object.keys(CONTROLS).join(", ")}`); +} +const control = CONTROLS[CONTROL]; + +const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); +const git = (cwd: string, ...args: string[]) => execFileSync("git", ["-C", cwd, ...args], { encoding: "utf8" }).trim(); + +const MONTHS = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]; +const pick = (xs: readonly T[]): T => xs[Math.floor(Math.random() * xs.length)]!; + +/** The held-out launch date, and whether a line states it. */ +function launchDate() { + const month = pick(MONTHS.filter((m) => m !== "November")); + const day = 2 + Math.floor(Math.random() * 26); + const said = new RegExp(`\\b${day}(st|nd|rd|th)?\\b`); + const monthSaid = new RegExp(`\\b${month.slice(0, 3)}`, "i"); + return { text: `${day} ${month}`, isIn: (line: string) => said.test(line) && monthSaid.test(line) }; +} + +/** A copy of the lab's workers whose researcher knows the held-out date instead of the shipped one. */ +function workersWith(dir: string, date: string): string { + const tree = join(dir, "workforce"); + cpSync(join(LAB, "workforce"), tree, { recursive: true }); + const file = join(tree, "teams/teammates/workers/researcher/WORKER.md"); + const before = readFileSync(file, "utf8"); + const after = before.replace(/The launch date is [^.\n]+\./, `The launch date is ${date}.`); + if (after === before) throw new Error("setup: researcher's WORKER.md has no launch date line to hold out"); + writeFileSync(file, after); + return tree; +} + +/** A scratch git checkout whose README's first line has a typo; `.fsdev/` ignored, as a run needs. */ +function scratchCheckout(dir: string, typo: Fixture["typos"][number]): string { + const checkout = join(dir, "relay"); + mkdirSync(checkout, { recursive: true }); + writeFileSync(join(checkout, "README.md"), `${typo.readme}\n${fixture.rest}`); + writeFileSync(join(checkout, ".gitignore"), "**/.fsdev/\n"); + git(checkout, "init", "-q", "-b", "main"); + git(checkout, "-c", "user.email=goal@example.com", "-c", "user.name=goal", "add", "."); + git(checkout, "-c", "user.email=goal@example.com", "-c", "user.name=goal", "commit", "-q", "-m", "init"); + return checkout; +} + +/** What the checkout holds, to tell whether anything on disk changed. */ +function diskOf(checkout: string) { + return { + head: git(checkout, "rev-parse", "HEAD"), + status: git(checkout, "status", "--porcelain"), + worktrees: git(checkout, "worktree", "list", "--porcelain"), + branches: git(checkout, "branch", "--list", "--format=%(refname:short) %(objectname)"), + }; +} + +/** Start the lab's server, refusing a port something already answers on. */ +async function startLab(env: Record, log: string): Promise<{ child: ChildProcess; origin: string }> { + const origin = `http://127.0.0.1:${fixture.port}`; + await refuseIfAnswering(origin); + const out: string[] = []; + const child = spawn( + "npx", + ["tsx", "../../packages/cli/bin/fsdev.ts", "dev", "--app", "@flow-state-dev/teammates", "--port", String(fixture.port), "--no-open"], + { cwd: LAB, env, detached: true, stdio: ["ignore", "pipe", "pipe"] }, + ); + const keep = (chunk: Buffer) => { + out.push(chunk.toString()); + writeFileSync(log, out.join("")); + }; + child.stdout!.on("data", keep); + child.stderr!.on("data", keep); + for (const until = Date.now() + 120_000; Date.now() < until; ) { + if (child.exitCode !== null) throw new Error(`the lab exited (${child.exitCode}) before it answered; log: ${log}`); + try { + if ((await fetch(origin, { signal: AbortSignal.timeout(2_000) })).ok) return { child, origin }; + } catch { + // not up yet + } + await sleep(500); + } + stopProcessGroup(child); + throw new Error(`the lab did not answer on ${origin} within 120s; log: ${log}`); +} + +// ---- reading the screen ---------------------------------------------------- + +const conversation = (page: Page) => page.getByRole("main", { name: "Conversation" }); +const workerRow = (page: Page, name: string) => page.locator(`nav[aria-label="Workers"] [data-worker="${name}"]`); + +interface Drawn { + kind: string; + label: string; + text: string; + status?: string; +} + +/** The open conversation's entries in order, as drawn. */ +async function entriesOf(page: Page): Promise { + return await conversation(page) + .locator("[data-entry]") + .evaluateAll((els) => + els.map((el) => ({ + kind: (el as HTMLElement).dataset.entry ?? "", + label: el.getAttribute("aria-label") ?? el.querySelector("[aria-label]")?.getAttribute("aria-label") ?? "", + text: el.textContent ?? "", + status: el.querySelector("[data-task-status]")?.textContent ?? undefined, + })), + ); +} + +/** Read the conversation until `done` holds, or the time runs out; the last reading either way. */ +async function readUntil(page: Page, done: (entries: Drawn[]) => boolean, withinMs: number): Promise<{ entries: Drawn[]; ok: boolean }> { + let entries: Drawn[] = []; + for (const until = Date.now() + withinMs; Date.now() < until; ) { + entries = await entriesOf(page); + if (done(entries)) return { entries, ok: true }; + await sleep(500); + } + return { entries, ok: false }; +} + +async function tell(page: Page, worker: string, text: string): Promise { + const box = page.getByLabel(`Message ${worker}`); + await box.fill(text); + await box.press("Enter"); +} + +async function open(page: Page, worker: string): Promise { + await workerRow(page, worker).click(); + await conversation(page).getByRole("heading", { name: worker }).waitFor({ timeout: 15_000 }); +} + +const userAt = (entries: Drawn[], text: string) => entries.findIndex((e) => e.kind === "user" && e.text.includes(text)); +const short = (id: string) => id.replace(/^teammates\./, ""); + +// --------------------------------------------------------------------------- + +await runGoal(async (failures, tell_) => { + const evidence: string[] = []; + const fail = (step: string, line: string) => failures.push(`[${step}] ${line}`); + const dir = goalTmpDir("teammates-lab"); + const date = launchDate(); + const typo = pick(fixture.typos); + const tree = workersWith(dir, date.text); + const checkout = scratchCheckout(dir, typo); + // Where the lab puts runs: beside its store (`fsdev.config.mts`). + const runsRoot = join(dir, "teammates-runs"); + const lead = short(fixture.lead); + const researcher = short(fixture.researcher); + const coder = short(fixture.coder); + + // The pages, built from this checkout, never assumed. + execFileSync("npx", ["vite", "build", "--logLevel", "error"], { cwd: LAB, stdio: "inherit" }); + + const mark = join(dir, "patched.txt"); + const patches = control?.patches ?? []; + if (patches.length > 0) console.error(`GOAL_CONTROL=${CONTROL} patches:\n${describePatches(patches, REPO_ROOT)}`); + const env = intentFreeEnv(process.env, { + TEAMMATES_MODEL: control?.model ?? MODEL, + TEAMMATES_STORE: join(dir, "teammates.sqlite"), + TEAMMATES_TREE: tree, + TEAMMATES_USER: "you", + TEAMMATES_PROJECTS: JSON.stringify([{ ...fixture.project, checkout }]), + ...(patches.length > 0 ? modulePatchEnv(patches, REPO_ROOT, mark) : {}), + }); + console.error(`goal: launch date ${date.text}; typo "${typo.wrong}"; scratch ${dir}`); + + const browser = await launchChromium(); + let server: ChildProcess | undefined; + try { + const lab = await startLab(env, join(dir, "server.log")); + server = lab.child; + const client = createClient({ userId: "you", baseUrl: lab.origin }); + const workforce = createWorkforceClient(client); + const page = await browser.newPage({ viewport: { width: 1440, height: 900 } }); + await page.goto(lab.origin); + await page.getByLabel(`Message ${lead}`).waitFor({ timeout: 30_000 }); + + /** The message log, read through lead's conversation as any client reads it. */ + const log = async () => { + const session = await workforce.ensureWorkerSession({ worker: fixture.lead }); + const rows = await readEveryCollectionPage(client.resources, session.id, WORKER_MESSAGES_RESOURCE); + return rows.flatMap((row) => { + const parsed = workerMessageRowSchema.safeParse(row.clientData); + return parsed.success ? [parsed.data] : []; + }); + }; + + // ---- 1 · you talk to lead ------------------------------------------------ + await tell(page, lead, fixture.ask); + const sentAsk = Date.now(); + // Step 3's second line goes in as soon as lead has messaged researcher, before the reply can land. + let secondSentAt: number | undefined; + let replyBeforeSecond = false; + const card = conversation(page).getByRole("button", { name: new RegExp(`^To ${researcher}: `) }); + for (const until = sentAsk + fixture.answerWithinMs; Date.now() < until; ) { + if ((await card.count()) > 0) { + replyBeforeSecond = (await conversation(page).getByRole("region", { name: `From ${researcher}` }).count()) > 0; + await tell(page, lead, fixture.second); + secondSentAt = Date.now(); + break; + } + const drawn = await entriesOf(page); + // No message to researcher, but lead has answered: send the second line anyway, so step 3 is graded. + if (drawn.slice(userAt(drawn, fixture.ask) + 1).some((e) => e.kind === "assistant") && Date.now() - sentAsk > 60_000) break; + await sleep(250); + } + if (secondSentAt === undefined) { + await tell(page, lead, fixture.second); + secondSentAt = Date.now(); + } + const one = await readUntil( + page, + (es) => es.slice(userAt(es, fixture.ask) + 1).some((e) => e.kind === "assistant" && e.text.trim() !== ""), + Math.max(0, sentAsk + fixture.answerWithinMs - Date.now()), + ); + const answers1 = tell_.over("1 · entries drawn in lead's conversation", one.entries).filter((e, i) => i > userAt(one.entries, fixture.ask) && e.kind === "assistant"); + if (userAt(one.entries, fixture.ask) < 0) fail("1", "your first line is not in lead's conversation"); + if (answers1.length === 0) fail("1", `no answer from lead after your first line within ${fixture.answerWithinMs / 1000}s`); + else evidence.push(`1: lead answered (${answers1[0]!.text.length} chars)`); + + // ---- 2 · lead messages researcher ------------------------------------------ + const cards = await card.count(); + if (cards === 0) fail("2", `no card "To ${researcher}" in lead's conversation`); + const talk = page.getByRole("complementary", { name: "Talk" }); + if ((await talk.count()) === 0) await conversation(page).getByRole("button", { name: "Talk" }).click(); + const talked = (await talk.getByRole("region", { name: `with ${researcher}` }).count()) > 0; + if (!talked) fail("2", `the Talk panel lists nothing under "with ${researcher}"`); + const rows = tell_.over("2 · message log rows", await log(), { emptyIs: "no message sent, which a control produces" }); + const asked = rows.filter((r) => r.from === fixture.lead && r.to === fixture.researcher); + if (!asked.some((r) => r.status === "delivered")) { + fail("2", `no delivered row ${fixture.lead} → ${fixture.researcher} in the message log (${asked.map((r) => r.status).join(", ") || "none"})`); + } + await open(page, researcher); + const heard = await conversation(page) + .getByRole("region", { name: `From ${lead}` }) + .waitFor({ timeout: 30_000 }) + .then(() => true, () => false); + if (!heard) fail("2", `researcher's conversation shows no line "From ${lead}"`); + if (cards > 0 && talked && heard) evidence.push(`2: card, Talk group, line in researcher's conversation, ${asked.length} log row(s)`); + await open(page, lead); + + // ---- 3 · researcher replies while you are still talking to lead ------------ + if (replyBeforeSecond) fail("3", "researcher's reply had landed before the second line could be sent, so this run doesn't test the step"); + const three = await readUntil( + page, + (es) => { + const at = es.findIndex((e) => e.kind === "received" && e.label === `From ${researcher}`); + return at >= 0 && es.slice(at + 1).some((e) => e.kind === "assistant" && date.isIn(e.text)); + }, + Math.max(0, secondSentAt + fixture.replyWithinMs - Date.now()), + ); + const drawn3 = tell_.over("3 · entries drawn in lead's conversation", three.entries); + const replyAt = drawn3.findIndex((e) => e.kind === "received" && e.label === `From ${researcher}`); + const firstAnswerAt = drawn3.findIndex((e, i) => i > userAt(drawn3, fixture.ask) && e.kind === "assistant"); + if (replyAt < 0) { + fail("3", `no reply "From ${researcher}" in lead's conversation within ${fixture.replyWithinMs / 1000}s of your second line`); + } else { + if (firstAnswerAt < 0 || replyAt < firstAnswerAt) fail("3", "researcher's reply is not after lead's answer to you"); + if (!date.isIn(drawn3[replyAt]!.text)) fail("3", `researcher's reply doesn't carry the launch date ${date.text}: "${drawn3[replyAt]!.text}"`); + const used = drawn3.slice(replyAt + 1).find((e) => e.kind === "assistant" && date.isIn(e.text)); + if (used === undefined) fail("3", `no line of lead's after the reply states the launch date ${date.text}`); + const replies = (await log()).filter((r) => r.from === fixture.researcher && r.to === fixture.lead && r.inReplyTo !== undefined); + if (!replies.some((r) => r.status === "delivered")) fail("3", "no delivered reply row researcher → lead in the message log"); + if (used !== undefined) evidence.push(`3: reply landed after lead's answer; lead's next line says ${date.text}`); + } + + // ---- 4 · the history window ------------------------------------------------ + evidence.push("4: not run, waits on the history window's mark (G1, FIX-1613)"); + + // ---- 5 · lead hands coder a fix, in lead's project ------------------------ + const chip = (await page.getByLabel(`Project for ${lead}`).inputValue()) || "none"; + if (chip !== "none") fail("5", `lead already shows project "${chip}" before any pick`); + const before = diskOf(checkout); + await tell(page, lead, fixture.fix); + const tasks = conversation(page).locator("[data-entry=task]"); + const asking = await readUntil(page, (es) => es.some((e) => e.kind === "task" && e.status === "needs a project"), fixture.answerWithinMs); + if (!asking.ok) { + fail("5", `no task card for ${coder} asking for a project within ${fixture.answerWithinMs / 1000}s (${asking.entries.filter((e) => e.kind === "task").map((e) => e.status).join(", ") || "no task card"})`); + } else { + const prompt = tasks.first().getByRole("group", { name: "Pick a project" }); + if ((await prompt.count()) === 0) fail("5", "the refused task's card shows no project picker"); + await sleep(fixture.unpickedMs); + const waited = await entriesOf(page); + const running = waited.filter((e) => e.kind === "task" && e.status?.startsWith("running")); + if (running.length > 0) fail("5", `with no pick, a run started: ${running.map((e) => e.status).join(", ")}`); + const still = diskOf(checkout); + if (JSON.stringify(still) !== JSON.stringify(before)) fail("5", "with no pick, something changed in the checkout"); + + const picked = await prompt + .getByLabel("Project") + .selectOption(fixture.project.id, { timeout: 15_000 }) + .then(() => prompt.getByRole("button", { name: "Use project" }).click()) + .then(() => true, (error: Error) => (fail("5", `couldn't pick ${fixture.project.id} on the card: ${error.message.split("\n")[0]}`), false)); + if (!picked) throw new Error("step 5 stopped: no pick could be made"); + const ended = await readUntil( + page, + (es) => { + const filed = es.filter((e) => e.kind === "task"); + const last = filed[filed.length - 1]; + return filed.length >= 2 && last!.status !== undefined && /^(done in|failed|refused)/.test(last!.status); + }, + fixture.runWithinMs, + ); + const filed = tell_.over("5 · task cards in lead's conversation", ended.entries.filter((e) => e.kind === "task")); + if (userAt(ended.entries, PICKED_LINE) < 0) fail("5", "your pick was not said to lead as your line"); + const rerun = filed.length >= 2 ? filed[filed.length - 1]! : undefined; + if (rerun === undefined) fail("5", "lead never filed the task again after the pick"); + else if (rerun.status !== `done in ${fixture.project.id}`) fail("5", `the task filed again ended "${rerun.status}", not "done in ${fixture.project.id}"`); + if (rerun?.status === `done in ${fixture.project.id}`) { + // The run, opened on its card: it went through Claude Code. + const rerunCard = tasks.last(); + await rerunCard.getByRole("button", { name: new RegExp(`^Task for ${coder}: `) }).click(); + const runList = rerunCard.getByRole("list", { name: /^Run of / }); + let runText: string | null = ""; + // The run's steps are read once the card opens; give them time to arrive. + for (const until = Date.now() + 30_000; Date.now() < until && !/Claude Code/.test(runText ?? ""); await sleep(500)) { + runText = (await runList.count()) > 0 ? await runList.textContent() : ""; + } + if (!/Claude Code/.test(runText ?? "")) fail("5", `the run's steps don't show it ran on Claude Code: "${(runText ?? "").slice(0, 200)}"`); + + const result = await readUntil(page, (es) => es.some((e) => e.kind === "result" && e.label === `From ${coder}`), 60_000); + // The refused task's ending lands from coder too, before the pick; the run's is the last one. + const resultAt = result.entries.map((e) => e.kind === "result" && e.label === `From ${coder}`).lastIndexOf(true); + if (resultAt < 0) fail("5", `the result never landed in lead's conversation as a line from ${coder}`); + else if (resultAt < userAt(result.entries, PICKED_LINE)) fail("5", `no result from ${coder} after your pick`); + else if (/task failed/.test(result.entries[resultAt]!.text)) fail("5", `${coder}'s last result is a failure: "${result.entries[resultAt]!.text}"`); + } + + // The disk: the checkout untouched, one worktree of it with one commit that fixes the first line only. + const after = diskOf(checkout); + if (after.head !== before.head || after.status !== before.status) fail("5", "the checkout itself changed (HEAD or working tree)"); + const worktrees = tell_.over( + "5 · worktrees of the checkout other than itself", + after.worktrees + .split("\n\n") + .map((block) => ({ path: /^worktree (.+)$/m.exec(block)?.[1], head: /^HEAD (.+)$/m.exec(block)?.[1] })) + .filter((w): w is { path: string; head: string } => w.path !== undefined && w.head !== undefined && w.path !== checkout), + { emptyIs: "no run worked in the checkout, which a control produces" }, + ); + const changed = worktrees.filter((w) => w.head !== before.head); + if (changed.length !== 1) { + fail("5", `${changed.length} worktree(s) of the checkout carry a commit; want exactly one`); + } else { + const [run] = changed; + const files = git(checkout, "diff", "--name-only", before.head, run!.head).split("\n").filter(Boolean); + if (files.join(",") !== "README.md") fail("5", `the run changed ${files.join(", ") || "nothing"}, not README.md alone`); + const readme = git(checkout, "show", `${run!.head}:README.md`).split("\n"); + if (!readme[0]!.includes(typo.right) || readme[0]!.includes(typo.wrong)) fail("5", `the README's first line is still wrong: "${readme[0]}"`); + // `git` here trims the output, so the README's last newline is gone. + if (readme.slice(1).join("\n") !== fixture.rest.trimEnd()) fail("5", "the run changed more of the README than its first line"); + if (!run!.path.startsWith(runsRoot)) fail("5", `the run's worktree ${run!.path} is not under the lab's runs folder`); + evidence.push(`5: refused until picked, then Claude Code fixed "${typo.wrong}" in ${run!.path}, README.md only, checkout untouched`); + } + } + if (patches.length > 0) assertPatched(patches, REPO_ROOT, mark); + } finally { + await browser.close(); + stopProcessGroup(server); + } + + // A control must redden each step it names, and only those. + if (control !== undefined) { + const steps = new Set(failures.map((f) => /^\[([^\]]+)\]/.exec(f)?.[1] ?? "")); + for (const step of control.steps) { + if (!steps.has(step)) failures.push(`[control] GOAL_CONTROL=${CONTROL} left step ${step} green, so that step cannot fail`); + } + for (const step of steps) { + if (!control.steps.includes(step) && step !== "control") failures.push(`[control] GOAL_CONTROL=${CONTROL} also reddened step ${step}`); + } + } + return { failures, evidence: evidence.join("; ") }; +}); diff --git a/labs/teammates/.gitignore b/labs/teammates/.gitignore index 10da5fda8b..6598a4b15e 100644 --- a/labs/teammates/.gitignore +++ b/labs/teammates/.gitignore @@ -1 +1,2 @@ dist-client/ +.fsdev/ diff --git a/labs/teammates/README.md b/labs/teammates/README.md index d21dd72471..c312ab2f43 100644 --- a/labs/teammates/README.md +++ b/labs/teammates/README.md @@ -32,59 +32,72 @@ no session list. The design and the decisions behind it are in the ## Run it -Until wiring, the screen runs on fixtures that play the script on a timer: +The lab runs on a real model and a durable SQLite store, served by `fsdev dev`: ```bash -pnpm --filter @flow-state-dev/teammates dev +TEAMMATES_PROJECTS='[{"id":"relay","title":"Relay","checkout":"/abs/path/to/a/git/checkout"}]' \ + pnpm --filter @flow-state-dev/teammates dev ``` -Ask lead for something, say *"Ask researcher for our launch date, and help me outline the post."* -lead answers and messages researcher. Before researcher replies, send lead a second line: the reply -shows as pending, then lands after lead's answer. lead's conversation already runs past the 50-turn -history window, so the divider is in view. +This builds the pages and serves them with the lab's server (`fsdev.config.mts`). It reads: + +| Variable | What it sets | Default | +|---|---|---| +| `TEAMMATES_MODEL` | the model lead, researcher and writer answer on | `openai/gpt-5.4-mini` | +| `TEAMMATES_PROJECTS` | a JSON list of projects to create at start, each `{ "id", "title", "checkout"? }` | none | +| `TEAMMATES_STORE` | the SQLite file | `.fsdev/teammates.sqlite` here | +| `TEAMMATES_USER` | who the page acts as | `you` | +| `TEAMMATES_TREE` | the workers' tree | `workforce/` here | + +The model needs a credential the gateway takes (`AI_GATEWAY_API_KEY`), and coder's runs need Claude +Code signed in, or `ANTHROPIC_API_KEY`. A project's `checkout` is a git checkout on this machine; +each coding run works in a worktree of it, so its `.gitignore` must ignore `**/.fsdev/`, where a run +keeps its own notes. A run refuses a checkout that doesn't. + +Ask lead *"Ask researcher for our launch date, and help me outline the post."* lead answers and +messages researcher. Before researcher replies, send lead a second line: the reply shows as pending, +then lands after lead's answer, and lead uses it in its next line. Then ask lead *"Have coder fix the typo in the README's first line."* The task card asks for a project. Pick `relay`: lead files the task again, coder's run shows its steps, and the result lands in lead's conversation. -After wiring, the lab runs against a real model and a durable store: - -```bash -fsdev dev --app @flow-state-dev/teammates -``` - -Wiring adds the host file, which composes `@flow-state-dev/memory` into each worker's flow: the -capability in `uses` to read it, and `afterAnswer: mem.captureFromItems` to record each turn. It -also adds the lab's one small flow: coder's worker flow, one `harnessManager` per harness over -`projectWorkspace()`, routing each task by the worker's `harness` setting. +The goal check drives all of this in a browser: +[`goals/teammates-lab/a-worker-talks-to-another-while-you-talk`](../../goals/teammates-lab/a-worker-talks-to-another-while-you-talk/goal.md). -## Fixtures +## What the screen reads -Everything the screen reads and writes goes through one adapter, `src/adapter.ts`. Each function -names the package call it stands for, and until wiring they run on `src/fixtures.ts`, marked -`fixture:`. At wiring the fixtures are deleted and each function calls the package. +Everything the screen reads and writes goes through one adapter, `src/adapter.ts`, and each function +names the package call it makes. -| Fixture stands in for | Package piece | +| On screen | Package piece | |---|---| -| The divider and its *summarized* label | G1: the history window's opt-in summary and the mark it leaves, tracked under FIX-1613 | -| The pending line, joined to the conversation by message id | G2: a received message as its own item, carrying its id (an ask of FIX-2070) | -| Workers messaging each other, the Talk panel | `sendMessage`, `receive` and the message log, as FIX-2070 ships them | -| The worker list, sending, the conversation, busy status | `roster()`, `ensureWorkerSession`, `respond`, session items, `listSessionRequests` | -| A worker's project, and picking it | FIX-2161's `setWorkProject` and the `workProjectId` it writes on the worker's default conversation | -| Task cards, the refusal for want of a project | the conversation board's rows (`listTasks_tasks`), and `projectWorkspace()`'s `no-project` refusal | -| coder's runs | the task row's `run` link, followed with `followRequest` and `useSession`, on a harness picked by coder's `harness` setting | +| The worker list, sending, the conversation, busy status | the workforce client's `roster()` and `ensureWorkerSession`, the flow's `respond`, session items, `listSessionRequests` | +| Workers messaging each other, the Talk panel | `sendMessage`, the received-message item (`workforce:received`), and the message log | +| A worker's project, and picking it | `setWorkProject`, read back from that action's own answer | +| Task cards, the refusal for want of a project | the conversation board's rows, and `projectWorkspace()`'s `no-project` refusal | +| coder's runs | the task row's `run` link, read as the run session's items | + +Not wired yet: + +- **The divider and its *summarized* label** wait on the history window's mark (G1, FIX-1613). Until + then the screen draws no divider. +- **A worker's project, read from its conversation.** The package keeps it on the conversation as + `workProjectId`, but doesn't show that state to a client, so the screen reads the last + `setWorkProject` answer instead. A pick made anywhere else isn't seen. +- **Which harness coder runs on.** The roster doesn't carry a worker's settings, so the screen names + the harness from the run's own steps once it starts. ## What this app adds Every file in the lab, by kind. `node scripts/inventory.mjs` fails on a file that is none of these, -and on a flow over 200 lines; `--wired` also fails while a fixture is left. +and on a flow over 200 lines; `--wired` also fails on any fixture. | Kind | Files | Lines | |---|---:|---:| -| Configuration | 14 | 279 | -| React UI | 16 | 1113 | -| Small flows | 0 | 0 | -| Fixtures (deleted at wiring) | 1 | 353 | -| Checks (not app code) | 3 | 362 | +| Configuration | 16 | 508 | +| React UI | 18 | 1535 | +| Small flows | 1 | 148 | +| Checks (not app code) | 4 | 713 | diff --git a/labs/teammates/fsdev.config.mts b/labs/teammates/fsdev.config.mts new file mode 100644 index 0000000000..98831b3df1 --- /dev/null +++ b/labs/teammates/fsdev.config.mts @@ -0,0 +1,28 @@ +/** + * The Teammates lab's server, as `fsdev dev --app @flow-state-dev/teammates` + * loads it from this folder. Everything is read from the environment: + * + * - `TEAMMATES_MODEL`: the model lead, researcher and writer answer on + * (default `openai/gpt-5.4-mini`). + * - `TEAMMATES_PROJECTS`: a JSON list of projects to create at start, each + * `{ "id", "title", "checkout"? }`. A project with a `checkout` (an absolute + * path to a git checkout) has its coding runs work in a worktree of it. + * - `TEAMMATES_STORE`: the SQLite file (default `.fsdev/teammates.sqlite` here). + * - `TEAMMATES_USER`: who the page acts as (default `you`). + * - `TEAMMATES_TREE`: the workers' tree (default `workforce/` here). + */ +import { mkdirSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { defaultStore, openTeammates, type LabProject } from "./host.mts"; + +const store = process.env.TEAMMATES_STORE ?? defaultStore(); +mkdirSync(dirname(store), { recursive: true }); + +export default await openTeammates({ + store, + model: process.env.TEAMMATES_MODEL ?? "openai/gpt-5.4-mini", + userId: process.env.TEAMMATES_USER ?? "you", + projects: JSON.parse(process.env.TEAMMATES_PROJECTS ?? "[]") as LabProject[], + runsRoot: join(dirname(store), "teammates-runs"), + ...(process.env.TEAMMATES_TREE === undefined ? {} : { tree: process.env.TEAMMATES_TREE }), +}); diff --git a/labs/teammates/host.mts b/labs/teammates/host.mts new file mode 100644 index 0000000000..1fba7280d5 --- /dev/null +++ b/labs/teammates/host.mts @@ -0,0 +1,162 @@ +/** + * The lab's server, put together from package pieces: the workers in + * `workforce/`, the built-in agent flow with memory composed in, the lab's one + * coding flow, a projects flow, and a store. `fsdev.config.mts` calls + * {@link openTeammates} and default-exports the `FlowState` it returns. + * + * - **lead, researcher and writer** run on the built-in `agent` flow, so each + * has `sendMessage` and one conversation where messages land. Memory is + * composed in through `uses` (read) and `afterAnswer` (record each turn). + * - **coder** runs on the lab's coding flow (`src/flows/coder.ts`), which + * takes the tasks lead files and runs each through the harness coder's + * `WORKER.md` names, in the project of the conversation that filed it. + * - **Projects** are the user's Workforce projects. The ones the config names + * are created at start, as the lab's user, and a project that names a + * checkout on this machine runs its coding work in a worktree of it. + * + * Durable, on SQLite: a worker message a busy host turned away is sent again + * on its session's wake, and a restart keeps every conversation. + */ +import { join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { codexAgent } from "@flow-state-dev/codex"; +import { harnessEnv } from "@flow-state-dev/core"; +import type { HarnessBlock } from "@flow-state-dev/core/types"; +import { CLAUDE_CODE_PASS, claudeCodeAgent } from "@flow-state-dev/claude-code/sdk"; +import { createFlowState, runAction } from "@flow-state-dev/engine"; +import { system } from "@flow-state-dev/memory"; +import { sqliteStores } from "@flow-state-dev/store-sqlite"; +import { defineFlow } from "@flow-state-dev/core"; +import { DEFAULT_ORG_ID } from "@flow-state-dev/core/types"; +import { + AGENT_FLOW, + createWorkerInstallation, + defineAgentWorkerFlow, + defineProjectBlocks, + hireWorkforce, + projectWorkspace, +} from "@flow-state-dev/workforce"; +import { readDeclaredRoster } from "@flow-state-dev/workforce/loader"; +import { localWorkspaceHost } from "@flow-state-dev/workspace"; +import { CODER_FLOW, coderFlow, type Harness } from "./src/flows/coder.ts"; + +/** The workers, beside this file. */ +export const TEAMMATES_TREE = fileURLToPath(new URL("./workforce", import.meta.url)); + +/** The flow the lab's projects are created on. */ +export const PROJECTS_FLOW = "teammates-projects"; + +/** One project the lab starts with. */ +export interface LabProject { + id: string; + title: string; + /** An absolute path to a git checkout on this machine; its coding runs work in a worktree of it. */ + checkout?: string; +} + +export interface TeammatesOptions { + /** The SQLite file the lab keeps everything in. */ + store: string; + /** The model lead, researcher and writer answer on, and memory records with. */ + model: string; + /** The user the page and the start-up writes act as. */ + userId: string; + /** The projects to create at start, unless the user already has them. */ + projects?: readonly LabProject[]; + /** Where coding runs' worktrees go. */ + runsRoot: string; + /** The workers' tree. Defaults to {@link TEAMMATES_TREE}. */ + tree?: string; + /** Wall-clock budget for one coding run. Defaults to 20 minutes. */ + runTimeoutMs?: number; +} + +/** The harnesses a coding worker may name in `harness:`. Each run gets only the environment its harness needs. */ +const HARNESSES: Record = { + "claude-code": (feeds) => + claudeCodeAgent({ + ...feeds, + env: harnessEnv({ pass: CLAUDE_CODE_PASS }), + detached: true, + recordWork: true, + allowedTools: ["Read", "Write", "Edit", "Bash"], + permissionMode: "acceptEdits", + } as never) as unknown as HarnessBlock, + codex: ({ cwd, resume, onSession }) => + codexAgent({ cwd, resume, onSession, thread: { sandboxMode: "workspace-write" } } as never) as unknown as HarnessBlock, +}; + +/** The remote a project with a checkout stores as its `repository`. */ +const remoteOf = (checkout: string) => `file://${checkout}`; + +/** + * Build the lab's server and create its projects. + * + * @throws When the workers' tree doesn't load, or a project can't be created. + */ +export async function openTeammates(options: TeammatesOptions) { + const roster = await readDeclaredRoster(options.tree ?? TEAMMATES_TREE); + if (roster.problems.length > 0) { + throw new Error(`teammates: the workers did not load: ${roster.problems.map((p) => `${p.layer} ${p.path}`).join(", ")}`); + } + + const projects = options.projects ?? []; + const checkouts = projects.flatMap((p) => + p.checkout === undefined ? [] : [{ remote: remoteOf(p.checkout), checkout: p.checkout, projects: [{ orgId: DEFAULT_ORG_ID, id: p.id }] }], + ); + + const mem = system({ model: options.model, working: { capacity: 7 }, episodic: true, semantic: true }); + let flows: Record = {}; + const installation = createWorkerInstallation({ standardWorkers: roster.workers, workerFlows: () => flows as never }); + flows = { + [AGENT_FLOW]: defineAgentWorkerFlow({ + installation, + model: options.model, + uses: [mem.capability.presets({ recall: false, connect: false, semantic: true, episodic: true })], + afterAnswer: mem.captureFromItems, + }), + [CODER_FLOW]: coderFlow({ + harnesses: HARNESSES, + workspace: localWorkspaceHost({ + root: options.runsRoot, + remotes: { allow: ["file"] }, + localRepositories: checkouts.map((c) => c.checkout), + source: projectWorkspace({ checkouts }), + }), + runTimeoutMs: options.runTimeoutMs ?? 20 * 60_000, + }), + }; + const copies = hireWorkforce(installation) as Array<{ id: string }>; + const projectsFlow = defineFlow({ kind: PROJECTS_FLOW, actions: defineProjectBlocks().actions } as never) as { id?: string }; + + const state = createFlowState({ + flows: { ...Object.fromEntries(copies.map((copy) => [copy.id, copy])), [PROJECTS_FLOW]: projectsFlow }, + stores: { default: { primary: sqliteStores({ filename: options.store }) } }, + durable: true, + devtool: { userId: options.userId }, + } as never); + + // The projects, as the lab's user. One the user already has comes back unchanged. + const runtime = await state.getRuntime(); + for (const project of projects) { + const result = (await runAction({ + flow: projectsFlow, + actionName: "createProject", + input: { id: project.id, title: project.title, ...(project.checkout === undefined ? {} : { repository: remoteOf(project.checkout) }) }, + userId: options.userId, + orgId: DEFAULT_ORG_ID, + sessionId: `${PROJECTS_FLOW}-${options.userId}`, + stores: runtime.stores, + runtimeConfig: runtime.runtimeConfig, + } as never)) as { error?: unknown }; + if (result.error !== undefined) { + await state.dispose(); + throw new Error(`teammates: project "${project.id}" was not created: ${JSON.stringify(result.error)}`); + } + } + return state; +} + +/** Where a lab run keeps its store and runs by default: `.fsdev/` beside this file. */ +export const LAB_DATA = fileURLToPath(new URL("./.fsdev", import.meta.url)); +export const defaultStore = () => join(LAB_DATA, "teammates.sqlite"); diff --git a/labs/teammates/package.json b/labs/teammates/package.json index 635e42a258..2864760b7c 100644 --- a/labs/teammates/package.json +++ b/labs/teammates/package.json @@ -9,8 +9,9 @@ ".": "./cli/index.ts" }, "scripts": { - "dev": "vite", + "dev": "vite build && tsx ../../packages/cli/bin/fsdev.ts dev --app @flow-state-dev/teammates", "build": "vite build", + "fsdev": "tsx ../../packages/cli/bin/fsdev.ts", "typecheck": "node ../../scripts/typecheck.mjs", "test": "vitest run --root .", "inventory": "node scripts/inventory.mjs", @@ -33,5 +34,21 @@ "tailwindcss": "^4.1.12", "vite": "^7.1.3", "vitest": "^3.2.4" + }, + "dependencies": { + "@flow-state-dev/claude-code": "workspace:*", + "@flow-state-dev/client": "workspace:*", + "@flow-state-dev/codex": "workspace:*", + "@flow-state-dev/core": "workspace:*", + "@flow-state-dev/devtool": "workspace:*", + "@flow-state-dev/engine": "workspace:*", + "@flow-state-dev/fsdev": "workspace:*", + "@flow-state-dev/harness-manager": "workspace:*", + "@flow-state-dev/memory": "workspace:*", + "@flow-state-dev/orchestration": "workspace:*", + "@flow-state-dev/store-sqlite": "workspace:*", + "@flow-state-dev/workforce": "workspace:*", + "@flow-state-dev/workspace": "workspace:*", + "zod": "^3.24.1" } } diff --git a/labs/teammates/src/App.tsx b/labs/teammates/src/App.tsx index cf487ccd84..55674a1dcc 100644 --- a/labs/teammates/src/App.tsx +++ b/labs/teammates/src/App.tsx @@ -28,7 +28,8 @@ export function App({ adapter }: { adapter: LabAdapter }) { setWorkers(roster); setProjects(projectRows); setSessions(Object.fromEntries(talking.map((w, i) => [w.id, ids[i]]))); - setSelected((current) => current ?? roster[0]?.id); + // Open on the first worker you can talk to: one that takes tasks only has no conversation. + setSelected((current) => current ?? talking[0]?.id ?? roster[0]?.id); })(); return () => { live = false; diff --git a/labs/teammates/src/adapter.ts b/labs/teammates/src/adapter.ts index 10aaa911cb..3c40ba3cf4 100644 --- a/labs/teammates/src/adapter.ts +++ b/labs/teammates/src/adapter.ts @@ -1,28 +1,45 @@ /** * The lab's one way in and out. Every read and write the screen makes goes - * through `LabAdapter`, and nothing else in `src/` touches a package. + * through `LabAdapter`, and nothing else in `src/` touches a package. Each + * function is bound to the package call it stands for: * - * Until wiring, `createLabAdapter()` returns the fixtures (`fixtures.ts`), - * which play the script on a timer. At wiring, each function is bound to the - * package call it stands for, by its post-refactor name, and the fixtures are - * deleted: + * | Function | Bound to | + * |---------------------|------------------------------------------------------------------------------| + * | `listWorkers` | the workforce client's `roster()` | + * | `openConversation` | `ensureWorkerSession({ worker })`: the worker's default conversation | + * | `send` | the worker's door, `respond`, in that conversation | + * | `watchConversation` | the session's items, from its snapshot and then its stream | + * | `watchTalk` | the user's message log (`workforceMessages`), as `sendMessage` writes it | + * | `watchActivity` | `listSessionRequests` on the worker's conversation | + * | `watchWindow` | the mark the history window leaves: gap G1 (FIX-1613), not yet in the package | + * | `listProjects` | the user's projects, read through their roster session | + * | `watchWorkProject` | the answer of the conversation's last `setWorkProject` (FIX-2161) | + * | `setWorkProject` | the workforce client's `setWorkProject(worker, project)` | + * | `watchTasks` | the board's rows, as the conversation's stream carries each one (`task-change`) | + * | `watchRun` | the items of the session the task's row names as its run | * - * | Function | Bound at wiring to | - * |---------------------|-------------------------------------------------------------------------| - * | `listWorkers` | the workforce client's `roster()` | - * | `openConversation` | `ensureWorkerSession({ worker })`: the worker's default conversation | - * | `send` | the worker's `respond` entry in that conversation | - * | `watchConversation` | the session's items, live (`@flow-state-dev/react`) | - * | `watchTalk` | the user's message log, as `sendMessage` and `receive` write its rows | - * | `watchActivity` | `listSessionRequests` on the worker's conversation | - * | `watchWindow` | the mark the history window leaves where the turns read word for word begin | - * | `listProjects` | the user's projects, as the workforce client lists them | - * | `watchWorkProject` | the worker's `workProjectId`, on its default conversation (FIX-2161) | - * | `setWorkProject` | FIX-2161's `setWorkProject(worker, project)` | - * | `watchTasks` | the conversation board's rows (`listTasks_tasks`) | - * | `watchRun` | the task row's `run` link, followed (`followRequest`, `useSession`) | + * A received message is drawn from its own item (`workforce:received`), which + * carries its message id, so the pending line joins the log to the + * conversation by id (gap G2, shipped with FIX-2070). + * + * The page acts as the user `fsdev dev` hands it (the config's `devtool` + * block), with the bearer token when there is one, on the server it came from. */ -import { createFixtureLab } from "./fixtures"; +import { createClient, readEveryCollectionPage, type Client, type SessionRequestSummary } from "@flow-state-dev/client"; +import type { OutputItem } from "@flow-state-dev/core/items"; +import { readBearerToken, readUserId, withBearerToken } from "@flow-state-dev/devtool/react"; +import { + createWorkforceClient, + RECEIVED_MESSAGE_COMPONENT, + ROSTER_FLOW, + SEND_MESSAGE_TOOL, + SET_WORK_PROJECT_ACTION, + WORKER_MESSAGES_RESOURCE, + workerMessageRowSchema, + type WorkforceClient, +} from "@flow-state-dev/workforce/browser"; +import { CODER_FLOW } from "./lib/coder-flow"; +import { sessionFeeds, type SessionFeed } from "./lib/session-feed"; /** Stops a watch. */ export type Unsubscribe = () => void; @@ -37,8 +54,6 @@ export interface WorkerRow { role: string; /** It takes tasks only: it has no conversation, and work reaches it as a task. */ takesTasks?: boolean; - /** The coding harness its tasks run through, from its `WORKER.md` `harness` setting. */ - harness?: string; } /** One of the user's projects: where a worker's runs get their files. */ @@ -56,11 +71,13 @@ export interface BoardTask { /** The worker it was filed for. */ to: string; title: string; - status: "needs-project" | "running" | "done"; + status: "needs-project" | "running" | "done" | "failed"; /** The project its run works in; none when it was refused. */ project?: string; - /** What the run reported when it ended. */ + /** What the run reported when it ended, or why it failed. */ result?: string; + /** The session its run works in, once it started. */ + runSessionId?: string; } /** One step of a task's run, as the harness reported it. */ @@ -80,7 +97,7 @@ export type ConversationEntry = /** The worker filed a task; the card reads the board's row by its id. */ | { kind: "task"; id: string; taskId: string } /** A task it filed ended, as a line under the name of the worker that ran it. */ - | { kind: "result"; id: string; taskId: string; from: string; text: string }; + | { kind: "result"; id: string; taskId: string; from: string; text: string; failed?: boolean }; /** What a conversation shows now. */ export interface ConversationView { @@ -99,6 +116,8 @@ export interface TalkRow { inReplyTo?: string; /** When it was sent, in ms. */ at: number; + /** It was refused, or nobody took it in time: it will never land. */ + undelivered?: boolean; } /** Whether a worker is busy, read from its conversation's requests. */ @@ -139,7 +158,301 @@ export interface LabAdapter { watchRun(taskId: string, onChange: (steps: RunStep[]) => void): Unsubscribe; } -/** The adapter the app runs on. */ -export function createLabAdapter(): LabAdapter { - return createFixtureLab(); +/** How often the reads with no stream are read again. */ +const POLL_MS = 1_500; +/** The accessor the user's shared projects are read under, on their roster session. */ +const PROJECTS = "projects"; +/** The keyed item a conversation's board emits for each row it changes. */ +const TASK_CHANGE = "task-change"; +/** The tool a worker files a task with. */ +const CREATE_TASK = "createTask"; +/** Requests that are a worker answering: everything but the board's own passes and the project write. */ +const QUIET_ACTIONS = new Set(["dispatch", SET_WORK_PROJECT_ACTION]); +/** The harness a run's items came from, by the block that emitted them. */ +const HARNESS_LABEL: Record = { "claude-code-agent": "Claude Code", "codex-agent": "Codex", "cursor-agent": "Cursor" }; + +/** An item, read loosely: each read below checks the fields it uses. */ +type Item = Record; + +/** The text of a message item. */ +const textOf = (item: Item): string => + (Array.isArray(item.content) ? item.content : []) + .map((part: { text?: unknown }) => (typeof part.text === "string" ? part.text : "")) + .join(""); + +const parseArgs = (item: Item): Record => { + try { + return JSON.parse(String(item.toolCall?.arguments ?? "{}")) as Record; + } catch { + return {}; + } +}; + +/** Read `read` now and every {@link POLL_MS} until stopped; a failed read keeps the last value. */ +function poll(read: () => Promise, onValue: (value: T) => void): Unsubscribe { + let live = true; + let last = ""; + const tick = async () => { + try { + const value = await read(); + const seen = JSON.stringify(value); + if (live && seen !== last) { + last = seen; + onValue(value); + } + } catch (error) { + console.error("teammates: a read failed", error); + } + if (live) timer = setTimeout(() => void tick(), POLL_MS); + }; + let timer = setTimeout(() => void tick(), 0); + return () => { + live = false; + clearTimeout(timer); + }; +} + +/** The latest copy of each board row in a conversation's items, oldest filing first. */ +function boardRows(items: readonly Item[]): Map> { + const rows = new Map>(); + for (const item of items) { + if (item.type === "component" && item.component === TASK_CHANGE && item.data?.task?.id) rows.set(item.data.task.id, item.data.task); + } + return rows; +} + +/** A board row as a task card. A run refused `no-project` is one that waits for a project. */ +function toBoardTask(row: Record): BoardTask { + const filedIn = row.metadata?.filedInProject; + const project = typeof filedIn === "string" ? filedIn.slice(filedIn.indexOf("/") + 1) : undefined; + const error = typeof row.error === "string" ? row.error : undefined; + const status: BoardTask["status"] = + row.status === "completed" + ? "done" + : row.status === "errored" || row.status === "cancelled" + ? error?.includes("(no-project)") + ? "needs-project" + : "failed" + : "running"; + const answer = typeof row.output?.answer === "string" ? row.output.answer : undefined; + return { + id: row.id, + to: row.assignee ?? "", + title: row.title ?? row.goal ?? row.id, + status, + ...(project === undefined ? {} : { project }), + ...((answer ?? error) === undefined ? {} : { result: answer ?? error }), + ...(typeof row.run?.sessionId === "string" ? { runSessionId: row.run.sessionId } : {}), + }; +} + +/** A conversation's items as the entries the screen draws. */ +function toEntries(items: readonly Item[], workers: ReadonlySet): ConversationEntry[] { + const rows = boardRows(items); + const entries: ConversationEntry[] = []; + for (const item of items) { + if (item.type === "message" && item.role === "user") { + entries.push({ kind: "user", id: item.id, text: textOf(item) }); + } else if (item.type === "message" && item.role === "assistant" && workers.has(item.agentName)) { + // A task it filed ended: the board's line under the worker that ran it. + const taskId = /\((task_[^)\s]+)\)/.exec(textOf(item))?.[1] ?? ""; + const row = rows.get(taskId); + const task = row === undefined ? undefined : toBoardTask(row); + entries.push({ kind: "result", id: item.id, taskId, from: item.agentName, text: task?.result ?? textOf(item), ...(task?.status === "done" ? {} : { failed: true }) }); + } else if (item.type === "message" && item.role === "assistant") { + const text = textOf(item); + if (text.trim() !== "") entries.push({ kind: "assistant", id: item.id, text }); + } else if (item.type === "tool_output" && item.toolCall?.name === SEND_MESSAGE_TOOL) { + const args = parseArgs(item); + const messageId = item.output?.sent ?? item.output?.callId; + if (typeof messageId === "string" && typeof args.to === "string") { + entries.push({ kind: "sent", id: item.id, messageId, to: args.to, text: String(args.text ?? "") }); + } + } else if (item.type === "tool_output" && item.toolCall?.name === CREATE_TASK && item.output?.ok === true) { + entries.push({ kind: "task", id: item.id, taskId: item.output.taskId }); + } else if (item.type === "component" && item.component === RECEIVED_MESSAGE_COMPONENT) { + const { id, from, text, inReplyTo } = item.data ?? {}; + entries.push({ kind: "received", id: item.id, messageId: id, from, text, ...(inReplyTo === undefined ? {} : { inReplyTo }) }); + } + } + return entries; +} + +/** Who a worker's conversation's requests say it is: answering now, and when it last did anything. */ +function activityOf(requests: readonly SessionRequestSummary[]): Activity { + const answering = requests.filter((r) => !QUIET_ACTIONS.has(r.actionName)); + return { + running: answering.some((r) => r.status === "in_progress"), + lastActiveAt: Math.max(0, ...answering.map((r) => r.completedAtMs ?? r.failedAtMs ?? r.startedAtMs ?? 0)), + }; +} + +/** The connection `fsdev dev` served this page with. */ +function connect(): Client { + return createClient({ userId: readUserId(), baseUrl: "", fetcher: withBearerToken(readBearerToken()) }); +} + +/** The adapter the app runs on: the package, through one client. */ +export function createLabAdapter(client: Client = connect()): LabAdapter { + const workforce: WorkforceClient = createWorkforceClient(client); + const feeds = sessionFeeds(client); + /** Each worker's conversation, and the flow it runs on, once opened. */ + const conversations = new Map(); + const flowOfSession = new Map(); + /** The workers, by id, so a line under a worker's name reads as a task's ending. */ + let workerIds = new Set(); + /** Each shared project's visibility, as listed. */ + const visibility = new Map(); + /** The run session of each task seen on a board. */ + const runOf = new Map(); + /** A pick this page made, until the conversation's own requests show it. */ + const picked = new Map(); + + const conversationOf = async (worker: string) => { + const known = conversations.get(worker); + if (known !== undefined) return known; + const session = await workforce.ensureWorkerSession({ worker }); + const opened = { sessionId: session.id, flow: session.flowKind }; + conversations.set(worker, opened); + flowOfSession.set(session.id, session.flowKind); + return opened; + }; + + /** Any conversation of the user's: the message log is read through one. */ + const anyConversation = async () => conversations.values().next().value ?? (await conversationOf((await workforce.roster()).find((w) => w.flow !== CODER_FLOW)!.id)); + + const watchFeed = (sessionId: string, map: (items: Item[]) => T, onChange: (value: T) => void): Unsubscribe => + (feeds(sessionId) as SessionFeed).watch((items: readonly OutputItem[]) => onChange(map(items as unknown as Item[]))); + + return { + async listWorkers() { + const roster = await workforce.roster(); + workerIds = new Set(roster.map((w) => w.id)); + return roster.map((w) => ({ + id: w.id, + name: w.name ?? w.id.slice(w.id.lastIndexOf(".") + 1), + role: w.description ?? "", + ...(w.flow === CODER_FLOW ? { takesTasks: true } : {}), + })); + }, + async openConversation(worker) { + return (await conversationOf(worker)).sessionId; + }, + async send(sessionId, text) { + const flow = flowOfSession.get(sessionId); + if (flow === undefined) throw new Error(`teammates: ${sessionId} is not an open conversation`); + await client.flow(flow).send("respond", { message: text }, { sessionId }); + }, + watchConversation(sessionId, onChange) { + let entries: ConversationEntry[] = []; + let running = false; + const emit = () => onChange({ entries, running }); + const stopFeed = watchFeed(sessionId, (items) => { + for (const row of boardRows(items).values()) if (typeof row.run?.sessionId === "string") runOf.set(row.id, row.run.sessionId); + return toEntries(items, workerIds); + }, (next) => { + entries = next; + emit(); + }); + const stopPoll = poll( + () => client.sessions.requests(sessionId, { status: "in_progress" }), + (requests) => { + running = activityOf(requests).running; + emit(); + }, + ); + return () => { + stopFeed(); + stopPoll(); + }; + }, + watchTalk(worker, onChange) { + return poll( + async () => { + const { sessionId } = await anyConversation(); + const rows = await readEveryCollectionPage(client.resources, sessionId, WORKER_MESSAGES_RESOURCE); + return rows + .map((row) => workerMessageRowSchema.safeParse(row.clientData)) + .flatMap((parsed) => (parsed.success ? [parsed.data] : [])) + .filter((m) => m.from === worker || m.to === worker) + .sort((a, b) => a.at - b.at) + .map((m) => ({ + id: m.id, + from: m.from, + to: m.to, + text: m.text, + at: m.at, + ...(m.inReplyTo === undefined ? {} : { inReplyTo: m.inReplyTo }), + ...(m.status === "refused" || m.status === "undeliverable" ? { undelivered: true } : {}), + })); + }, + onChange, + ); + }, + watchActivity(worker, onChange) { + return poll(async () => { + const known = conversations.get(worker); + // A worker that takes tasks only has no conversation: it is busy while a run it was handed is. + if (known === undefined) return { running: false, lastActiveAt: 0 }; + return activityOf(await client.sessions.requests(known.sessionId, { limit: 20 })); + }, onChange); + }, + watchWindow(_sessionId, onChange) { + // G1 (FIX-1613): the package leaves no mark yet, so no divider is drawn. + onChange(undefined); + return () => {}; + }, + async listProjects() { + // Reading the roster opens the user's roster session, where their projects are kept. + await workforce.roster(); + const roster = (await client.sessions.list({ flowKind: ROSTER_FLOW, userId: client.userId }))[0]; + if (roster === undefined) return []; + const rows = await readEveryCollectionPage(client.resources, roster.id, PROJECTS); + return rows.flatMap((row) => { + const project = row.clientData as { id?: string; title?: string; members?: string[] } | undefined; + if (typeof project?.id !== "string" || !(project.members ?? []).includes(client.userId)) return []; + visibility.set(project.id, "shared"); + return [{ id: project.id, name: project.title ?? project.id }]; + }); + }, + watchWorkProject(worker, onChange) { + return poll(async () => { + const { sessionId } = await conversationOf(worker); + const done = await client.sessions.requests(sessionId, { status: "completed", includeResultOutput: true, limit: 200 }); + const last = done + .filter((r) => r.actionName === SET_WORK_PROJECT_ACTION) + .sort((a, b) => (b.completedAtMs ?? 0) - (a.completedAtMs ?? 0))[0]; + const project = (last?.result?.output as { project?: { id?: string } } | undefined)?.project?.id; + return project ?? picked.get(worker); + }, onChange); + }, + async setWorkProject(worker, project) { + await workforce.setWorkProject(worker, { visibility: visibility.get(project) ?? "shared", id: project }); + picked.set(worker, project); + }, + watchTasks(sessionId, onChange) { + return watchFeed(sessionId, (items) => [...boardRows(items).values()].map(toBoardTask), onChange); + }, + watchRun(taskId, onChange) { + let stopFeed: Unsubscribe | undefined; + // The run's session is named on the task's row once it starts. + const stopWait = poll(async () => runOf.get(taskId), (sessionId) => { + if (sessionId === undefined || stopFeed !== undefined) return; + stopFeed = watchFeed(sessionId, (items) => { + const steps: RunStep[] = []; + const block = items.find((i) => HARNESS_LABEL[i.provenance?.blockName ?? ""] !== undefined)?.provenance?.blockName; + if (block !== undefined) steps.push({ id: "harness", text: `on ${HARNESS_LABEL[block]}` }); + for (const item of items) { + if (item.type === "message" && item.role === "assistant" && textOf(item).trim() !== "") steps.push({ id: item.id, text: textOf(item) }); + else if (item.type === "tool_output" && typeof item.toolCall?.name === "string") steps.push({ id: item.id, text: item.toolCall.name }); + } + return steps; + }, onChange); + }); + return () => { + stopWait(); + stopFeed?.(); + }; + }, + }; } diff --git a/labs/teammates/src/components/Conversation.tsx b/labs/teammates/src/components/Conversation.tsx index 79713af9bf..596aa7fd75 100644 --- a/labs/teammates/src/components/Conversation.tsx +++ b/labs/teammates/src/components/Conversation.tsx @@ -7,6 +7,9 @@ import { Composer } from "./Composer"; import { Entry } from "./Entry"; import { TaskCard } from "./TaskCard"; +/** Your line to the worker once you picked its project from a card that asked. */ +export const PICKED_LINE = "I picked a project for you. File the task again."; + /** * The center: the worker's one conversation. A divider marks where the turns * the worker reads word for word begin. A message another worker sent that @@ -41,10 +44,11 @@ export function Conversation({ const workProject = useWatch(adapter.watchWorkProject, worker.id); // A job refused for want of a project waits on the pick, from its card or the header. const waiting = !workProject && tasks.some((t) => t.status === "needs-project"); - // The pick is stored on the worker, then said to it as your line, so it files the job again. + // The pick is stored on the worker, then said to it as your line, so it files the job again. The line + // doesn't name the project: the job is filed in the stored one, never in one the worker names. const pick = async (project: string) => { await adapter.setWorkProject(worker.id, project); - await adapter.send(sessionId, `Work in ${projects.find((p) => p.id === project)?.name ?? project}.`); + await adapter.send(sessionId, PICKED_LINE); }; const end = useRef(null); diff --git a/labs/teammates/src/components/Entry.tsx b/labs/teammates/src/components/Entry.tsx index 186888dbce..b9162f3128 100644 --- a/labs/teammates/src/components/Entry.tsx +++ b/labs/teammates/src/components/Entry.tsx @@ -44,7 +44,9 @@ export function Entry({ entry, workerName, nameOf }: { entry: ConversationEntry; case "result": return (
-
← {nameOf(entry.from)} · task done
+
+ ← {nameOf(entry.from)} · {entry.failed ? "task failed" : "task done"} +

{entry.text}

); diff --git a/labs/teammates/src/components/Runs.tsx b/labs/teammates/src/components/Runs.tsx index 157964ec2f..191e36e782 100644 --- a/labs/teammates/src/components/Runs.tsx +++ b/labs/teammates/src/components/Runs.tsx @@ -27,7 +27,7 @@ export function Runs({

{worker.name}

{worker.role} - takes tasks · {worker.harness} + takes tasks
diff --git a/labs/teammates/src/components/TaskCard.tsx b/labs/teammates/src/components/TaskCard.tsx index 50309405bf..361cfccdcf 100644 --- a/labs/teammates/src/components/TaskCard.tsx +++ b/labs/teammates/src/components/TaskCard.tsx @@ -40,8 +40,10 @@ export function TaskCard({ ? "refused · no project" : "needs a project" : task.status === "running" - ? `running in ${task.project}` - : `done in ${task.project}`; + ? task.project ? `running in ${task.project}` : "running" + : task.status === "failed" + ? "failed" + : `done in ${task.project}`; const asking = task.status === "needs-project" && !workProject && onPick; return (
0 ? `waiting on ${waiting.map(nameOf).join(", ")}` : activity - ? `idle · ${age(activity.lastActiveAt, now)}` + ? activity.lastActiveAt > 0 + ? `idle · ${age(activity.lastActiveAt, now)}` + : "idle" : ""; return (