Skip to content

FIX-2378: a task's line says which task it is, as data - #4485

Merged
jhoffner merged 3 commits into
mainfrom
claude/project-thread-j4sbyu
Nov 2, 2026
Merged

jhoffner merged 3 commits into
mainfrom
claude/project-thread-j4sbyu

Conversation

@jhoffner

@jhoffner jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator

Requested by Jake · project thread

Builds FIX-2378 to its merged spec, specs/issues/FIX-2378 (#4397). Wave 1 package slice of FIX-2369. It touches no app file; the labs adopt the readers in wave 3.

What changes

  • contracts / core / engine: MessageItem gains optional metadata, set through ctx.emit.message(text, { metadata }) on both message emitters. EmitMessageOptions is exported from core. The engine never reads it, and history holds the text alone. No task or worker noun enters L1 (ER-1).
  • orchestration: noticeMetadata(notice, task) and parseNotice(item) sit beside noticeText. parseNotice reads the data when present and falls back to the words for lines stored before this (BP-030, E1). Malformed data reads as "not a notice".
  • workforce: the board's notice line, a line a running turn took, and a routed failure's line carry noticeMetadata. A delegate's answer, from the board or the coordinator's two answer sites, carries delegateAnswerMetadata({ worker, taskId }). delegateAnswerOf(item) is exported from the root and ./browser. The keys stay internal (E7).
  • Docs: orchestration and workforce READMEs, docs/architecture/items.md, and the Emitting items page.
  • Changeset: patch for the five packages.

Verification

  • packages/workforce/test/task-line-markers.test.ts (6 tests, real engine): completion and final-failure lines carry taskNotice with the filed task's id and ending. Answers from a coordinator, a worker's own conversation, and a routed message read as { worker, taskId }.
    • Negative control, run while prototyping: dropping the marker at each emit site fails the matching legs (notice line → both ending legs; coordinator → routed and unrouted legs; board answer line → worker-conversation leg).
  • packages/orchestration/test/tasks/parse-notice.test.ts (16 tests): every ending round-trips, a reworded line still parses from its data, and the text fallback is checked against noticeText's own output, cascade included. A user quoting a notice, another item type, and malformed data are rejected.
  • packages/engine/test/emit-message-metadata.test.ts (2 tests): metadata rides both the streamed and the stored item, is absent when not given, and never reaches itemToLLMMessages. Control: the engine drops the field and the test fails.
  • Suites on this branch: contracts 95, core 2613, engine 4224 (+8 skipped), orchestration 2213, workforce 1727/1728.
    • The one workforce red is coordinator-rounds.test.ts hitting its 5s timeout under full-suite load; it passes on its own (39/39 with the markers test).
  • Typecheck is clean for contracts, core, engine and orchestration. Workforce shows the same 11 errors on clean main, so they come from main.

Generated by Claude Code

…ge items

A conversation's line about a task now carries its data on the item, so an
app reads the task, its ending and what came back without parsing the words.

- contracts/core/engine: optional `metadata` on MessageItem, set through
  `ctx.emit.message(text, { metadata })`; never sent to a model.
- orchestration: `noticeMetadata` and `parseNotice` beside `noticeText`, with
  a text fallback for lines stored before this (BP-030).
- workforce: every task line and delegate answer is marked;
  `delegateAnswerOf` reads the answer marker (root and ./browser).

Spec: specs/issues/FIX-2378 (#4397).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGDvDM4uyuL6R8WL5Q
@jhoffner jhoffner self-assigned this Nov 1, 2026
@linear-code

linear-code Bot commented Nov 1, 2026

Copy link
Copy Markdown

FIX-2378

@vercel

vercel Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
flow-state-dev-build-site Ready Ready Preview Nov 1, 2026 9:30pm UTC
3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Nov 1, 2026 9:30pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Nov 1, 2026 9:30pm UTC
flow-state-dev-ui Ignored Ignored Preview Nov 1, 2026 9:30pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 1, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-01T21:26:20.253083Z 62a82c7 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Nov 1, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass

Overall: the shape is right. A generic opaque metadata on MessageItem (precedent: ContainerItem.metadata) keeps task/worker nouns out of L1, the readers live beside the emitters, and the text fallback (BP-030) is tested against noticeText's own output. I'd ship this approach; I couldn't find a leaner one that still keeps the engine task-agnostic. Findings below, most important first. None block the direction.

1. resultLine can mark an answer as a notice (correctness, small)

packages/workforce/src/conversation-board/task-settled.ts (resultLine): when answer !== undefined but row.assignee === undefined, the fall-through returns text: answer with metadata: noticeMetadata(notice, row). The line's words are the delegate's reply, but parseNotice reads it as a completed notice. Before this PR that case was just text. Either mark it with the notice only when answer === undefined, or carry no metadata in that branch. A one-line test (conversation-result task with no assignee) would pin it.

2. Routed-failure line carries a notice but isn't noticeText's words

task-settled.ts (routed branch, ~L296–305): when !byTurn, text is "<worker> couldn't answer: …", yet metadata is noticeMetadata(notice, row). parseNotice will return an errored notice whose title is the user's message (the comment above says "a policy's task is the user's message"). That is probably the intended semantic ("this task ended in failure"), but it's the one place the data and the words disagree, and title there isn't a task title. Worth a sentence in the test or the NoticeLine.title doc, or pass a real title.

3. Two readers for one idea (architecture)

A client drawing a conversation's task lines must now call parseNotice (orchestration) and delegateAnswerOf (workforce, a different package, a different import path), and must know which one applies. Both answer "what task-related line is this item?". Suggest wave 3 either (a) adds a single taskLineOf(item) in workforce that returns { kind: "notice", … } | { kind: "answer", … } | undefined, or (b) states in the README that these are the only two and shows the combined read. Not needed for this PR if wave 3 apps are the first consumers, but better decided before two apps hand-roll the pairing.

4. noticeMetadata and noticeText derive detail separately (refactor opportunity within the PR)

noticeMetadata re-implements the completed/cancelled/errored branching that noticeText already has (summary(output) vs error ?? "no error was recorded" vs none), and lineFromText is a third copy of the same grammar. The PR's tests do guard drift, which is good, but a small shared detailOf(notice) used by both writers would remove one place where "what came back" can diverge. noticeText's named/worker formatting would stay as is. Optional, ~5 lines.

5. detail is a truncated string, so it's "data" only in name

For a completion, detail is summary(output), the SUMMARY_LIMIT-truncated JSON.stringify. A client that wants the structured output can't get it from taskNotice; it gets the same lossy text twice (content + metadata). That's the right call for BP-042 (no unbounded payload on a recorded item), but the docs/NoticeLine.detail comment should say "truncated summary, not the output" so wave-3 doesn't build on it expecting the object.

6. Smaller notes

  • lineOf silently drops a non-numeric attempt / non-string detail rather than rejecting. Fine for tolerance; just noting it differs from the "malformed → not a notice" rule for taskId/title/ending.
  • delegateAnswerOf is exported from both workforce root and ./browser, and delegate-answer.ts is a leaf with no Node imports, so the browser boundary holds. The README sentence listing browser exports is now very long; consider splitting it into a list when polish-docs runs.
  • emit-message-metadata.test.ts reaches into stores.request.list({ withItems: true }) and casts to { items?: MessageItem[] }. If there is an existing helper for "items stored for a run" in engine tests, prefer it; otherwise fine.
  • Test coverage gap: nothing exercises metadata surviving the client/react item merge path (useSession). The engine test proves wire + store; the first wave-3 consumer will be the first to prove the client doesn't strip it. A single client stream-reduce test would close that cheaply.
  • Typecheck note in the description (11 errors in workforce on main) is pre-existing and not touched here.

Not recommending

  • Moving the marker into OutputItemBase or a typed taskNotice field on MessageItem: would put a task noun in L1 (ER-1).
  • Deriving "is this a delegate answer" from agentName: the PR correctly rejects that.

Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6c4a3b379e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +768 to +771
const marked = item.metadata?.[NOTICE_ITEM_KEY];
if (marked !== undefined) return lineOf(marked);
const text = (item.content ?? []).map((part) => part.text ?? "").join("");
return lineFromText(text);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Restrict legacy text parsing to unmarked messages

When a delegate's answer quotes a complete notice sentence, parseNotice treats it as a notice even though its metadata explicitly identifies it as a delegate answer. For example, an answer marked { delegateAnswer: { worker: "otto", taskId: "task_new" } } with text Task "Count licenses" (task_old) completed by otto: 12 licenses returns a completion notice for task_old. This makes the two readers classify the same new message differently and can associate the answer with the wrong task, contrary to FIX-2378's requirement that delegate answers return undefined from parseNotice. Limit the legacy fallback to messages without structured classification data rather than all messages lacking taskNotice.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed and fixed in 62a82c7. The spec's E1 says a line that has data is never read off its words, but the fallback only checked for a missing taskNotice key. parseNotice now falls back to the text only for a message with no metadata at all.

A new test covers your case: a delegateAnswer-marked line quoting a task_old notice. It fails without the fix and passes with it. Orchestration 2214/2214 and the workforce markers test (6/6) both pass.


Generated by Claude Code

@github-actions

github-actions Bot commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Mechanism check (advisory, never blocks)

Rows from docs/mechanisms/mechanisms.yaml · labels: none

New export Package Mechanism
noticeMetadata @flow-state-dev/orchestration task-notice
parseNotice @flow-state-dev/orchestration task-notice
delegateAnswerMetadata @flow-state-dev/workforce session-board
delegateAnswerOf @flow-state-dev/workforce session-board

A line that carries any metadata says what it is, so the legacy text
fallback now applies only to a line with no metadata at all. A delegate's
answer quoting an older notice no longer reads as that notice (Codex review).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGDvDM4uyuL6R8WL5Q
… in the changeset

DELEGATE_ANSWER_KEY was exported from its module with no consumer (Fallow);
the key stays internal per the spec's E7. The changeset now names FIX-2378.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NczDiGDvDM4uyuL6R8WL5Q
@jhoffner
jhoffner added this pull request to the merge queue Nov 2, 2026
Merged via the queue into main with commit 9634cdb Nov 2, 2026
20 checks passed
@jhoffner
jhoffner deleted the claude/project-thread-j4sbyu branch November 2, 2026 22:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants