Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 23 additions & 7 deletions labs/teammates/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ the workforce package. It is one half of the evidence that the same package piec
apps: an app adds only configuration, React UI and a few small flows, and anything else it needs is
a gap filed against the package.

- **Left:** the workers, lead, researcher and writer. Each row is a worker with an ongoing role,
never a list of sessions. A row shows what the worker is doing and how many new entries its
- **Left:** the workers, lead, researcher, writer and coder. Each row is a worker with an ongoing
role, never a list of sessions. A row shows what the worker is doing and how many new entries its
conversation has since you last looked.
- **Center:** the chosen worker's one conversation. It goes on for weeks. A divider marks where the
turns the worker reads word for word begin; it reads *summarized* only when the earlier turns were
Expand All @@ -19,6 +19,13 @@ shows in lead's conversation and the message lands in researcher's. The reply la
conversation under researcher's name. A message never interrupts the turn you are in: while lead is
answering you, researcher's reply shows as a pending line, and lead reads it right after.

coder is different: it takes tasks only, so it has no conversation and you can't message it. Ask
lead for a code change and lead files a task for coder, which runs it through Claude Code in lead's
project. A card in lead's conversation shows the task and opens to its run, and the result lands
as a line from coder. Talking to a worker never needs a project. The first time a job needs files,
the card asks you to pick one for lead; nothing runs until you do, and the pick sticks to lead.
Picking one from the header works too.

Scope is core messaging and session management. There are no group chats, no new-chat button and
no session list. The design and the decisions behind it are in the
[spec](../../specs/issues/FIX-2154/SPEC.md).
Expand All @@ -36,14 +43,20 @@ lead answers and messages researcher. Before researcher replies, send lead a sec
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.

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.
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.

## Fixtures

Expand All @@ -57,6 +70,9 @@ names the package call it stands for, and until wiring they run on `src/fixtures
| 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 |

## What this app adds

Expand All @@ -66,9 +82,9 @@ and on a flow over 200 lines; `--wired` also fails while a fixture is left.
<!-- inventory:start -->
| Kind | Files | Lines |
|---|---:|---:|
| Configuration | 13 | 253 |
| React UI | 14 | 822 |
| Configuration | 14 | 279 |
| React UI | 16 | 1108 |
| Small flows | 0 | 0 |
| Fixtures (deleted at wiring) | 1 | 267 |
| Checks (not app code) | 3 | 275 |
| Fixtures (deleted at wiring) | 1 | 353 |
| Checks (not app code) | 3 | 340 |
<!-- inventory:end -->
22 changes: 15 additions & 7 deletions labs/teammates/src/App.tsx
Original file line number Diff line number Diff line change
@@ -1,28 +1,33 @@
import { useEffect, useState } from "react";
import type { LabAdapter, WorkerRow } from "./adapter";
import type { LabAdapter, ProjectRow, WorkerRow } from "./adapter";
import { Conversation } from "./components/Conversation";
import { Runs } from "./components/Runs";
import { TalkPanel } from "./components/TalkPanel";
import { WorkersList } from "./components/WorkersList";

/**
* The screen: the workers on the left, the chosen worker's one conversation
* in the center, and its talk with the other workers on the right. The app
* opens on the first worker on the roster.
* in the center, and its talk with the other workers on the right. A worker
* that takes tasks only has no conversation; the center shows its runs. The
* app opens on the first worker on the roster.
*/
export function App({ adapter }: { adapter: LabAdapter }) {
const [workers, setWorkers] = useState<WorkerRow[]>([]);
const [projects, setProjects] = useState<ProjectRow[]>([]);
const [sessions, setSessions] = useState<Record<string, string>>({});
const [selected, setSelected] = useState<string>();
const [talkOpen, setTalkOpen] = useState(true);

useEffect(() => {
let live = true;
void (async () => {
const roster = await adapter.listWorkers();
const ids = await Promise.all(roster.map((w) => adapter.openConversation(w.id)));
const [roster, projectRows] = await Promise.all([adapter.listWorkers(), adapter.listProjects()]);
const talking = roster.filter((w) => !w.takesTasks);
const ids = await Promise.all(talking.map((w) => adapter.openConversation(w.id)));
if (!live) return;
setWorkers(roster);
setSessions(Object.fromEntries(roster.map((w, i) => [w.id, ids[i]])));
setProjects(projectRows);
setSessions(Object.fromEntries(talking.map((w, i) => [w.id, ids[i]])));
setSelected((current) => current ?? roster[0]?.id);
})();
return () => {
Expand All @@ -39,11 +44,14 @@ export function App({ adapter }: { adapter: LabAdapter }) {
style={{ gridTemplateColumns: talkOpen ? "15rem minmax(0,1fr) 18rem" : "15rem minmax(0,1fr)" }}
>
<WorkersList adapter={adapter} workers={workers} sessions={sessions} selected={selected} nameOf={nameOf} onSelect={setSelected} />
{worker && sessionId ? (
{worker?.takesTasks ? (
<Runs adapter={adapter} worker={worker} workers={workers} sessions={sessions} projects={projects} nameOf={nameOf} />
) : worker && sessionId ? (
<Conversation
adapter={adapter}
worker={worker}
sessionId={sessionId}
projects={projects}
nameOf={nameOf}
talkOpen={talkOpen}
onToggleTalk={() => setTalkOpen((open) => !open)}
Expand Down
51 changes: 50 additions & 1 deletion labs/teammates/src/adapter.ts
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@
* | `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`) |
*/
import { createFixtureLab } from "./fixtures";

Expand All @@ -30,6 +35,38 @@ export interface WorkerRow {
name: string;
/** Its `WORKER.md` description: the ongoing role. */
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. */
export interface ProjectRow {
id: string;
name: string;
}

/**
* A task a conversation filed for a worker that takes tasks, from the board's
* row. `needs-project` is a run refused `no-project` before any file existed.
*/
export interface BoardTask {
id: string;
/** The worker it was filed for. */
to: string;
title: string;
status: "needs-project" | "running" | "done";
/** The project its run works in; none when it was refused. */
project?: string;
/** What the run reported when it ended. */
result?: string;
}

/** One step of a task's run, as the harness reported it. */
export interface RunStep {
id: string;
text: string;
}

/** One entry of a worker's conversation, in the order it happened. */
Expand All @@ -39,7 +76,11 @@ export type ConversationEntry =
/** The worker messaged another worker (`sendMessage`). */
| { kind: "sent"; id: string; messageId: string; to: string; text: string }
/** A message another worker sent, as the `receive` turn that read it. */
| { kind: "received"; id: string; messageId: string; from: string; text: string; inReplyTo?: string };
| { kind: "received"; id: string; messageId: string; from: string; text: string; inReplyTo?: string }
/** 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 };

/** What a conversation shows now. */
export interface ConversationView {
Expand Down Expand Up @@ -88,6 +129,14 @@ export interface LabAdapter {
watchActivity(worker: string, onChange: (activity: Activity) => void): Unsubscribe;
/** `undefined` while the whole conversation is inside the window. */
watchWindow(sessionId: string, onChange: (mark: WindowMark | undefined) => void): Unsubscribe;
listProjects(): Promise<ProjectRow[]>;
/** The project `worker`'s runs work in; `undefined` until one is picked. */
watchWorkProject(worker: string, onChange: (project: string | undefined) => void): Unsubscribe;
setWorkProject(worker: string, project: string): Promise<void>;
/** The tasks a conversation filed, oldest first. */
watchTasks(sessionId: string, onChange: (tasks: BoardTask[]) => void): Unsubscribe;
/** A task's run, read only: the worker that runs it takes no messages. */
watchRun(taskId: string, onChange: (steps: RunStep[]) => void): Unsubscribe;
}

/** The adapter the app runs on. */
Expand Down
46 changes: 43 additions & 3 deletions labs/teammates/src/components/Conversation.tsx
Original file line number Diff line number Diff line change
@@ -1,27 +1,32 @@
import { Fragment, useEffect, useRef } from "react";
import type { LabAdapter, WorkerRow } from "../adapter";
import type { LabAdapter, ProjectRow, WorkerRow } from "../adapter";
import { pendingFor } from "../lib/talk";
import { useWatch } from "../lib/use-watch";
import { cn } from "../lib/utils";
import { Composer } from "./Composer";
import { Entry } from "./Entry";
import { TaskCard } from "./TaskCard";

/**
* 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
* waits for the current answer shows as a pending line until it lands.
* waits for the current answer shows as a pending line until it lands. The
* header carries the worker's project: none is needed to talk, and the first
* job that needs files asks for one on its task card.
*/
export function Conversation({
adapter,
worker,
sessionId,
projects,
nameOf,
talkOpen,
onToggleTalk,
}: {
adapter: LabAdapter;
worker: WorkerRow;
sessionId: string;
projects: ProjectRow[];
nameOf: (id: string) => string;
talkOpen: boolean;
onToggleTalk: () => void;
Expand All @@ -32,18 +37,49 @@ export function Conversation({
const entries = view?.entries ?? [];
const running = view?.running ?? false;
const pending = pendingFor(worker.id, talk, entries);
const tasks = useWatch(adapter.watchTasks, sessionId) ?? [];
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.
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}.`);
};

const end = useRef<HTMLDivElement>(null);
useEffect(() => {
end.current?.scrollIntoView?.({ block: "end" });
}, [entries.length, running, pending.length, sessionId]);

// A card shows once the board's row has arrived.
const taskTile = (taskId: string) => {
const task = tasks.find((t) => t.id === taskId);
if (!task) return null;
return <TaskCard adapter={adapter} task={task} filer={worker.name} workProject={workProject} projects={projects} nameOf={nameOf} onPick={(p) => void pick(p)} />;
};

const markAt = mark ? entries.findIndex((e) => e.id === mark.firstVerbatimEntryId) : -1;
return (
<main aria-label="Conversation" className="flex h-full min-h-0 min-w-0 flex-col">
<header className="flex items-center gap-3 border-b border-border px-6 py-3">
<h1 className="text-sm font-semibold">{worker.name}</h1>
<span className="min-w-0 flex-1 truncate text-xs text-muted-foreground">{worker.role}</span>
<select
aria-label={`Project for ${worker.name}`}
value={workProject ?? ""}
onChange={(e) => void (waiting ? pick(e.target.value) : adapter.setWorkProject(worker.id, e.target.value))}
className="border border-border bg-card px-1 py-0.5 font-mono text-[10px] tracking-widest uppercase"
>
<option value="" disabled>
no project
</option>
{projects.map((p) => (
<option key={p.id} value={p.id}>
in · {p.name}
</option>
))}
</select>
{running ? (
<span className="flex items-center gap-1.5 font-mono text-[10px] tracking-widest text-info uppercase">
<span className="size-2 animate-pulse rounded-full bg-info" /> working
Expand Down Expand Up @@ -75,7 +111,11 @@ export function Conversation({
</div>
) : null}
<div className={cn(i < markAt && "opacity-60")} data-in-window={markAt < 0 || i >= markAt ? "true" : "false"}>
<Entry entry={entry} workerName={worker.name} nameOf={nameOf} />
{entry.kind === "task" ? (
taskTile(entry.taskId)
) : (
<Entry entry={entry} workerName={worker.name} nameOf={nameOf} />
)}
</div>
</Fragment>
))}
Expand Down
14 changes: 12 additions & 2 deletions labs/teammates/src/components/Entry.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@ import { cn } from "../lib/utils";
/**
* One entry of a conversation. Your lines sit on the right; the worker's
* answers on the left. A message the worker sent another worker is a one-line
* card that opens to its full text; a message it received lands under the
* sender's name.
* card that opens to its full text; a message it received, or a task it
* filed coming back, lands under the sender's name.
*/
export function Entry({ entry, workerName, nameOf }: { entry: ConversationEntry; workerName: string; nameOf: (id: string) => string }) {
switch (entry.kind) {
Expand Down Expand Up @@ -41,6 +41,16 @@ export function Entry({ entry, workerName, nameOf }: { entry: ConversationEntry;
<p className="mt-0.5 text-sm whitespace-pre-wrap">{entry.text}</p>
</section>
);
case "result":
return (
<section aria-label={`From ${nameOf(entry.from)}`} data-entry="result" className="max-w-[85%] rounded-md border border-dashed border-success/60 bg-success/5 px-3 py-2">
<div className="font-mono text-[10px] tracking-widest text-success uppercase">← {nameOf(entry.from)} · task done</div>
<p className="mt-0.5 text-sm whitespace-pre-wrap">{entry.text}</p>
</section>
);
case "task":
// Drawn by the conversation, from the board's row.
return null;
}
}

Expand Down
Loading
Loading