From d6284232b64593e39602e5ab6cfe149a8eba037e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 00:10:10 +0000 Subject: [PATCH 01/28] fix(goals): read the DevForce channel's skip list off CHANNEL.md (FIX-1756) it-ships-an-artifact-a-person-can-open expected the channel post to skip exactly [eng.coder, eng.reviewer], a list typed into the check. Since FIX-1719 seated the chief of staff in DevTeam's channel, the fan-out correctly skips it too, and the check has been red on main. The expected skips are now every member CHANNEL.md declares except the EM, read off the lab's roster. The check also fails if the tree stops declaring the coder or the reviewer, so the claim can't hold vacuously. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .../goal.md | 6 ++-- .../run.mts | 33 ++++++++++++++----- goals/devforce-lab/lab/notify.mts | 4 +-- 3 files changed, 31 insertions(+), 12 deletions(-) diff --git a/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md b/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md index b06ccbef79..e83e96255c 100644 --- a/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md +++ b/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md @@ -23,8 +23,9 @@ convention file and in none of the lab's own code, before the run starts. **Signal:** 1. Before anybody posts, the board carries no row. After one post, the line is in the channel's - transcript, the fan-out addressed the EM seat and recorded the other two declared members as - skipped, and exactly one row exists. + transcript, the fan-out addressed the EM seat and recorded every other member `CHANNEL.md` + declares as skipped (read off the tree, which must still declare the coder and the reviewer), + and exactly one row exists. 2. The board's dispatch record names the coder seat and never the reviewer seat, by `flowId`. 3. The prompt the manager handed the agent carries all four held-out tokens. 4. Exactly one branch under `conductor/` resolves at the published address **after** the store is @@ -167,3 +168,4 @@ own verdict log, which re-proves BR-10 and BR-17. **Re-run on `origin/main` at ` while the same read with an org lands"*. The paragraph above is kept as history. | 2026-09-30 | a1b122eb1 | n/a | PASS | Local leg. Row read back in a fresh process from the organization's storage under the channel's board id; the transcript count reads channel-post items. The published branch carries `eng.feature.work`. | | 2026-10-01 | a25134ebd+wip (FIX-1691/1692) | Claude Code (Agent SDK) | PASS | Local leg. 19 lab TypeScript files classified, `harness.mts` among them. | +| 2026-10-04 | d5225ecd8+FIX-1756 | Claude Code (Agent SDK) | PASS | Local leg. The skip list is read off `CHANNEL.md`: 3 declared members seen and skipped (`chief-of-staff`, `eng.coder`, `eng.reviewer`). All nine controls red. Red on `d5225ecd8` before the change: *the fan-out skipped [chief-of-staff, eng.coder, eng.reviewer]; wanted [eng.coder, eng.reviewer]*. | diff --git a/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/run.mts b/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/run.mts index ebd4fc0f4f..7fc28b0995 100644 --- a/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/run.mts +++ b/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/run.mts @@ -112,8 +112,18 @@ const ASSIGNED_SEAT = "eng.coder"; const COORDINATOR_SEAT = "eng.em"; /** Declared on the channel, hired into the same kind as the coder, and never given work. */ const REVIEWER_SEAT = "eng.reviewer"; -/** Every member `CHANNEL.md` declares, in the order the fan-out walks them. */ -const DECLARED_MEMBERS = [COORDINATOR_SEAT, ASSIGNED_SEAT, REVIEWER_SEAT]; +/** + * The members this check's claim names. The channel's full member list is read + * off `CHANNEL.md` at run time (`declaredMembers`), not restated here: a list + * this check typed out goes stale the moment the tree seats someone else. + */ +const CLAIMED_MEMBERS = [COORDINATOR_SEAT, ASSIGNED_SEAT, REVIEWER_SEAT]; + +/** Every member the lab's channel declares in `CHANNEL.md`, as the lab read it. */ +function declaredMembers(lab: Lab): string[] { + const channel = lab.roster.channels.find((c) => c.id === lab.channelId); + return (channel?.declared.members as string[] | undefined) ?? []; +} /** The feature, and the line an operator posts to ask for it. */ const ISSUE = "greeting-module"; @@ -743,9 +753,8 @@ await runGoal(async () => { coderSeatId: ASSIGNED_SEAT, runTimeoutMs: RUN_TIMEOUT_MS, logger: silentLogger, - // Only the EM is addressed. The coder and the reviewer are declared members - // of the channel and are true no-ops in the fan-out — recorded and skipped, - // never dispatched to. + // Only the EM is addressed. Every other declared member of the channel is a + // true no-op in the fan-out — recorded and skipped, never dispatched to. channels: { addresses: { [COORDINATOR_SEAT]: COORDINATOR_SEAT }, log: notifyLog }, harness: ({ cwd, resume, onSession }) => sequencer({ @@ -829,10 +838,18 @@ await runGoal(async () => { } if (failures.length > 0) return { failures, evidence: "" }; - // BR-8's positive half: exactly the EM was addressed, and the other two - // declared members were seen and skipped. Not an absence — a record. + // BR-8's positive half: exactly the EM was addressed, and every other + // declared member was seen and skipped. Not an absence — a record. + const declared = declaredMembers(lab); + const unseated = CLAIMED_MEMBERS.filter((m) => !declared.includes(m)); + if (unseated.length > 0) { + failures.push( + `the channel declares [${declared.join(", ")}], without [${unseated.join(", ")}] — ` + + `the claim is about those seats, so it would hold vacuously`, + ); + } const skipped = [...notifyLog.skipped].sort(); - const expectedSkips = DECLARED_MEMBERS.filter((m) => m !== COORDINATOR_SEAT).sort(); + const expectedSkips = declared.filter((m) => m !== COORDINATOR_SEAT).sort(); if (notifyLog.addressed.join(",") !== COORDINATOR_SEAT) { failures.push( `the fan-out addressed [${notifyLog.addressed.join(", ")}]; wanted only ${COORDINATOR_SEAT}`, diff --git a/goals/devforce-lab/lab/notify.mts b/goals/devforce-lab/lab/notify.mts index c53c83e551..c18f7226cc 100644 --- a/goals/devforce-lab/lab/notify.mts +++ b/goals/devforce-lab/lab/notify.mts @@ -30,8 +30,8 @@ * poster, not after. That is a fact about those seats, not about this file. * * The one rule is how BR-8 is satisfied rather than asserted. `CHANNEL.md` declares - * three members; only the EM is in the address map, so the coder and the - * reviewer are true no-ops in the fan-out — not "dispatched to a block that + * the EM, the coder, the reviewer and the chief of staff; only the EM is in the + * address map, so every other member is a true no-op in the fan-out — not "dispatched to a block that * happens to do nothing", but never dispatched to at all, with the skip * recorded so the check grades a fact rather than an absence. * From 5f1fd5075bda79ac04d47249d6860eef2d886126 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 00:19:27 +0000 Subject: [PATCH 02/28] fix(workforce): hire under any org id by escaping it into the seat address (FIX-1757) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A hired seat's address is `.`, and `seatAddress` refused any org id that wasn't a lowercase-hyphen segment. That refused the framework's own default org and the `org_…` ids auth providers hand out, so a chief of staff on such a Lab could never hire. The org is now escaped with the same encoding as the user segment (`encodeUserSegment`), which keeps the join injective and is the identity on ids that were already legal, so existing addresses don't move. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- apps/kitchen-sink/components/seat-pane.tsx | 7 ++- .../goal.md | 5 +- .../run.mts | 18 ++++-- packages/workforce/src/browser.ts | 2 +- packages/workforce/src/loader/segments.ts | 30 +--------- packages/workforce/src/roster/address.ts | 53 +++++++++++------ packages/workforce/test/roster-check.test.ts | 7 ++- packages/workforce/test/roster.test.ts | 58 ++++++++++--------- .../workforce/test/seat-hire-blocks.test.ts | 37 +++++++++++- 9 files changed, 128 insertions(+), 89 deletions(-) diff --git a/apps/kitchen-sink/components/seat-pane.tsx b/apps/kitchen-sink/components/seat-pane.tsx index 4b3426a1bf..23613d9384 100644 --- a/apps/kitchen-sink/components/seat-pane.tsx +++ b/apps/kitchen-sink/components/seat-pane.tsx @@ -17,7 +17,7 @@ * shell carries by address (`SEAT_DESCRIPTIONS`). A seat with none draws none. */ import { SeatDetail, type PanelItemSource } from "@flow-state-dev/react"; -import { HIRED_ROSTER_RESOURCE, splitSeatAddress } from "@flow-state-dev/workforce/browser"; +import { HIRED_ROSTER_RESOURCE, seatAddress, splitSeatAddress } from "@flow-state-dev/workforce/browser"; import { SEAT_DESCRIPTIONS } from "@/lib/workforce-shell"; @@ -36,8 +36,9 @@ export interface SeatPaneProps { /** The roster topic of a seat hired into the whole organization; `undefined` for any other seat. */ function publicRosterTopic(orgId: string, address: string): string | undefined { - if (address.startsWith(`${orgId}.~`)) return undefined; - return splitSeatAddress(orgId, address); + const seatId = splitSeatAddress(orgId, address); + // A user-owned address splits to its seat id too; only the org-visible one rebuilds to itself. + return seatId !== undefined && seatAddress(orgId, seatId) === address ? seatId : undefined; } export function SeatPane({ sessionId, orgId, kind, address, resourceClient }: SeatPaneProps) { diff --git a/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md b/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md index a9a5563d73..1fa205d2ce 100644 --- a/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md +++ b/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md @@ -1,12 +1,12 @@ # hire-plane › reload survives an unaddressable row **Issue:** FIX-1536 -**Outcome:** An app with no authentication that hires a seat at runtime does not take the rest of the roster down at the next boot. That hire lands under the development organization, whose id cannot be a seat address, so it can never come back as a seat. It comes back as one named problem, and every other organization's seats still reload, register and answer. A row stamped for a different organization is still refused, not minted. +**Outcome:** An app with no authentication that hires a seat at runtime does not take the rest of the roster down at the next boot. That hire lands under the development organization, and comes back as a seat at that organization's escaped address (FIX-1757; before it, the id could not be an address and the row came back as one named problem). Every other organization's seats still reload, register and answer. A row stamped for a different organization is still refused, not minted. **Input:** `fixtures/input.json` — the signed-in org and user, the dev user, the two seat ids, the stray org and seat id, and a marker. Held-out: every id is read from the fixture and graded against the reload result and a real run on the reloaded seat. Swapping any of them must still pass. **Signal:** against `createFlowState`'s HTTP router, one in-memory store shared by three app instances (dev, signed-in, restarted), no model. (a) The dev app's `hire` action, run with no identity, completes and leaves a roster row under `DEFAULT_ORG_ID`. (b) The signed-in app's `hire` action completes for the named org. -(c) `reloadHiredSeats` over `[DEFAULT_ORG_ID, ]` resolves. It returns `.`, names the dev row by org and key in `problems`, and the returned seat registers on the restarted app and completes an `answer` run. +(c) `reloadHiredSeats` over `[DEFAULT_ORG_ID, ]` resolves. It returns `.` and the dev row at `seatAddress(DEFAULT_ORG_ID, )`, names no default-org problem, and the named seat registers on the restarted app and completes an `answer` run. (d) A row in the named org's cell stamped `owningOrgId: ` is a `cannot be registered under` problem, and no seat with its id is returned. **Anti-game:** a hollow pass would check that `problems` is non-empty, which holds when reload names both bad rows and returns nothing else. So the check MUST see the named org's seat come back and answer a real run after the restart, MUST see the dev row named by its org and key, and MUST see the stray row refused rather than minted. It must not grade the address string alone. @@ -20,3 +20,4 @@ |------|--------|-------|---------|-------| | 2026-09-23 | `636542bc6` with `reload.ts` reverted to `ffe2b6e26`, then restored | n/a | FAIL (expected) | **Leg (c) only:** `reload rejected, so no org's seats came back: Organization id "__fsd_default_org__" must be lowercase letters, digits, and single hyphens ...`. Legs (a) and (b) completed, so the dev hire really does write under the default org through the HTTP path. Restored with `git checkout HEAD -- packages/workforce/src/roster/reload.ts` and rebuilt. | | 2026-09-23 | `636542bc6` (fix present) | n/a | PASS | Exit 0. Dev hire stored under `__fsd_default_org__`; reload over `[__fsd_default_org__, acme]` returned `["acme.support.ada"]` and 2 problems; `acme.support.ada` answered after restart; default-org row named as `organization "__fsd_default_org__", row "workforce/roster/lead"`; stray row refused as `owned by organization "globex" and cannot be registered under "acme"`. | +| 2026-10-04 | `d5225ecd8` + FIX-1757 (org escaped into the address) | n/a | PASS | Leg (c) re-pointed: the default org is now addressable. Reload returned `["%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead","acme.support.ada"]` and 1 problem (the stray row, refused as before); `acme.support.ada` answered after restart. | diff --git a/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts b/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts index b7033606d5..3953b6279e 100644 --- a/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts +++ b/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts @@ -16,6 +16,7 @@ import { createFlowState, inMemoryStores } from "@flow-state-dev/engine"; import { defineHiredRosterCollection, reloadHiredSeats, + seatAddress, toHiredSeatRow, workerConfigSchema, } from "@flow-state-dev/workforce"; @@ -226,11 +227,16 @@ await runGoal(async () => { if (reload !== undefined) { const ids = reload.seats.map((seat) => seat.id); if (!ids.includes(namedAddress)) fail("c", `reload did not return ${namedAddress}; got ${JSON.stringify(ids)}`); - const devProblem = reload.problems.find( - (problem) => problem.includes(DEFAULT_ORG_ID) && problem.includes(fixture.devSeatId), - ); - if (devProblem === undefined) { - fail("c", `the default-org row was not named in problems: ${JSON.stringify(reload.problems)}`); + // The dev hire comes back as a seat: the default org is escaped into its + // address rather than refused. + const devAddress = seatAddress(DEFAULT_ORG_ID, fixture.devSeatId); + const devProblem = reload.problems.find((problem) => problem.includes(DEFAULT_ORG_ID)); + if (!ids.includes(devAddress) || devProblem !== undefined) { + fail( + "c", + `the default-org row did not come back as ${devAddress}: ${JSON.stringify(ids)}, ` + + `problems ${JSON.stringify(reload.problems)}`, + ); } const strayProblem = reload.problems.find((problem) => problem.includes(fixture.strayOrg)); if (strayProblem === undefined || !strayProblem.includes("cannot be registered under")) { @@ -263,7 +269,7 @@ await runGoal(async () => { evidence: `dev hire stored under ${DEFAULT_ORG_ID}; reload over [${DEFAULT_ORG_ID}, ${fixture.namedOrg}] ` + `returned ${JSON.stringify(ids)} and ${reload.problems.length} problems; ` + - `${namedAddress} answered after restart; default-org row named: ${devProblem}; ` + + `${namedAddress} answered after restart; default-org row came back as ${devAddress}; ` + `stray row refused: ${strayProblem}`, }; } diff --git a/packages/workforce/src/browser.ts b/packages/workforce/src/browser.ts index 85fddf7586..2f8ed07f4b 100644 --- a/packages/workforce/src/browser.ts +++ b/packages/workforce/src/browser.ts @@ -17,7 +17,7 @@ export { HIRED_ROSTER_RESOURCE, SEAT_INVENTORY_RESOURCE } from "./seat-hire-keys"; -export { splitSeatAddress } from "./roster/address"; +export { seatAddress, splitSeatAddress } from "./roster/address"; export { isHiredSeatRow, listedSeatRows } from "./inventory/listed-seats"; export { CHANNEL_POST_COMPONENT, diff --git a/packages/workforce/src/loader/segments.ts b/packages/workforce/src/loader/segments.ts index f5b8e9cdba..4718af05e6 100644 --- a/packages/workforce/src/loader/segments.ts +++ b/packages/workforce/src/loader/segments.ts @@ -12,14 +12,6 @@ * root. A segment reaches these readers from an argument as well as from a * walk, and `..` in one would read a folder the caller never configured — the * same escape the walk's symlink refusal exists to stop. - * - * This module is on the `@flow-state-dev/workforce/browser` graph (through - * `roster/address.ts`), so it must stay free of Node built-ins. Its one import - * is the `@flow-state-dev/core/helpers` barrel, which is pure today — but that - * is a property of the whole barrel, not of the one helper taken from it. The - * guarantee is `test/browser-subpath-safe.test.ts`, which walks this graph - * into workspace packages and fails on any Node built-in it reaches; do not - * rely on this comment instead. */ import { isWindowsReservedName } from "@flow-state-dev/core/helpers"; @@ -63,17 +55,6 @@ const RESERVED_SEGMENTS = new Set(["_meta"]); * `Package` is a folder under a `packages/` slot. Its name is what a worker's * `packages:` line takes it by and half of the address its blocks are * registered under, so it obeys the rule every other name does. - * - * `Org` is the one label that names **nothing on disk**. It is the leading - * segment of a runtime-hired seat's address (`.`), and it is - * here rather than in a rule of its own because the `.` exclusion below is - * precisely what that address needs: org `acme` with seat `support.ada` and - * org `acme.support` with seat `ada` both spell `acme.support.ada`, so - * admitting a dotted org would make the join non-injective and one seat would - * silently answer at the other's address. Sharing the rule does mean an org - * inherits two constraints it has no need of — the reserved folder name and - * the Windows device names — which costs a handful of unusable org ids and - * buys one rule instead of two that can drift. */ export type SegmentLabel = | "Team" @@ -82,7 +63,6 @@ export type SegmentLabel = | "Document" | "Kind" | "Block" - | "Org" | "Package"; /** @@ -93,11 +73,7 @@ const FILE_LABELS: ReadonlySet = new Set(["Document" /** Validate one path segment against the naming rules. Throws on a break. */ export function validateSegment(segment: string, label: SegmentLabel): void { - // `Org` names nothing on disk, so neither "file" nor "folder" is true of it. - const what = - label === "Org" - ? "Organization id" - : `${label} ${FILE_LABELS.has(label) ? "file" : "folder"} name`; + const what = `${label} ${FILE_LABELS.has(label) ? "file" : "folder"} name`; if (segment.length > MAX_SEGMENT_LENGTH) { throw new Error(`${what} "${segment}" exceeds ${MAX_SEGMENT_LENGTH} characters`); @@ -107,9 +83,7 @@ export function validateSegment(segment: string, label: SegmentLabel): void { } if (!SEGMENT_PATTERN.test(segment)) { const identity = - label === "Org" - ? `it becomes the leading segment of a hired seat's address, which is joined with a "."` - : label === "Document" + label === "Document" ? `it becomes part of the document's ref, which is joined with a "/"` : label === "Channel" ? `it becomes part of the channel's identity, which is joined with a "."` diff --git a/packages/workforce/src/roster/address.ts b/packages/workforce/src/roster/address.ts index b3e8f54f03..d264a60945 100644 --- a/packages/workforce/src/roster/address.ts +++ b/packages/workforce/src/roster/address.ts @@ -5,15 +5,13 @@ * Split out of `rows.ts`, which re-exports both, so a browser panel can * resolve an address without the roster's collection definitions (and through * them the `@flow-state-dev/core` root). A leaf on purpose (BP-019): the only - * imports are `@flow-state-dev/core/types` and `../loader/segments`, which - * imports only the pure `@flow-state-dev/core/helpers` (enforced by + * import is `@flow-state-dev/core/types` (kept free of Node built-ins by * `test/browser-subpath-safe.test.ts`). * `@flow-state-dev/workforce/browser` re-exports * {@link splitSeatAddress} from here. */ import { encodeUserSegment } from "@flow-state-dev/core/types"; -import { validateSegment } from "../loader/segments"; /** * The address a runtime-hired seat answers on. @@ -22,21 +20,24 @@ import { validateSegment } from "../loader/segments"; * the user escaped. `ownerUserId` comes from the hire row. Nothing here * reads a pin out of an address that was already built. * - * The org is validated as one address segment, so it carries no `.` — which - * is what makes the join injective and therefore reversible by - * {@link splitSeatAddress}. The seat id keeps its own shape: dotted - * for a team seat (`"."`), bare for an org seat (`""`). - * Only the leading segment has to be dot-free. + * Any org id the principal carries is accepted (`org_acme`, the framework's + * `__fsd_default_org__`). It is escaped the way the user segment is, by + * {@link orgSegment}, so the leading segment carries no `.` — which is what + * makes the join injective and therefore reversible by {@link splitSeatAddress}. + * An org already spelled in lowercase letters, digits and hyphens escapes to + * itself, so its addresses read as `.`. The seat id keeps its own + * shape: dotted for a team seat (`"."`), bare for an org seat + * (`""`). Only the leading segment has to be dot-free. * - * @throws when the org id is not a legal address segment, the seat id is - * empty, or the seat id starts with `~` (that marker is the user-owned form). + * @throws when the org id or the seat id is empty, or the seat id starts with + * `~` (that marker is the user-owned form). */ export function seatAddress( orgId: string, seatId: string, ownerUserId?: string | null, ): string { - validateSegment(orgId, "Org"); + const org = orgSegment(orgId); if (seatId.length === 0) { throw new Error("A seat id must not be empty — it is half of the seat's address"); } @@ -46,21 +47,37 @@ export function seatAddress( ); } if (ownerUserId != null && ownerUserId.length > 0) { - return `${orgId}.~${encodeUserSegment(ownerUserId)}.${seatId}`; + return `${org}.~${encodeUserSegment(ownerUserId)}.${seatId}`; } - return `${orgId}.${seatId}`; + return `${org}.${seatId}`; +} + +/** + * An org id as the leading segment of a seat's address: the user segment's + * escape, applied to the org. Lowercase letters, digits and `-` pass through; + * every other character (`_`, `.`, `%`, upper case) is percent-encoded, so the + * result holds no `.` and two org ids never share one. + * + * @throws when the org id is empty. + */ +function orgSegment(orgId: string): string { + if (orgId.length === 0) { + throw new Error("An organization id must not be empty — it is the first half of a seat's address"); + } + return encodeUserSegment(orgId); } /** * The seat id inside an address this org owns, or `undefined`. * - * One split at the first dot, which is correct only because the org is a - * validated segment. A user-owned address is `.~.`; the - * user segment is skipped and is not returned as an owner. The pin stays on - * the hire row. + * One split at the first dot, which is correct only because the escaped org + * holds no dot. A user-owned address is `.~.`; the user + * segment is skipped and is not returned as an owner. The pin stays on the + * hire row. */ export function splitSeatAddress(orgId: string, address: string): string | undefined { - const prefix = `${orgId}.`; + if (orgId.length === 0) return undefined; + const prefix = `${orgSegment(orgId)}.`; if (!address.startsWith(prefix)) return undefined; const rest = address.slice(prefix.length); if (rest.startsWith("~")) { diff --git a/packages/workforce/test/roster-check.test.ts b/packages/workforce/test/roster-check.test.ts index 6a475e14c1..c20fc10fdf 100644 --- a/packages/workforce/test/roster-check.test.ts +++ b/packages/workforce/test/roster-check.test.ts @@ -85,7 +85,7 @@ describe("checkHiredSeatRow", () => { if (!checked.ok) expect(checked.detail).toMatch(/queue/); }); - it("unreadable: a row that doesn't parse, a row stamped for another org, an unaddressable org", () => { + it("unreadable: a row that doesn't parse, a row stamped for another org; any org id addresses", () => { const shapeless = checkHiredSeatRow("acme", { seatId: "support.x" }, kinds); expect(shapeless).toMatchObject({ ok: false, reason: "unreadable" }); expect(shapeless.ok ? undefined : shapeless.row).toBeUndefined(); @@ -94,8 +94,9 @@ describe("checkHiredSeatRow", () => { expect(foreign).toMatchObject({ ok: false, reason: "unreadable" }); if (!foreign.ok) expect(foreign.detail).toMatch(/cannot be registered under "acme"/); - const badOrg = checkHiredSeatRow("Not An Org", stored({ seatId: "support.z", flow: "desk", owningOrgId: null }), kinds); - expect(badOrg).toMatchObject({ ok: false, reason: "unreadable" }); + // An org id outside lowercase-hyphen is escaped into the address, not refused. + const spacedOrg = checkHiredSeatRow("Not An Org", stored({ seatId: "support.z", flow: "desk", settings: { queue: "q" }, owningOrgId: null }), kinds); + expect(spacedOrg).toMatchObject({ ok: true }); }); it("the reload names each skipped row with the check's detail, unchanged", async () => { diff --git a/packages/workforce/test/roster.test.ts b/packages/workforce/test/roster.test.ts index eabc8017f8..35fed20c08 100644 --- a/packages/workforce/test/roster.test.ts +++ b/packages/workforce/test/roster.test.ts @@ -12,9 +12,8 @@ * shadow back over the column. * V3 — give `settings` a closed shape instead of a passthrough record: the * unknown-key assertion fails and a seat comes back on defaults. - * V4 — drop `validateSegment(orgId, "Org")` from `seatAddress`: both hires - * succeed and mint the SAME address, so the second silently rebinds - * the first. + * V4 — pass the org into `seatAddress` unescaped: both hires succeed and + * mint the SAME address, so the second silently rebinds the first. * V5 — hire the roster in one `hireWorkforce` call instead of per row: the * stale row's throw takes the good row with it, so `seats` is empty * and `problems` never names anything. This is the degrade path @@ -41,6 +40,7 @@ import { parseHiredSeatRow, reloadHiredSeats, seatAddress, + splitSeatAddress, toHiredSeatRow, type HiredRosterStores, } from "../src/roster"; @@ -210,20 +210,31 @@ describe("V3 · a row round-trips to a record and back", () => { describe("V4 · the org segment is what makes the address unambiguous", () => { it("cannot let org `acme` + `support.ada` and org `acme.support` + `ada` coexist", () => { - // Both would spell `acme.support.ada`. Exactly one of them is addressable, - // and it is refused at the segment check rather than discovered later by - // whichever hire happened to land second. + // Both would spell `acme.support.ada` if the org went in as written. The + // org is escaped like the user segment, so its dot can't reach the + // address and the two land apart. Pass the org through raw and the second + // expectation fails: both hires mint one address and the second silently + // rebinds the first. expect(seatAddress("acme", "support.ada")).toBe("acme.support.ada"); + expect(seatAddress("acme.support", "ada")).toBe("acme%2Esupport.ada"); expect(seatAddress("acme", "research", "alice")).toBe("acme.~alice.research"); expect(seatAddress("acme", "research", "alice@acme.com")).toBe("acme.~alice%40acme%2Ecom.research"); expect(() => seatAddress("acme", "~research", "alice")).toThrow(/starts with "~"/); - expect(() => seatAddress("acme.support", "ada")).toThrow(/Organization id/); - expect(() => seatAddress("acme.support", "ada")).toThrow(/"\."/); }); - it("refuses an empty and an over-long org id", () => { - expect(() => seatAddress("", "support.ada")).toThrow(); - expect(() => seatAddress("a".repeat(65), "support.ada")).toThrow(/64/); + it("addresses any org the principal carries, and splits back under it alone", () => { + expect(seatAddress("org_pentest_lab", "helper")).toBe("org%5Fpentest%5Flab.helper"); + expect(seatAddress(DEFAULT_ORG_ID, "lead")).toBe("%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead"); + expect(splitSeatAddress("org_pentest_lab", "org%5Fpentest%5Flab.helper")).toBe("helper"); + expect(splitSeatAddress("acme.support", "acme%2Esupport.ada")).toBe("ada"); + // An org never reads another's address, even one its raw spelling prefixes. + expect(splitSeatAddress("acme", "acme%2Esupport.ada")).toBeUndefined(); + expect(splitSeatAddress("acme.support", "acme.support.ada")).toBeUndefined(); + }); + + it("refuses an empty org id", () => { + expect(() => seatAddress("", "support.ada")).toThrow(/organization id must not be empty/); + expect(splitSeatAddress("", ".ada")).toBeUndefined(); }); it("refuses an empty seat id", () => { @@ -314,13 +325,12 @@ describe("V5 · a boot reload skips what it cannot use and serves the rest", () expect(seats[1]!.config).toMatchObject({ desk: "bravo-front" }); }); - it("skips a row it cannot address, and still serves every other org", async () => { - // An app with no principal resolver runs as DEFAULT_ORG_ID, so a runtime - // hire there leaves a row in a cell whose id is not a legal address - // segment. That row can never become a seat, but it must cost only - // itself: the boot still has to hand back acme's team, and the row has to - // be named rather than dropped. A seat id carrying the user-owned `~` - // marker is the same failure one segment later. + it("serves the default org's rows, and skips only a row it cannot address", async () => { + // An app with no principal resolver runs as DEFAULT_ORG_ID, and a runtime + // hire there comes back at boot like any other org's. A seat id carrying + // the user-owned `~` marker can never become a seat, but it must cost only + // itself: the boot still hands back every other row, and names this one + // rather than dropping it. const stores = storeHolding({ acme: { "support.ada": { seatId: "support.ada", flow: "desk-clerk", settings: {} }, @@ -342,14 +352,10 @@ describe("V5 · a boot reload skips what it cannot use and serves the rest", () kinds, }); - expect(seats.map((seat) => seat.id)).toEqual(["acme.support.ada"]); - expect(problems).toHaveLength(2); - const tilde = problems.find((problem) => problem.includes('organization "acme"')); - const defaultOrg = problems.find((problem) => problem.includes(DEFAULT_ORG_ID)); - expect(tilde).toContain('organization "acme", row "workforce/roster/~support.bo"'); - expect(tilde).toContain('starts with "~"'); - expect(defaultOrg).toContain(`organization "${DEFAULT_ORG_ID}", row "workforce/roster/lead"`); - expect(defaultOrg).toContain("Organization id"); + expect(seats.map((seat) => seat.id)).toEqual([seatAddress(DEFAULT_ORG_ID, "lead"), "acme.support.ada"]); + expect(problems).toHaveLength(1); + expect(problems[0]).toContain('organization "acme", row "workforce/roster/~support.bo"'); + expect(problems[0]).toContain('starts with "~"'); }); it("still refuses a row stamped for another org, even when that org is not addressable", async () => { diff --git a/packages/workforce/test/seat-hire-blocks.test.ts b/packages/workforce/test/seat-hire-blocks.test.ts index 6fbe88680a..67a4711f49 100644 --- a/packages/workforce/test/seat-hire-blocks.test.ts +++ b/packages/workforce/test/seat-hire-blocks.test.ts @@ -11,6 +11,8 @@ import { createTestContext } from "@flow-state-dev/testing"; import type { SeatHireCapabilityOptions } from "../src/seat-hire-blocks"; import { defineHiredRosterCollection } from "../src/roster/collections"; import { defineSeatInventoryCollection } from "../src/inventory/collections"; +import { seatAddress, splitSeatAddress } from "../src/roster/address"; +import { DEFAULT_ORG_ID } from "@flow-state-dev/core/types"; const captured = vi.hoisted(() => ({ hire: undefined as unknown, @@ -43,14 +45,17 @@ function presetTools(cap: Parameters[0]): unknown[] ); } -async function hireAgainst(register: SeatHireCapabilityOptions["register"] = () => {}) { +async function hireAgainst( + register: SeatHireCapabilityOptions["register"] = () => {}, + orgId = "acme", +) { const { createSeatHireBlocks } = await import("../src/seat-hire-blocks"); const { hire } = createSeatHireBlocks({ register, unregister: () => true, }); const runtime = await createTestContext({ - orgId: "acme", + orgId, sessionId: "test-session", declaredResources: { [HIRED_ROSTER_RESOURCE]: defineHiredRosterCollection(), @@ -152,3 +157,31 @@ describe("register throwing leaves no roster row and no inventory row", () => { expect(await listedIds(ctx, SEAT_INVENTORY_RESOURCE, "id")).toEqual([]); }); }); + +describe("an org id that is not a lowercase-hyphen segment can hire", () => { + // The framework's own default org, and the `org_…` ids auth providers hand + // out. Put the segment check back in `seatAddress` and every hire here is + // refused with "Organization id … must be lowercase letters". + for (const orgId of ["org_pentest_lab", DEFAULT_ORG_ID, "Org_2NfXq"]) { + it(`hires under "${orgId}", at an address that splits back to the seat id`, async () => { + const registered: string[] = []; + const { hire, ctx } = await hireAgainst((seat) => { + registered.push(seat.id); + }, orgId); + + const result = await executeBlock({ + block: hire, + input: { seatId: "helper", flow: "agent" }, + ctx, + }); + + expect(result.error).toBeUndefined(); + const address = (result.output as { address: string }).address; + expect(address).toBe(seatAddress(orgId, "helper")); + expect(registered).toEqual([address]); + expect(splitSeatAddress(orgId, address)).toBe("helper"); + expect(await listedIds(ctx, HIRED_ROSTER_RESOURCE, "seatId")).toEqual(["helper"]); + expect(await listedIds(ctx, SEAT_INVENTORY_RESOURCE, "id")).toEqual([address]); + }); + } +}); From 7da156e517859256f882b22988e6523d72f9fea5 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 00:28:21 +0000 Subject: [PATCH 03/28] docs(workforce): chief-of-staff registry lookup, room wake and template wiring; any org id hires (FIX-1757) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 5 +++++ apps/docs/docs/workforce/channels.md | 16 +++++++++++++ apps/docs/docs/workforce/chief-of-staff.md | 26 ++++++++++++++++++++-- apps/docs/docs/workforce/durable-hire.md | 15 +++++-------- packages/workforce/README.md | 14 +++++++----- packages/workforce/src/roster/rows.ts | 6 ++--- 6 files changed, 61 insertions(+), 21 deletions(-) create mode 100644 .changeset/hire-any-org-id.md diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md new file mode 100644 index 0000000000..fa066c8f17 --- /dev/null +++ b/.changeset/hire-any-org-id.md @@ -0,0 +1,5 @@ +--- +"@flow-state-dev/workforce": patch +--- + +`seatAddress` now accepts any non-empty organization id, including `__fsd_default_org__` and ids like `org_acme`, by percent-escaping it the way the user segment already is; ids of lowercase letters, digits and `-` keep their existing addresses. `@flow-state-dev/workforce/browser` also exports `seatAddress` (FIX-1757). diff --git a/apps/docs/docs/workforce/channels.md b/apps/docs/docs/workforce/channels.md index dc02d9cfce..a6ef3410f5 100644 --- a/apps/docs/docs/workforce/channels.md +++ b/apps/docs/docs/workforce/channels.md @@ -816,8 +816,24 @@ const { resources } = splitResourceModules(resourceModules); const instances = channelInstances(channels, { kinds, resources }); ``` +An app that doesn't run `fsdev gen` imports the file's default export and passes it under the collection's name, `projects`, the basename of `projects.ts`: + +```ts +import projectsCollection from "./workforce/org/resources/projects"; + +// channels and kinds as above +const instances = channelInstances(channels, { + kinds, + resources: { projects: projectsCollection }, +}); +``` + +The other arguments are as in the snippet above. Any other key is refused with `names collection "projects", which is not in the org's resources passed to channelInstances`. + Rooms run on the built-in channel kind, and that kind has to be able to wake seats, so build it with a notify block, as in `kinds: { channel: defineChannelFlow({ notify: wakeMemberSeats(seats) }) }`. Left as the plain built-in, a template that names seats is refused, because no post would wake them. +`wakeMemberSeats(seats)` wakes a member whose seat is in the `seats` list and whose kind hears channel posts, as the built-in `agent` kind does. A notify block you write yourself wakes only the members its own code wakes; `channelInstances` doesn't check that it reaches the template's seats. A seat hired after you built `wakeMemberSeats(seats)` isn't in its list and isn't woken. + If your app calls `channelInstances` more than once, say once per flow, only one call needs `resources`. The first call that finds the template keeps it for the whole process, and every other call builds its channel kind with the same seats and charter. A call that finds a different template is refused. A team can declare the template in a `CHANNEL.md` instead, by marking it `mintFor: projects`. Its `members:` are the seats and its body is the charter: diff --git a/apps/docs/docs/workforce/chief-of-staff.md b/apps/docs/docs/workforce/chief-of-staff.md index 98e9566801..0df597c979 100644 --- a/apps/docs/docs/workforce/chief-of-staff.md +++ b/apps/docs/docs/workforce/chief-of-staff.md @@ -88,13 +88,35 @@ kinds.agent = defineAgentWorkerFlow({ }); ``` -`registry-access.ts` is the module from [Reaching the `FlowState`](./durable-hire.md#reaching-the-flowstate), with two more exports, both read from `(await flowState.getRuntime()).registry` once the app is up. `kindAt(address)` returns the kind of the flow registered at that address; the hire tools use it to refuse a declared seat by name. `instanceAt(address)` returns the flow instance registered at that address, or `undefined`. The hire tools use it to tell a seat they minted apart from another seat at the same address, so a re-hire interrupted by a restart completes, and `fire` releases only its own seat. +Add `kindAt` and `instanceAt` to the `registry-access.ts` from [Reaching the `FlowState`](./durable-hire.md#reaching-the-flowstate), next to `registerSeat` and `releaseSeat`. They use the `FlowInstance` and `FlowState` imports already in the file: + +```ts title="src/flows/workforce-admin/registry-access.ts" +let registry: Awaited>["registry"] | undefined; + +/** Call once, right after `createFlowState`, alongside `useFlowState`. */ +export async function useRegistry(next: FlowState): Promise { + registry = (await next.getRuntime()).registry; +} + +export const kindAt = (address: string): string | undefined => registry?.get(address)?.kind; +export const instanceAt = (address: string): FlowInstance | undefined => registry?.get(address); +``` + +`kindAt(address)` returns the kind of the flow registered at that address, or `undefined`; the hire tools use it to refuse a declared seat by name. `instanceAt(address)` returns the flow instance registered there, or `undefined`. The hire tools use it to tell a seat they minted apart from another seat at the same address, so a re-hire interrupted by a restart completes, and `fire` releases only its own seat. + +Both read nothing until `useRegistry` has run, so call it where you call `useFlowState`: + +```ts +const app = createFlowState(/* ... */); +useFlowState(app); +await useRegistry(app); +``` `createWorkforceCapability` gives every seat on the kind `discover`, which is how the chief of staff answers questions about the roster. The small `channel-inventory` capability declares the channel inventory as a resource on the kind, and passing its key, `channelInventory` here, as `inventory.channels` lets `discover` answer who is on a channel too. `channelPostCapability` adds `post-to-channel`, so the chief of staff can answer in a channel it is a member of. `createSeatHireCapability` takes the same options as [`createSeatHireBlocks`](./durable-hire.md#the-ready-made-hire-and-fire-handlers), plus `askBefore`. Installing the tools on a kind doesn't hand them to every seat of it. A seat holds `hire` or `fire` only when its own `tools:` names it, so keep those names in the chief of staff's file and no other. `refuseRosterAdmin: true` keeps them out of the seats the chief of staff hires, too. Leave it off and a hire may name them like any other tool. -If your Lab has projects, add `chief-of-staff` to the project template's `seats` (or a team `CHANNEL.md` template's `members:`), so the chief of staff is in every project's room. +If your Lab has projects, add `chief-of-staff` to the project template's `seats` (or a team `CHANNEL.md` template's `members:`), so the chief of staff is in every project's room. Build the channel kind with `wakeMemberSeats(seats)` so a post in the room wakes it, and pass the template to `channelInstances` as [A room per project](./channels.md#a-room-per-project) shows, including without `fsdev gen`. Read the seats it hired back when the app starts, as in [Reading the roster back at the next start](./durable-hire.md#reading-the-roster-back-at-the-next-start), and serve the app over a store that survives a restart. Otherwise a hire lasts only as long as the process. diff --git a/apps/docs/docs/workforce/durable-hire.md b/apps/docs/docs/workforce/durable-hire.md index 763d0c4c72..4213d0ddbe 100644 --- a/apps/docs/docs/workforce/durable-hire.md +++ b/apps/docs/docs/workforce/durable-hire.md @@ -25,7 +25,7 @@ All of these come from `@flow-state-dev/workforce`: | --- | --- | | `defineHiredRosterCollection()` | Declares the stored roster: an organization-scoped resource collection at `workforce/roster/*`, one row per hired seat. Takes no options. | | `defineHiredRosterPrivateCollection()` | Declares where a [user-owned seat](#hiring-a-seat-only-one-member-can-reach)'s row is written, at `workforce/roster/~/`. Server-side only, and a block that has it in `resources` reaches only the calling user's rows. | -| `seatAddress(orgId, seatId, ownerUserId?)` | The address a hired seat answers on. Org-visible seats are `.`. A user-owned seat is `.~.`, with the user escaped, so two people can hire the same seat id. Throws when the organization id is not a single address segment, or when the seat id starts with `~`. | +| `seatAddress(orgId, seatId, ownerUserId?)` | The address a hired seat answers on. Org-visible seats are `.`. A user-owned seat is `.~.`, so two people can hire the same seat id. The organization id and the user are percent-escaped, as [The organization has to come from the credential](#the-organization-has-to-come-from-the-credential) spells out. Throws when the organization id is empty, or when the seat id is empty or starts with `~`. | | `hireWorkforce(records, { kinds })` | Turns records into configured flow copies, one per record. The same call the file-declared roster goes through. | | `reloadHiredSeats({ stores, orgIds, kinds })` | Reads every stored row back at the next start and hires what it names. Returns `{ seats, problems, byOrg }`. It registers nothing. | | `createSeatHireBlocks(options)` | Returns `{ hire, fire, brokenSeats, rehire }`: two handlers that run the whole hire and fire sequence, and two that list and [repair a seat whose kind is gone](#repairing-a-seat-whose-kind-is-gone). Mount them as a flow's actions. See [the ready-made handlers](#the-ready-made-hire-and-fire-handlers). | @@ -80,7 +80,7 @@ Give each organization its own token. A token written against two organizations Register the flow only when a usable credential is configured. Then a deployment that has none has no hire route at all, and a call to `/api/flows/workforce-admin/actions/hire` comes back `404 Unknown flow "workforce-admin"` rather than reaching a check that can go wrong. -The organization's id must be a single address segment: lowercase letters, digits and single hyphens, up to 64 characters, and no dots. A dot would make the address ambiguous, since it is also what joins the organization to the seat. +`seatAddress` percent-escapes the organization id and the user in a seat's address: lowercase letters, digits and `-` stay, everything else is encoded. `acme` gives `acme.helper`, and `org_pentest_lab` becomes `org%5Fpentest%5Flab.helper`. Build and read addresses with `seatAddress` and `splitSeatAddress(orgId, address)`, which takes the seat id back out, rather than assembling `${orgId}.` prefixes by hand. ### Reaching the `FlowState` @@ -184,13 +184,7 @@ export default workforceAdmin(); The seats these handlers and the `seat-hire` tools hire are always org-visible: pinned to the organization and no user, so any caller the seat's resolver places in that organization can call one, and its roster row, `instructions` included, is readable by a browser in that organization. For a seat only one member can reach, write the hire yourself as in [Hiring a seat only one member can reach](#hiring-a-seat-only-one-member-can-reach). -Both handlers take the organization from the principal your `resolvePrincipal` returns for the session, as [above](#the-organization-has-to-come-from-the-credential). A session whose principal names no organization, which includes every session on a flow with no `resolvePrincipal`, belongs to the framework's default organization. That id can't start a seat address, so every hire there is refused before anything is written: - -```text -Organization id "__fsd_default_org__" must be lowercase letters, digits, and single hyphens (not at the start or end) — it becomes the leading segment of a hired seat's address, which is joined with a "." -``` - -Mount these handlers only on a flow whose resolver names a real organization. +Both handlers take the organization from the principal your `resolvePrincipal` returns for the session, as [The organization has to come from the credential](#the-organization-has-to-come-from-the-credential) describes. A session whose principal names no organization, which includes every session on a flow with no `resolvePrincipal`, belongs to the framework's default organization, `__fsd_default_org__`. A hire there succeeds. Its seat answers on `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.` and is reloaded at the next start like any other. A seat hired this way is pinned to the default organization. Without a seat-level resolver that names that organization, a caller whose principal doesn't match the pin gets `404 Unknown flow`, as for any hired seat. Install the resolver on the seat the way `registerSeat` does in [Reaching the `FlowState`](#reaching-the-flowstate). ### Hiring @@ -277,7 +271,8 @@ A caller the seat's resolver refuses, such as a request with no credential, gets `reloadHiredSeats` reads each organization's stored rows and hires what they name. It registers nothing, so you loop over what comes back: ```ts -// Wherever you build the FlowState, after createFlowState and useFlowState. +// Wherever you build the FlowState, after createFlowState and useFlowState +// (and useRegistry, if you pass kindAt and instanceAt). const runtime = await flowstate.getRuntime(); // Your policy. This one reloads every organization the deployment has a record for. diff --git a/packages/workforce/README.md b/packages/workforce/README.md index 62ea76f740..c803158df0 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -1485,8 +1485,9 @@ for (const seat of seats) { ``` A reloaded seat is addressed `.`, so two organizations can both hold a seat called -`support.ada`. The organization must be a single address segment — lowercase letters, digits and -single hyphens, up to 64 characters, and no dots, since a dot is what joins the two halves. +`support.ada`. The organization id is percent-escaped in the address: lowercase letters, digits and +`-` stay, everything else is encoded, so `org_pentest_lab` becomes `org%5Fpentest%5Flab.`. Use `seatAddress` and `splitSeatAddress` instead of building +`${orgId}.` prefixes by hand. Register the seats yourself, one at a time, with each seat's `ownerPin`, and add any refusal to `problems`. The other seats still start. @@ -1713,9 +1714,10 @@ const workforceAdmin = defineFlow({ ``` The organization comes from the session's principal; an `orgId` in the input is ignored. A -session whose principal names no organization belongs to the default organization, whose id -cannot start a seat address, so a hire there is refused before anything is written. Configure a -`resolvePrincipal` that returns an `orgId` on the flow that mounts these. +session whose principal names no organization belongs to the default organization, and a hire +there lands under `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.` and reloads at the next start like any +other. Configure a `resolvePrincipal` that returns an `orgId` on the flow that mounts these to hire +into a real organization. ### Posting to a channel from a seat @@ -2182,7 +2184,7 @@ before fire removed inventory rows is left out that way. | `hiredSeatRowSchema` / `HiredSeatRow` | One roster row — `{ seatId, flow, settings, instructions, owningOrgId, ownerUserId, pendingRepair, incarnation }`. `owningOrgId`, `ownerUserId`, `pendingRepair` (set only while a `rehire` is unfinished) and `incarnation` (the hire or re-hire that wrote it) are nullable and default to `null`. `pendingRepair` is server-only; `incarnation` is published to browsers by `defineHiredRosterCollection`, beside `seatId`, `flow` and `instructions`, so a browser can join a roster row to its inventory row. The envelope is closed when parsed; the roster collections store it with unknown keys kept, so a key a newer version wrote survives this version's rewrite of the row (a re-hire). `settings` is a passthrough bag belonging to the kind's own schema. | | `HIRED_ROSTER_PREFIX` | The roster's storage prefix, `"workforce/roster/"`. Moving it strands every roster already written. | | `HIRED_ROSTER_BROWSER_PATTERN` / `HIRED_ROSTER_PRIVATE_PATTERN` | The two roster collections' patterns, `"workforce/roster/*"` and `"workforce/roster/[owner]/[seat]"`. Like the prefix, they spell stored keys. | -| `seatAddress(orgId, seatId, ownerUserId?)` / `splitSeatAddress(orgId, address)` | Join an organization and a seat id into the address a hired seat answers on, and take the seat id back out. Org-visible is `.`. User-owned is `.~.`, with the user escaped. The pin is the hire row, not the address. Throws when the organization is not one legal address segment, or when the seat id starts with `~`. | +| `seatAddress(orgId, seatId, ownerUserId?)` / `splitSeatAddress(orgId, address)` | Join an organization and a seat id into the address a hired seat answers on, and take the seat id back out. Org-visible is `.`. User-owned is `.~.`, with the user escaped. The organization is percent-escaped like the user (`seatAddress("org_pentest_lab", "helper")` is `org%5Fpentest%5Flab.helper`). The pin is the hire row, not the address. `seatAddress` throws when the organization id is empty, or when the seat id is empty or starts with `~`. `splitSeatAddress` returns `undefined` when the address isn't under that organization. Both are also exported from `@flow-state-dev/workforce/browser`. | | `newIncarnation()` / `tagIncarnation(seat, incarnation)` | For a host that writes roster rows itself rather than through `createSeatHireCapability`. Stamp each hire's row with `toHiredSeatRow({ ..., incarnation: newIncarnation() })` and tag the seat minted from it with the same id. A fire then removes only the inventory row carrying that id, so a replacement hired at the same address keeps its own. A row written with no incarnation can't be told from a replacement written the same way. | | `toHiredSeatRow(input)` / `parseHiredSeatRow(value)` | Build a row from what a hire supplied, and read a stored value back into one. `parseHiredSeatRow` returns `{ row }` or `{ problem }` — it never throws and never rewrites the stored value. | | `hiredRosterStorageKey(row)` | `seatId` for an org-visible row, `~/` for a user-owned one. The user id is escaped, so a `/` in it stays one segment. | diff --git a/packages/workforce/src/roster/rows.ts b/packages/workforce/src/roster/rows.ts index a7c241a71f..e3eab67cf8 100644 --- a/packages/workforce/src/roster/rows.ts +++ b/packages/workforce/src/roster/rows.ts @@ -207,9 +207,9 @@ export function hiredSeatManifest( * or the one reason it cannot be. * * The per-row walk every reader of stored rows needs: parse, apply the - * owning-org fence, and build the address. The address throws when the org or - * the seat id cannot be one (a row under `DEFAULT_ORG_ID`, a seat id starting - * with `~`); here that throw is one row's reason, so a caller walking a roster + * owning-org fence, and build the address. The address throws when the seat id + * cannot be one (empty, or starting with `~`); here that throw is one row's + * reason, so a caller walking a roster * skips it and keeps the rest. `reloadHiredSeats` and the seats manifest * source both read through this, so they agree on which rows count. * From dedc1df2e2d52bb3a6f94720e9d29cc18528b97c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 00:31:02 +0000 Subject: [PATCH 04/28] test(shift-manager): build the hired chief of staff's address with seatAddress (FIX-1757) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- labs/shift-manager/test/chief-of-staff.test.ts | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/labs/shift-manager/test/chief-of-staff.test.ts b/labs/shift-manager/test/chief-of-staff.test.ts index 621c3d0728..c9dedf6b05 100644 --- a/labs/shift-manager/test/chief-of-staff.test.ts +++ b/labs/shift-manager/test/chief-of-staff.test.ts @@ -6,6 +6,7 @@ */ import { describe, expect, it } from "vitest"; import type { SessionSummary } from "@flow-state-dev/client"; +import { seatAddress } from "@flow-state-dev/workforce/browser"; import { chiefOfStaffOf, shiftSummary, streamCounts, type LoadedSnapshot } from "../src/lib/derive"; import { conversationSession, currentConversation, newConversationId } from "../src/lib/cos"; import { parseRoute, pathFor, type Route } from "../src/lib/routes"; @@ -46,9 +47,10 @@ describe("which seat is the chief of staff (V2, D2)", () => { it("finds an org seat and a team's seat by the name after the org's address", () => { expect(chiefOfStaffOf([seat("chief-of-staff"), seat("ops.asker")], ORG)).toEqual({ kind: "one", seat: seat("chief-of-staff") }); expect(chiefOfStaffOf([seat("desk.chief-of-staff"), seat("desk.asker")], ORG)).toEqual({ kind: "one", seat: seat("desk.chief-of-staff") }); - // An Ops-hired seat's address is `.`. - expect(chiefOfStaffOf([seat(`${ORG}.chief-of-staff`)], ORG)).toEqual({ kind: "one", seat: seat(`${ORG}.chief-of-staff`) }); - expect(chiefOfStaffOf([seat(`${ORG}.desk.chief-of-staff`)], ORG).kind).toBe("one"); + // An Ops-hired seat's address is `seatAddress(org, seatId)`: `org_1` is escaped to `org%5F1`. + const hired = seatAddress(ORG, "chief-of-staff"); + expect(chiefOfStaffOf([seat(hired)], ORG)).toEqual({ kind: "one", seat: seat(hired) }); + expect(chiefOfStaffOf([seat(seatAddress(ORG, "desk.chief-of-staff"))], ORG).kind).toBe("one"); }); it("is several, and no guess, when two seats carry the name", () => { From 2a3c8179c44ac197abb896cbf2e812965d9f6d51 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 00:38:31 +0000 Subject: [PATCH 05/28] test(kitchen-sink): assert a dotted org's seat lands apart, not refused; note why org ids are escaped (FIX-1757) The V11 case asserted the old contract (an org id that isn't one segment is refused). What it protected is injectivity: `kitchen-sink.support` + `ada` must not answer where `kitchen-sink` + `support.ada` does. It now hires both and checks they land on distinct addresses that split back to their own seat ids. Also drops the stale validateSegment note from rows.ts. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .../kitchen-sink/test/workforce-admin.test.ts | 34 ++++++++++++------- packages/workforce/src/roster/address.ts | 5 ++- packages/workforce/src/roster/rows.ts | 18 ++++------ 3 files changed, 31 insertions(+), 26 deletions(-) diff --git a/apps/kitchen-sink/test/workforce-admin.test.ts b/apps/kitchen-sink/test/workforce-admin.test.ts index bdb08fd8ee..7300ff0d5c 100644 --- a/apps/kitchen-sink/test/workforce-admin.test.ts +++ b/apps/kitchen-sink/test/workforce-admin.test.ts @@ -51,6 +51,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import type { FlowInstance } from "@flow-state-dev/core/types"; import { createInMemoryStores, runAction } from "@flow-state-dev/engine"; import { createMockModelResolver } from "@flow-state-dev/testing"; +import { seatAddress, splitSeatAddress } from "@flow-state-dev/workforce"; import { ADMIN_TOKENS_ENV, adminCredentialConfigured, @@ -422,22 +423,29 @@ describe("V11 · a duplicate hire is refused and changes nothing", () => { expect(await storedRow(stores, "support.ada")).toBeUndefined(); }); - it("refuses an organization that is not one legal address segment", async () => { - stubRegistrar(); + it("keeps a dotted organization's seat off the address another organization's seat answers on", async () => { + const registrar = stubRegistrar(); const flow = adminFlow(); const stores = createInMemoryStores(); - // `kitchen-sink.support` + `ada` would spell `kitchen-sink.support.ada` — - // the same address `kitchen-sink` + `support.ada` spells. Exactly one of - // them can be addressable. - const result = await callAdmin( - flow, - stores, - "hire", - { seatId: "ada", flow: "agent", settings: {} }, - `${ORG}.support` - ); - expectRefused(result, /Organization id/); + // Raw, `kitchen-sink.support` + `ada` would spell `kitchen-sink.support.ada`, + // the address `kitchen-sink` + `support.ada` answers on, and the second hire + // would rebind the first. The org is escaped into the address, so both land, + // apart, and each splits back to its own seat id. + const dottedOrg = `${ORG}.support`; + const dotted = await callAdmin(flow, stores, "hire", { seatId: "ada", flow: "agent", settings: {} }, dottedOrg); + const plain = await callAdmin(flow, stores, "hire", { seatId: "support.ada", flow: "agent", settings: {} }); + expect(dotted.error).toBeUndefined(); + expect(plain.error).toBeUndefined(); + + // This flow's hires are owned by the caller, `admin`. + const dottedAddress = seatAddress(dottedOrg, "ada", "admin"); + const plainAddress = seatAddress(ORG, "support.ada", "admin"); + expect(dottedAddress).not.toBe(plainAddress); + expect([...registrar.held.keys()].sort()).toEqual([dottedAddress, plainAddress].sort()); + expect(splitSeatAddress(dottedOrg, dottedAddress)).toBe("ada"); + expect(splitSeatAddress(ORG, dottedAddress)).toBeUndefined(); + expect(await storedRow(stores, "ada", dottedOrg)).toBeDefined(); }); }); diff --git a/packages/workforce/src/roster/address.ts b/packages/workforce/src/roster/address.ts index d264a60945..ab3751ad94 100644 --- a/packages/workforce/src/roster/address.ts +++ b/packages/workforce/src/roster/address.ts @@ -54,7 +54,10 @@ export function seatAddress( /** * An org id as the leading segment of a seat's address: the user segment's - * escape, applied to the org. Lowercase letters, digits and `-` pass through; + * escape, applied to the org. Not `validateSegment`: that rule is for names + * on disk (team, worker and channel folders), which an author chooses. A + * runtime org id comes from the principal, is opaque, and so is escaped + * rather than validated. Lowercase letters, digits and `-` pass through; * every other character (`_`, `.`, `%`, upper case) is percent-encoded, so the * result holds no `.` and two org ids never share one. * diff --git a/packages/workforce/src/roster/rows.ts b/packages/workforce/src/roster/rows.ts index e3eab67cf8..1374a04645 100644 --- a/packages/workforce/src/roster/rows.ts +++ b/packages/workforce/src/roster/rows.ts @@ -11,22 +11,16 @@ * politeness: a stored row was written by a past runtime against code that has * since moved, so the boot that finds it must be able to skip it and serve, * and a boot that rewrote data it did not understand would destroy the - * evidence of why it did not. The one thing that DOES throw is a bad org id, - * because that is this deploy's mistake rather than a past one — see - * {@link seatAddress}. A reader walking stored rows calls + * evidence of why it did not. The one thing that DOES throw is an address that + * cannot be built (an empty org id, or a seat id that is empty or starts with + * `~`) — see {@link seatAddress}. A reader walking stored rows calls * {@link hiredSeatManifestFromStored}, which turns that throw into a reason * too. * * The address pair lives in `./address.ts` and is re-exported here, so a - * browser can take it without this module's collections. Its import of - * `validateSegment` reaches into `../loader/` and is safe: - * `loader/segments.ts` imports only the pure `@flow-state-dev/core/helpers` - * (for the shared Windows device-name list), which - * `test/browser-subpath-safe.test.ts` enforces. The package's root/loader split - * exists to keep `node:fs` out of anything importing `@flow-state-dev/workforce`, - * and the naming rule is the one piece of the loader with no filesystem in it. - * Copying the rule here instead would be the second copy of a rule whose whole - * value is that every reader agrees on it. + * browser can take it without this module's collections. Its only import is + * `@flow-state-dev/core/types`, which `test/browser-subpath-safe.test.ts` keeps + * free of Node built-ins. */ import { encodeUserSegment, ownerSegment, type InstanceOwnerPin } from "@flow-state-dev/core/types"; From 6f42cd557ace2b615c992fd5a300055b17f30e45 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 00:43:51 +0000 Subject: [PATCH 06/28] fix(core,workforce): refuse org ids with lone surrogates; correct default-org seat guidance (FIX-1757) A lone UTF-16 surrogate has no UTF-8 form, so the org escape mapped it onto U+FFFD and two org ids shared one address (Codex P2). isValidOrgId now refuses such ids at the principal boundary, and seatAddress checks again. durable-hire.md told unauthenticated apps to put a resolver on a default-org seat, which can't work: a resolver can't name the default org (401) and a real org misses the pin (404). It now says such a seat is reachable only with no resolver on the seat or the host. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 3 ++- apps/docs/docs/workforce/durable-hire.md | 6 +++-- packages/core/src/types/auth.ts | 9 ++++++- packages/core/test/org-id.test.ts | 30 ++++++++++++++++++++++++ packages/workforce/src/roster/address.ts | 8 ++++++- packages/workforce/test/roster.test.ts | 10 ++++++++ 6 files changed, 61 insertions(+), 5 deletions(-) create mode 100644 packages/core/test/org-id.test.ts diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index fa066c8f17..b7b7fd5315 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -1,5 +1,6 @@ --- "@flow-state-dev/workforce": patch +"@flow-state-dev/core": patch --- -`seatAddress` now accepts any non-empty organization id, including `__fsd_default_org__` and ids like `org_acme`, by percent-escaping it the way the user segment already is; ids of lowercase letters, digits and `-` keep their existing addresses. `@flow-state-dev/workforce/browser` also exports `seatAddress` (FIX-1757). +`seatAddress` now accepts any well-formed organization id, including `__fsd_default_org__` and ids like `org_acme`, by percent-escaping it the way the user segment already is (ids of lowercase letters, digits and `-` keep their existing addresses), and `@flow-state-dev/workforce/browser` also exports `seatAddress`. `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate (FIX-1757). diff --git a/apps/docs/docs/workforce/durable-hire.md b/apps/docs/docs/workforce/durable-hire.md index 4213d0ddbe..1b655cc3a4 100644 --- a/apps/docs/docs/workforce/durable-hire.md +++ b/apps/docs/docs/workforce/durable-hire.md @@ -44,7 +44,7 @@ The files on this page go in your app's own source tree, under `src/flows/`, whe A hire writes durable state that belongs to an organization, so the organization has to come from something the framework can trust, not from the request body. Configure [`resolvePrincipal`](../server/authentication.md) on the flow and the action's `orgId` comes from there. An `orgId` in the body is ignored, so a caller can't hire into another organization by naming it in the input. -A hired seat is pinned to that organization, and every request to it is checked against the pin. The principal for that check comes from the seat's own `authentication` when it has one, and from the host's otherwise. With neither, every caller counts as the default organization, which never matches the pin, so opening the seat answers `404 Unknown flow` even for the person who hired it. So put the resolver that verified the hire on the seat itself, where you register it, as `registerSeat` [below](#reaching-the-flowstate) does. The seat then answers only callers that resolver accepts. If members should call the seat with their own sign-in, register it with a resolver that verifies them and names the same organization. Don't install it host-wide instead: a host-level resolver applies to every flow the app serves. +A hired seat is pinned to that organization, and every request to it is checked against the pin. The principal for that check comes from the seat's own `authentication` when it has one, and from the host's otherwise. With neither, every caller counts as the default organization. That never matches a pin to a real organization, so opening the seat answers `404 Unknown flow` even for the person who hired it. So put the resolver that verified the hire on the seat itself, where you register it, as `registerSeat` [below](#reaching-the-flowstate) does. The seat then answers only callers that resolver accepts. If members should call the seat with their own sign-in, register it with a resolver that verifies them and names the same organization. Don't install it host-wide instead: a host-level resolver applies to every flow the app serves. The exception is a seat hired under the default organization; see [the ready-made handlers](#the-ready-made-hire-and-fire-handlers). ```ts title="src/flows/workforce-admin/authentication.ts" import type { AuthenticationConfig } from "@flow-state-dev/core/types"; @@ -184,7 +184,9 @@ export default workforceAdmin(); The seats these handlers and the `seat-hire` tools hire are always org-visible: pinned to the organization and no user, so any caller the seat's resolver places in that organization can call one, and its roster row, `instructions` included, is readable by a browser in that organization. For a seat only one member can reach, write the hire yourself as in [Hiring a seat only one member can reach](#hiring-a-seat-only-one-member-can-reach). -Both handlers take the organization from the principal your `resolvePrincipal` returns for the session, as [The organization has to come from the credential](#the-organization-has-to-come-from-the-credential) describes. A session whose principal names no organization, which includes every session on a flow with no `resolvePrincipal`, belongs to the framework's default organization, `__fsd_default_org__`. A hire there succeeds. Its seat answers on `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.` and is reloaded at the next start like any other. A seat hired this way is pinned to the default organization. Without a seat-level resolver that names that organization, a caller whose principal doesn't match the pin gets `404 Unknown flow`, as for any hired seat. Install the resolver on the seat the way `registerSeat` does in [Reaching the `FlowState`](#reaching-the-flowstate). +Both handlers take the organization from the principal your `resolvePrincipal` returns for the session, as [The organization has to come from the credential](#the-organization-has-to-come-from-the-credential) describes. When no `resolvePrincipal` is configured for the request, neither on the flow nor on the host, every session belongs to the framework's default organization, `__fsd_default_org__`. A hire there succeeds. Its seat answers on `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.` and is reloaded at the next start like any other, and it is pinned to the default organization. + +A resolver can't name `__fsd_default_org__`; a request whose resolver does is refused with `401`. A resolver that returns a real organization doesn't match the pin, so its callers get `404 Unknown flow`. A seat hired under the default organization is reachable only when no resolver applies to it, neither on the seat nor on the host. Register it without a seat-level resolver on a host with none, and every caller is treated as unauthenticated and placed in the default organization. That suits a development app with no sign-in. For a deployment that signs people in, hire under a real organization and install the resolver on the seat the way `registerSeat` does in [Reaching the `FlowState`](#reaching-the-flowstate). ### Hiring diff --git a/packages/core/src/types/auth.ts b/packages/core/src/types/auth.ts index 706ce8a2c8..1640c7c14f 100644 --- a/packages/core/src/types/auth.ts +++ b/packages/core/src/types/auth.ts @@ -45,13 +45,20 @@ export const DEFAULT_ORG_ID = "__fsd_default_org__"; * framework stores exactly what the trusted source supplied, so a stored id * and the identity that produced it compare equal. * + * An id holding a lone UTF-16 surrogate is refused too: it has no UTF-8 form, + * so anything that encodes the id (a storage key, an address) would map it + * onto U+FFFD and give two distinct ids one encoding. + * * The one definition both the host's principal normalization and trusted * direct execution validate against, so the two cannot drift. */ export function isValidOrgId(value: unknown): value is string { - return typeof value === "string" && value.trim().length > 0; + return typeof value === "string" && value.trim().length > 0 && !LONE_SURROGATE.test(value); } +/** A high surrogate with no low one after it, or a low one with no high one before it. */ +const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(? { + it("accepts any well-formed nonempty id, including the default org and emoji", () => { + for (const id of ["acme", "org_pentest_lab", DEFAULT_ORG_ID, "acme.support", "�", "😀"]) { + expect(isValidOrgId(id), id).toBe(true); + } + }); + + it("refuses an id holding a lone surrogate, high or low", () => { + for (const id of ["\uD800", "acme\uD800", "\uDC00acme", "a\uDC00\uD800b"]) { + expect(isValidOrgId(id), JSON.stringify(id)).toBe(false); + } + }); + + it("refuses empty, whitespace-only and non-string values", () => { + for (const value of ["", " ", undefined, null, 7]) { + expect(isValidOrgId(value)).toBe(false); + } + }); +}); diff --git a/packages/workforce/src/roster/address.ts b/packages/workforce/src/roster/address.ts index ab3751ad94..90cb2c1896 100644 --- a/packages/workforce/src/roster/address.ts +++ b/packages/workforce/src/roster/address.ts @@ -11,7 +11,7 @@ * {@link splitSeatAddress} from here. */ -import { encodeUserSegment } from "@flow-state-dev/core/types"; +import { encodeUserSegment, isValidOrgId } from "@flow-state-dev/core/types"; /** * The address a runtime-hired seat answers on. @@ -67,6 +67,12 @@ function orgSegment(orgId: string): string { if (orgId.length === 0) { throw new Error("An organization id must not be empty — it is the first half of a seat's address"); } + // `isValidOrgId` refuses these at the principal; checked again here because + // the escape is injective only on well-formed strings (a lone surrogate + // encodes as U+FFFD, the same bytes as a real U+FFFD). + if (!isValidOrgId(orgId)) { + throw new Error(`Organization id ${JSON.stringify(orgId)} is not a usable organization id`); + } return encodeUserSegment(orgId); } diff --git a/packages/workforce/test/roster.test.ts b/packages/workforce/test/roster.test.ts index 35fed20c08..f7fe19cdc5 100644 --- a/packages/workforce/test/roster.test.ts +++ b/packages/workforce/test/roster.test.ts @@ -232,6 +232,16 @@ describe("V4 · the org segment is what makes the address unambiguous", () => { expect(splitSeatAddress("acme.support", "acme.support.ada")).toBeUndefined(); }); + it("refuses an org id with a lone surrogate, which would share U+FFFD's address", () => { + // The escape goes through UTF-8, where a lone surrogate becomes U+FFFD. + // Admit it and these two orgs would answer on one address. + expect(seatAddress("�", "ada")).toBe("%EF%BF%BD.ada"); + expect(() => seatAddress("\uD800", "ada")).toThrow(/not a usable organization id/); + expect(() => seatAddress("acme\uDC00", "ada")).toThrow(/not a usable organization id/); + // A well-formed pair is an ordinary character. + expect(seatAddress("😀", "ada")).toBe("%F0%9F%98%80.ada"); + }); + it("refuses an empty org id", () => { expect(() => seatAddress("", "support.ada")).toThrow(/organization id must not be empty/); expect(splitSeatAddress("", ".ada")).toBeUndefined(); From e551762a053be9d7ab7e90b0f214e5c11c45c6e1 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 01:09:58 +0000 Subject: [PATCH 07/28] fix(engine,node): decode route segments exactly once on every host (FIX-1757) Next and Vercel hand the router `params.path` already decoded once; the route matcher decoded it again, so a flow kind carrying a literal `%XX` (an escaped seat address, org or user segment) resolved to the wrong id there. The Node host passed raw segments, so it decoded once. parseFlowRoute now takes decoded segments (re-encodes, matcher decodes once). The Node host and the HTTP adapter's raw-URL fallback decode via the new decodePathSegments. Tests per host shape (node, next, vercel). Also: channels.md no longer claims a non-`projects` resources key is refused; core changeset bumped to minor. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 6 +- apps/docs/docs/api/server.md | 8 ++- apps/docs/docs/workforce/channels.md | 4 +- packages/engine/README.md | 3 +- packages/engine/src/routes/index.ts | 1 + packages/engine/src/routes/parseFlowRoute.ts | 29 ++++++++- .../http/createHttpTransportAdapter.ts | 6 +- packages/engine/test/router.test.ts | 46 +++++++++++++- packages/next/test/escaped-segments.test.ts | 60 +++++++++++++++++++ packages/node/src/app.ts | 13 ++-- packages/node/test/escaped-segments.test.ts | 54 +++++++++++++++++ packages/vercel/test/escaped-segments.test.ts | 38 ++++++++++++ 12 files changed, 254 insertions(+), 14 deletions(-) create mode 100644 packages/next/test/escaped-segments.test.ts create mode 100644 packages/node/test/escaped-segments.test.ts create mode 100644 packages/vercel/test/escaped-segments.test.ts diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index b7b7fd5315..0390971b8f 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -1,6 +1,8 @@ --- "@flow-state-dev/workforce": patch -"@flow-state-dev/core": patch +"@flow-state-dev/core": minor +"@flow-state-dev/engine": minor +"@flow-state-dev/node": patch --- -`seatAddress` now accepts any well-formed organization id, including `__fsd_default_org__` and ids like `org_acme`, by percent-escaping it the way the user segment already is (ids of lowercase letters, digits and `-` keep their existing addresses), and `@flow-state-dev/workforce/browser` also exports `seatAddress`. `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate (FIX-1757). +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are decoded exactly once on every host, so a flow kind carrying a literal `%XX` resolves on Next and Vercel as on Node: `parseFlowRoute` takes decoded segments, and the new `decodePathSegments` builds them from a raw URL path. diff --git a/apps/docs/docs/api/server.md b/apps/docs/docs/api/server.md index 5596747d1e..4bbb6b20da 100644 --- a/apps/docs/docs/api/server.md +++ b/apps/docs/docs/api/server.md @@ -143,10 +143,16 @@ const router = createFlowApiRouter({ export const { GET, POST, PATCH, DELETE } = router; ``` -### `parseFlowRoute(path)` +### `parseFlowRoute(method, path)` Parse a flow API path into its components (the addressed flow id, action, sessionId, and so on). The first segment of an action or stream route is an instance id, which for a singleton is its kind. See [Addressing an instance](../server/setup.md#addressing-an-instance). +`path` is an array of path segments beneath the mount prefix, each already percent-decoded once. A framework catch-all such as Next's `params.path` hands over that shape. `parseFlowRoute` decodes nothing further, so a segment that still contains `%5F` or `/` after that one decode is read as written. + +### `decodePathSegments(rawPath)` + +Splits a raw, still-encoded URL path (the part beneath the mount prefix) on `/` and decodes each segment once. The result is the array `parseFlowRoute` takes. Use it in a host that only has the raw URL. A segment with invalid percent-encoding is kept as written. + ## Execution ### `createExecutionContext(options)` diff --git a/apps/docs/docs/workforce/channels.md b/apps/docs/docs/workforce/channels.md index a6ef3410f5..b76d2b6911 100644 --- a/apps/docs/docs/workforce/channels.md +++ b/apps/docs/docs/workforce/channels.md @@ -816,7 +816,7 @@ const { resources } = splitResourceModules(resourceModules); const instances = channelInstances(channels, { kinds, resources }); ``` -An app that doesn't run `fsdev gen` imports the file's default export and passes it under the collection's name, `projects`, the basename of `projects.ts`: +An app that doesn't run `fsdev gen` imports the file's default export and passes it in `resources` under a key of its choosing. `fsdev gen` uses `projects`, the basename of `projects.ts`, and so does this example: ```ts import projectsCollection from "./workforce/org/resources/projects"; @@ -828,7 +828,7 @@ const instances = channelInstances(channels, { }); ``` -The other arguments are as in the snippet above. Any other key is refused with `names collection "projects", which is not in the org's resources passed to channelInstances`. +The other arguments are as in the snippet above. If you declare the template in a `CHANNEL.md` instead (below), its `mintFor:` must name the key you passed the collection under (`projects` here). Rooms run on the built-in channel kind, and that kind has to be able to wake seats, so build it with a notify block, as in `kinds: { channel: defineChannelFlow({ notify: wakeMemberSeats(seats) }) }`. Left as the plain built-in, a template that names seats is refused, because no post would wake them. diff --git a/packages/engine/README.md b/packages/engine/README.md index 48d0044bb2..644eb5b55d 100644 --- a/packages/engine/README.md +++ b/packages/engine/README.md @@ -708,7 +708,8 @@ Use `summarizeForLog(value)` for the same bounded payload summaries in custom lo **Registry/routes:** - `createFlowRegistry` — Register flow instances - `createFlowApiRouter` — Generate HTTP route handlers from a registry -- `parseFlowRoute` — Parse incoming request paths +- `parseFlowRoute` — Parse an incoming method and decoded path segments +- `decodePathSegments` — Turn a raw, still-encoded URL path into those decoded segments **Cross-flow schema validation:** diff --git a/packages/engine/src/routes/index.ts b/packages/engine/src/routes/index.ts index 0db408c171..621897490d 100644 --- a/packages/engine/src/routes/index.ts +++ b/packages/engine/src/routes/index.ts @@ -9,6 +9,7 @@ export { type FlowApiRouter } from "./createFlowApiRouter"; export { + decodePathSegments, parseFlowRoute, type ParsedFlowRoute } from "./parseFlowRoute"; diff --git a/packages/engine/src/routes/parseFlowRoute.ts b/packages/engine/src/routes/parseFlowRoute.ts index e398b397c2..5ec0eef279 100644 --- a/packages/engine/src/routes/parseFlowRoute.ts +++ b/packages/engine/src/routes/parseFlowRoute.ts @@ -53,6 +53,13 @@ export type ParsedFlowRoute = * Empty / whitespace-only segments are dropped so request paths that come * in as `["", "sessions", "abc"]` from a Next.js catch-all match the same * way as `["sessions", "abc"]`. + * + * `path` holds **decoded** segments, the shape a framework catch-all (Next's + * `params.path`) hands over: each URL segment percent-decoded exactly once. + * The segments are re-encoded before matching and the matcher decodes once, + * so each segment reaches the route as given: a literal `%5F` or `/` inside + * one stays in it. A host that only has the raw URL decodes it with + * {@link decodePathSegments} first. */ export function parseFlowRoute( method: string, @@ -61,6 +68,26 @@ export function parseFlowRoute( const segments = (Array.isArray(path) ? path : []) .map((segment) => segment.trim()) .filter((segment) => segment.length > 0); - const pathname = segments.length === 0 ? "/" : `/${segments.join("/")}`; + const pathname = + segments.length === 0 ? "/" : `/${segments.map(encodeURIComponent).join("/")}`; return matchFlowRoute(method, pathname); } + +/** + * Splits a raw, still-encoded URL path (the part beneath the mount prefix) + * into the decoded segments {@link parseFlowRoute} takes: split on `/` first, + * then decode each segment once, so an encoded `%2F` stays inside its + * segment. A segment that is not valid percent-encoding is kept as written. + */ +export function decodePathSegments(rawPath: string): string[] { + return rawPath + .split("/") + .filter((segment) => segment.length > 0) + .map((segment) => { + try { + return decodeURIComponent(segment); + } catch { + return segment; + } + }); +} diff --git a/packages/engine/src/transports/http/createHttpTransportAdapter.ts b/packages/engine/src/transports/http/createHttpTransportAdapter.ts index 67f921a841..94740dd63a 100644 --- a/packages/engine/src/transports/http/createHttpTransportAdapter.ts +++ b/packages/engine/src/transports/http/createHttpTransportAdapter.ts @@ -15,7 +15,7 @@ import type { TransportBindings, TransportRoute } from "../types"; -import type { ParsedFlowRoute } from "../../routes/parseFlowRoute"; +import { decodePathSegments, type ParsedFlowRoute } from "../../routes/parseFlowRoute"; /** Stable provenance identifier for the built-in HTTP transport. */ export const HTTP_TRANSPORT_SOURCE = "http"; @@ -90,10 +90,12 @@ function pathFromContextOrUrl( return fromParam.split("/").filter((s) => s.length > 0); } + // The raw URL is still encoded, while framework params arrive decoded. + // Decode here so both reach `parseFlowRoute` in the same shape. const url = new URL(request.url); const prefix = basePath.endsWith("/") ? basePath : `${basePath}/`; if (!url.pathname.startsWith(prefix)) return []; - return url.pathname.slice(prefix.length).split("/").filter((s) => s.length > 0); + return decodePathSegments(url.pathname.slice(prefix.length)); } // Silence unused-symbol typecheck on optional re-import for tooling that diff --git a/packages/engine/test/router.test.ts b/packages/engine/test/router.test.ts index a3671b47a2..ac8882e1af 100644 --- a/packages/engine/test/router.test.ts +++ b/packages/engine/test/router.test.ts @@ -5,7 +5,11 @@ * compilation tests for the `:param` and trailing-`*` shapes. */ import { describe, expect, it } from "vitest"; -import { parseFlowRoute, type ParsedFlowRoute } from "../src/routes/parseFlowRoute"; +import { + decodePathSegments, + parseFlowRoute, + type ParsedFlowRoute +} from "../src/routes/parseFlowRoute"; import { compileTransportPattern, matchTransportRoute @@ -379,3 +383,43 @@ describe("compileTransportPattern", () => { expect(matchTransportRoute(matcher, "/wrong/path")).toBeNull(); }); }); + +describe("parseFlowRoute — segments arrive decoded, and are decoded no further", () => { + it("keeps a literal percent escape inside a flow kind", () => { + // Next hands `params.path` decoded once; an escaped seat address still + // carries `%5F` after that decode, and must resolve as written. + expect(parseFlowRoute("POST", ["org%5Fpentest%5Flab.helper", "actions", "run"])).toEqual({ + kind: "execute_action", + flowKind: "org%5Fpentest%5Flab.helper", + actionName: "run" + }); + }); + + it("keeps a decoded slash inside its segment", () => { + expect(parseFlowRoute("GET", ["sessions", "a/b"])).toEqual({ + kind: "get_session", + sessionId: "a/b" + }); + }); +}); + +describe("decodePathSegments — the raw-URL host's half of the contract", () => { + it("decodes each segment once, after splitting", () => { + expect(decodePathSegments("org%255Fpentest%255Flab.helper/actions/run")).toEqual([ + "org%5Fpentest%5Flab.helper", + "actions", + "run" + ]); + expect(decodePathSegments("sessions/a%2Fb")).toEqual(["sessions", "a/b"]); + }); + + it("keeps a segment that is not valid percent-encoding as written", () => { + expect(decodePathSegments("sessions/100%")).toEqual(["sessions", "100%"]); + }); + + it("round-trips through parseFlowRoute to the kind the client encoded", () => { + const kind = "acme.~alice%40acme%2Ecom.helper"; + const raw = `${encodeURIComponent(kind)}/actions/run`; + expect(parseFlowRoute("POST", decodePathSegments(raw))).toMatchObject({ flowKind: kind }); + }); +}); diff --git a/packages/next/test/escaped-segments.test.ts b/packages/next/test/escaped-segments.test.ts new file mode 100644 index 0000000000..2097d6789f --- /dev/null +++ b/packages/next/test/escaped-segments.test.ts @@ -0,0 +1,60 @@ +/** + * Next hands the catch-all route its `path` param already percent-decoded, + * once per segment. A flow kind that carries a literal `%XX` (a seat address + * whose org or user segment was escaped, e.g. `org%5Fpentest%5Flab.helper`) + * must reach the router intact, not decoded a second time. + */ +import { describe, expect, it } from "vitest"; +import { defineFlow, handler } from "@flow-state-dev/core"; +import { z } from "zod"; +import { createFlowState, inMemoryStores } from "@flow-state-dev/engine"; +import { createNextHandler } from "../src/createNextHandler"; + +const ESCAPED_ORG = "org%5Fpentest%5Flab.helper"; +const ESCAPED_USER = "acme.~alice%40acme%2Ecom.helper"; + +function runFlow(kind: string) { + return defineFlow({ + kind, + actions: { + run: { + inputSchema: z.object({}).passthrough(), + block: handler({ + name: "run", + inputSchema: z.object({}).passthrough(), + outputSchema: z.object({ ok: z.boolean() }), + execute: () => ({ ok: true }) + }) + } + } + })(); +} + +describe("createNextHandler — a flow kind that carries percent escapes", () => { + it.each([ + ["an escaped org segment", ESCAPED_ORG], + ["an escaped user segment", ESCAPED_USER] + ])("dispatches an action on %s, decoded once by Next", async (_label, kind) => { + const flowstate = createFlowState({ + flows: { seat: runFlow(kind) }, + stores: { default: { primary: inMemoryStores() } } + }); + const { POST } = createNextHandler(flowstate); + + // The URL the client builds (`encodeURIComponent(kind)`), and the + // `params.path` Next derives from it: one decodeURIComponent per segment. + const url = `http://localhost/api/flows/${encodeURIComponent(kind)}/actions/run`; + const nextPath = [decodeURIComponent(encodeURIComponent(kind)), "actions", "run"]; + + const res = await POST( + new Request(url, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ userId: "u1", input: {} }) + }), + { params: Promise.resolve({ path: nextPath }) } + ); + expect(res.status, await res.clone().text()).toBeLessThan(300); + await flowstate.dispose(); + }); +}); diff --git a/packages/node/src/app.ts b/packages/node/src/app.ts index dfc044b56e..cfe1aac1e5 100644 --- a/packages/node/src/app.ts +++ b/packages/node/src/app.ts @@ -14,6 +14,7 @@ */ import { Hono, type Context } from "hono"; import { + decodePathSegments, dispatchDedicatedRoute, disposeFlowApiRouter, isFlowState, @@ -69,11 +70,14 @@ function escapeRegExp(value: string): string { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } -/** Segments after the mount prefix, e.g. `/api/flows/chat/send` → `["chat","send"]`. */ +/** + * Decoded segments after the mount prefix, e.g. `/api/flows/chat/send` → + * `["chat","send"]`. `pathname` is the raw URL path; each segment is decoded + * once, the same shape Next hands the router as `params.path`. + */ function pathSegments(pathname: string, basePath: string): string[] { const prefix = new RegExp(`^${escapeRegExp(basePath)}/?`); - const after = pathname.replace(prefix, ""); - return after.split("/").filter((s) => s.length > 0); + return decodePathSegments(pathname.replace(prefix, "")); } /** @@ -154,7 +158,8 @@ export function createServerApp( // action handler (with its side effects) just to discard the body. return c.json({ error: "Method not allowed" }, 405); } - const path = pathSegments(c.req.path, basePath); + // From the raw URL, not `c.req.path`: Hono partly decodes that one. + const path = pathSegments(new URL(c.req.url).pathname, basePath); return handler(c.req.raw, { params: { path } }); }; diff --git a/packages/node/test/escaped-segments.test.ts b/packages/node/test/escaped-segments.test.ts new file mode 100644 index 0000000000..6565ab4cde --- /dev/null +++ b/packages/node/test/escaped-segments.test.ts @@ -0,0 +1,54 @@ +/** + * The Node host has only the raw URL, still percent-encoded. A flow kind that + * carries a literal `%XX` (a seat address whose org or user segment was + * escaped) must be decoded exactly once on the way to the router, the same as + * on Next, where the framework does that decode. + */ +import { describe, expect, it } from "vitest"; +import { createFlowState, inMemoryStores } from "@flow-state-dev/engine"; +import { defineFlow, handler } from "@flow-state-dev/core"; +import { z } from "zod"; +import { createServerApp } from "../src/app"; + +function runFlow(kind: string) { + return defineFlow({ + kind, + actions: { + run: { + inputSchema: z.object({}).passthrough(), + block: handler({ + name: "run", + inputSchema: z.object({}).passthrough(), + outputSchema: z.object({ ok: z.boolean() }), + execute: () => ({ ok: true }), + }), + }, + }, + })(); +} + +describe("createServerApp — a flow kind that carries percent escapes", () => { + it.each([ + ["an escaped org segment", "org%5Fpentest%5Flab.helper"], + ["an escaped user segment", "acme.~alice%40acme%2Ecom.helper"], + ["a plain kind", "plain-helper"], + ])("dispatches an action on %s from the raw URL", async (_label, kind) => { + const flowstate = createFlowState({ + flows: { seat: runFlow(kind) }, + stores: { default: { primary: inMemoryStores() } }, + }); + const server = createServerApp(flowstate); + try { + const res = await server.app.fetch( + new Request(`http://localhost/api/flows/${encodeURIComponent(kind)}/actions/run`, { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ userId: "u1", input: {} }), + }), + ); + expect(res.status, await res.clone().text()).toBeLessThan(300); + } finally { + await server.dispose(); + } + }); +}); diff --git a/packages/vercel/test/escaped-segments.test.ts b/packages/vercel/test/escaped-segments.test.ts new file mode 100644 index 0000000000..63e2b9e0bb --- /dev/null +++ b/packages/vercel/test/escaped-segments.test.ts @@ -0,0 +1,38 @@ +/** + * On Vercel the route is a Next catch-all, so `params.path` arrives already + * percent-decoded once. The handler forwards it untouched, and the engine's + * route parser must not decode it a second time: a flow kind that carries a + * literal `%XX` (an escaped seat address) has to resolve as written. + */ +import { describe, expect, it } from "vitest"; +import { parseFlowRoute, type FlowApiRouter, type FlowState } from "@flow-state-dev/engine"; +import { createVercelNextHandler } from "../src/next"; + +describe("createVercelNextHandler — a flow kind that carries percent escapes", () => { + it.each([ + ["an escaped org segment", "org%5Fpentest%5Flab.helper"], + ["an escaped user segment", "acme.~alice%40acme%2Ecom.helper"] + ])("routes %s to the kind Next decoded once", async (_label, kind) => { + const routed: unknown[] = []; + const router = { + GET: async () => new Response("ok"), + POST: async (req: Request, ctx: { params: { path?: string[] } }) => { + routed.push(parseFlowRoute(req.method, ctx.params.path)); + return new Response("ok"); + }, + PATCH: async () => new Response("ok"), + DELETE: async () => new Response("ok") + } as unknown as FlowApiRouter; + const { POST } = createVercelNextHandler({ + getRouter: async () => router + } as unknown as FlowState); + + const url = `http://localhost/api/flows/${encodeURIComponent(kind)}/actions/run`; + const nextPath = [decodeURIComponent(encodeURIComponent(kind)), "actions", "run"]; + await POST(new Request(url, { method: "POST" }), { + params: Promise.resolve({ path: nextPath }) + }); + + expect(routed).toEqual([{ kind: "execute_action", flowKind: kind, actionName: "run" }]); + }); +}); From d9df1f995530429acfc0750cab34e8654d065e59 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 01:10:41 +0000 Subject: [PATCH 08/28] chore(changeset): cover next and vercel for the decode-once fix; state parseFlowRoute's contract change (FIX-1757) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index 0390971b8f..38b4d3ebd9 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -3,6 +3,8 @@ "@flow-state-dev/core": minor "@flow-state-dev/engine": minor "@flow-state-dev/node": patch +"@flow-state-dev/next": patch +"@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are decoded exactly once on every host, so a flow kind carrying a literal `%XX` resolves on Next and Vercel as on Node: `parseFlowRoute` takes decoded segments, and the new `decodePathSegments` builds them from a raw URL path. +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes them), and the new `decodePathSegments` builds those from a raw URL path. From 5a44042ff4825603be1c0a87194f3d51d41fc16d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 01:24:28 +0000 Subject: [PATCH 09/28] fix(engine): never trim a decoded route segment; document well-formed org ids (FIX-1757) parseFlowRoute trimmed each segment after it became decoded, so a topic " report " read as "report" (the wrong item, or a false 404) on every host, Request.url fallback included. It now drops only empty segments. Tests on the params path and the Request.url fallback. The authentication docs (architecture and user-facing) now say an org id must be well-formed Unicode, matching isValidOrgId. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 2 +- apps/docs/docs/server/authentication.md | 9 ++-- docs/architecture/authentication.md | 3 +- packages/engine/src/routes/parseFlowRoute.ts | 8 ++-- .../http-transport-adapter-segments.test.ts | 45 +++++++++++++++++++ packages/engine/test/router.test.ts | 31 ++++++++++++- 6 files changed, 86 insertions(+), 12 deletions(-) create mode 100644 packages/engine/test/http-transport-adapter-segments.test.ts diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index 38b4d3ebd9..9b53fe899f 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -7,4 +7,4 @@ "@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes them), and the new `decodePathSegments` builds those from a raw URL path. +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path. diff --git a/apps/docs/docs/server/authentication.md b/apps/docs/docs/server/authentication.md index baf83a6506..b44f6a54f6 100644 --- a/apps/docs/docs/server/authentication.md +++ b/apps/docs/docs/server/authentication.md @@ -97,10 +97,11 @@ await runAction({ }); ``` -Organizations are opaque, nonempty strings. A whitespace-only id is rejected -rather than trimmed, and a valid one is stored exactly as given. That check is -`isValidOrgId`, exported from `@flow-state-dev/core`, so a resolver can apply -the same rule and refuse with its own message. +An organization id can be any string except an empty one, a whitespace-only +one, or one that isn't well-formed Unicode (a lone UTF-16 surrogate). Those are +rejected, not trimmed or repaired. Every other string is stored exactly as +given. `isValidOrgId`, exported from `@flow-state-dev/core`, applies the same +check, so a resolver can use it and refuse with its own message. A session's organization is fixed when the session is created, like its user. Reopening cannot move it; create a new session instead. diff --git a/docs/architecture/authentication.md b/docs/architecture/authentication.md index 2abb789059..ef5d17980b 100644 --- a/docs/architecture/authentication.md +++ b/docs/architecture/authentication.md @@ -71,7 +71,8 @@ identity above is still what that bucket is derived from, and an instance id is a storage coordinate, never an authorization. A custom resolver therefore owns the org boundary as well as the user one, -and it may not decline it. Returning no `orgId`, a blank one, or the reserved +and it may not decline it. Returning no `orgId`, a blank one, one that is not +well-formed Unicode (a lone UTF-16 surrogate), or the reserved `DEFAULT_ORG_ID` is refused with `401` — organization is unconditional, so there is no configuration under which a configured resolver may omit it. Org binding is fixed at session creation and immutable after: a later request diff --git a/packages/engine/src/routes/parseFlowRoute.ts b/packages/engine/src/routes/parseFlowRoute.ts index 5ec0eef279..12e3b9575c 100644 --- a/packages/engine/src/routes/parseFlowRoute.ts +++ b/packages/engine/src/routes/parseFlowRoute.ts @@ -50,7 +50,7 @@ export type ParsedFlowRoute = /** * Parses a catch-all method/path tuple into a typed flow route shape. - * Empty / whitespace-only segments are dropped so request paths that come + * Empty segments are dropped so request paths that come * in as `["", "sessions", "abc"]` from a Next.js catch-all match the same * way as `["sessions", "abc"]`. * @@ -65,9 +65,9 @@ export function parseFlowRoute( method: string, path: string[] | undefined ): ParsedFlowRoute { - const segments = (Array.isArray(path) ? path : []) - .map((segment) => segment.trim()) - .filter((segment) => segment.length > 0); + // Empty segments are dropped, but a segment's content is never trimmed: it + // is already decoded, so its whitespace is part of the id. + const segments = (Array.isArray(path) ? path : []).filter((segment) => segment.length > 0); const pathname = segments.length === 0 ? "/" : `/${segments.map(encodeURIComponent).join("/")}`; return matchFlowRoute(method, pathname); diff --git a/packages/engine/test/http-transport-adapter-segments.test.ts b/packages/engine/test/http-transport-adapter-segments.test.ts new file mode 100644 index 0000000000..8a5a16d7be --- /dev/null +++ b/packages/engine/test/http-transport-adapter-segments.test.ts @@ -0,0 +1,45 @@ +/** + * The HTTP adapter reaches `parseFlowRoute` two ways: with the decoded + * `params.path` a framework catch-all hands over, or, without one, from the + * raw `Request.url`. Both must resolve an id to exactly what the client + * encoded, whitespace and percent escapes included. A topic `" report "` + * trimmed to `"report"` reads the wrong item, or 404s. + */ +import { describe, expect, it } from "vitest"; +import { createHttpTransportAdapter } from "../src/transports/http/createHttpTransportAdapter"; +import { parseFlowRoute, type ParsedFlowRoute } from "../src/routes/parseFlowRoute"; + +const TOPIC = " report "; +const KIND = "org%5Fpentest%5Flab.helper"; + +async function routeVia(url: string, params: Record): Promise { + let parsed: ParsedFlowRoute | undefined; + const adapter = createHttpTransportAdapter({ + handle: async (request, { path }) => { + parsed = parseFlowRoute(request.method, path); + return new Response(null, { status: 204 }); + } + }); + const [route] = adapter.createBindings({} as never).routes; + await route!.handler(new Request(url), { params } as never); + return parsed!; +} + +const contentUrl = `http://localhost/api/flows/sessions/s1/resources/notes/${encodeURIComponent(TOPIC)}/content`; +const expected = { kind: "get_collection_item_content", sessionId: "s1", ref: "notes", topic: TOPIC }; + +describe("createHttpTransportAdapter — ids reach the route as the client encoded them", () => { + it("keeps a whitespace-bearing topic from the params path", async () => { + const path = ["sessions", "s1", "resources", "notes", TOPIC, "content"]; + expect(await routeVia(contentUrl, { path })).toEqual(expected); + }); + + it("keeps a whitespace-bearing topic from the Request.url fallback", async () => { + expect(await routeVia(contentUrl, {})).toEqual(expected); + }); + + it("keeps a percent escape in a flow kind from the Request.url fallback", async () => { + const url = `http://localhost/api/flows/${encodeURIComponent(KIND)}/requests/r1/stream`; + expect(await routeVia(url, {})).toEqual({ kind: "request_stream", flowKind: KIND, requestId: "r1" }); + }); +}); diff --git a/packages/engine/test/router.test.ts b/packages/engine/test/router.test.ts index ac8882e1af..62d42c7c98 100644 --- a/packages/engine/test/router.test.ts +++ b/packages/engine/test/router.test.ts @@ -311,11 +311,15 @@ describe("parseFlowRoute (router-backed)", () => { expect(parseFlowRoute("GET", [])).toEqual({ kind: "list_flows" }); }); - it("strips empty / whitespace segments", () => { - expect(parseFlowRoute("GET", ["", "sessions", " ", "sess_1"])).toEqual({ + it("strips empty segments, but a whitespace-only segment is an id", () => { + expect(parseFlowRoute("GET", ["", "sessions", "", "sess_1"])).toEqual({ kind: "get_session", sessionId: "sess_1" }); + // Decoded content is never trimmed, so " " is a session id here and + // the path has one segment too many for get_session. + expect(parseFlowRoute("GET", ["", "sessions", " ", "sess_1"])).toEqual({ kind: "not_found" }); + expect(parseFlowRoute("GET", ["sessions", " "])).toEqual({ kind: "get_session", sessionId: " " }); }); }); @@ -395,6 +399,24 @@ describe("parseFlowRoute — segments arrive decoded, and are decoded no further }); }); + it("keeps whitespace inside a decoded segment (a topic \" report \" is not \"report\")", () => { + expect( + parseFlowRoute("GET", ["sessions", " s1 ", "resources", "notes", " report ", "content"]) + ).toEqual({ + kind: "get_collection_item_content", + sessionId: " s1 ", + ref: "notes", + topic: " report " + }); + }); + + it("still drops empty segments, as a catch-all can hand them over", () => { + expect(parseFlowRoute("GET", ["", "sessions", "abc", ""])).toEqual({ + kind: "get_session", + sessionId: "abc" + }); + }); + it("keeps a decoded slash inside its segment", () => { expect(parseFlowRoute("GET", ["sessions", "a/b"])).toEqual({ kind: "get_session", @@ -417,6 +439,11 @@ describe("decodePathSegments — the raw-URL host's half of the contract", () => expect(decodePathSegments("sessions/100%")).toEqual(["sessions", "100%"]); }); + it("round-trips a whitespace-bearing topic from the raw URL", () => { + const raw = `sessions/s1/resources/notes/${encodeURIComponent(" report ")}/content`; + expect(parseFlowRoute("GET", decodePathSegments(raw))).toMatchObject({ topic: " report " }); + }); + it("round-trips through parseFlowRoute to the kind the client encoded", () => { const kind = "acme.~alice%40acme%2Ecom.helper"; const raw = `${encodeURIComponent(kind)}/actions/run`; From a584e0a83c8e7d753871910d52084e6dac7e1c96 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 01:34:40 +0000 Subject: [PATCH 10/28] docs(FIX-1757): decode segments in the standalone Node recipes; list every refused org id; workforce minor The Docker and Railway recipes built params.path from raw URL segments; the router now takes decoded ones, so they call decodePathSegments. seatAddress's docs (table, README, JSDoc) list every refused org id: empty, whitespace-only, not well-formed Unicode. Workforce is minor in the changeset: the "Org" member left the exported SegmentLabel union. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 4 ++-- apps/docs/docs/workforce/durable-hire.md | 2 +- apps/docs/guides/deploying-to-railway.md | 5 +++-- apps/docs/guides/deploying-with-docker.md | 5 +++-- packages/workforce/README.md | 2 +- packages/workforce/src/roster/address.ts | 8 +++++--- 6 files changed, 15 insertions(+), 11 deletions(-) diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index 9b53fe899f..b27574245c 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -1,5 +1,5 @@ --- -"@flow-state-dev/workforce": patch +"@flow-state-dev/workforce": minor "@flow-state-dev/core": minor "@flow-state-dev/engine": minor "@flow-state-dev/node": patch @@ -7,4 +7,4 @@ "@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path. +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path. diff --git a/apps/docs/docs/workforce/durable-hire.md b/apps/docs/docs/workforce/durable-hire.md index 1b655cc3a4..a0f251b807 100644 --- a/apps/docs/docs/workforce/durable-hire.md +++ b/apps/docs/docs/workforce/durable-hire.md @@ -25,7 +25,7 @@ All of these come from `@flow-state-dev/workforce`: | --- | --- | | `defineHiredRosterCollection()` | Declares the stored roster: an organization-scoped resource collection at `workforce/roster/*`, one row per hired seat. Takes no options. | | `defineHiredRosterPrivateCollection()` | Declares where a [user-owned seat](#hiring-a-seat-only-one-member-can-reach)'s row is written, at `workforce/roster/~/`. Server-side only, and a block that has it in `resources` reaches only the calling user's rows. | -| `seatAddress(orgId, seatId, ownerUserId?)` | The address a hired seat answers on. Org-visible seats are `.`. A user-owned seat is `.~.`, so two people can hire the same seat id. The organization id and the user are percent-escaped, as [The organization has to come from the credential](#the-organization-has-to-come-from-the-credential) spells out. Throws when the organization id is empty, or when the seat id is empty or starts with `~`. | +| `seatAddress(orgId, seatId, ownerUserId?)` | The address a hired seat answers on. Org-visible seats are `.`. A user-owned seat is `.~.`, so two people can hire the same seat id. The organization id and the user are percent-escaped, as [The organization has to come from the credential](#the-organization-has-to-come-from-the-credential) spells out. Throws when the organization id is empty, whitespace-only, or not well-formed Unicode (a lone UTF-16 surrogate), or when the seat id is empty or starts with `~`. | | `hireWorkforce(records, { kinds })` | Turns records into configured flow copies, one per record. The same call the file-declared roster goes through. | | `reloadHiredSeats({ stores, orgIds, kinds })` | Reads every stored row back at the next start and hires what it names. Returns `{ seats, problems, byOrg }`. It registers nothing. | | `createSeatHireBlocks(options)` | Returns `{ hire, fire, brokenSeats, rehire }`: two handlers that run the whole hire and fire sequence, and two that list and [repair a seat whose kind is gone](#repairing-a-seat-whose-kind-is-gone). Mount them as a flow's actions. See [the ready-made handlers](#the-ready-made-hire-and-fire-handlers). | diff --git a/apps/docs/guides/deploying-to-railway.md b/apps/docs/guides/deploying-to-railway.md index bd91986ab2..beb92dab20 100644 --- a/apps/docs/guides/deploying-to-railway.md +++ b/apps/docs/guides/deploying-to-railway.md @@ -26,7 +26,7 @@ The framework's router uses Web standard `Request`/`Response` objects. You bridg ```ts title="src/server.ts" import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; -import { createFlowState, filesystemStores } from "@flow-state-dev/engine"; +import { createFlowState, decodePathSegments, filesystemStores } from "@flow-state-dev/engine"; import myFlow from "./flows/my-flow/flow.js"; const port = parseInt(process.env.PORT ?? "3000", 10); @@ -87,7 +87,8 @@ async function handleFlowRequest( // Extract path after /api/flows const pathAfterPrefix = url.replace(/^\/api\/flows\/?/, ""); const [pathPart] = pathAfterPrefix.split("?", 2); - const pathSegments = pathPart.split("/").filter((s) => s.length > 0); + // The router takes decoded segments, one decode each, as Next hands them. + const pathSegments = decodePathSegments(pathPart); // Read body for POST/PATCH let body: string | undefined; diff --git a/apps/docs/guides/deploying-with-docker.md b/apps/docs/guides/deploying-with-docker.md index cedc703ed6..70cbacde7d 100644 --- a/apps/docs/guides/deploying-with-docker.md +++ b/apps/docs/guides/deploying-with-docker.md @@ -83,7 +83,7 @@ Use the same standalone server pattern from the [Railway guide](/guides/deployin ```ts title="src/server.ts" import { createServer, type IncomingMessage, type ServerResponse } from "node:http"; -import { createFlowState } from "@flow-state-dev/engine"; +import { createFlowState, decodePathSegments } from "@flow-state-dev/engine"; import { sqliteStores } from "@flow-state-dev/store-sqlite"; import myFlow from "./flows/my-flow/flow.js"; @@ -140,7 +140,8 @@ async function handleFlowRequest( const method = (req.method ?? "GET").toUpperCase(); const pathAfterPrefix = url.replace(/^\/api\/flows\/?/, ""); const [pathPart] = pathAfterPrefix.split("?", 2); - const pathSegments = pathPart.split("/").filter((s) => s.length > 0); + // The router takes decoded segments, one decode each, as Next hands them. + const pathSegments = decodePathSegments(pathPart); let body: string | undefined; if (method === "POST" || method === "PATCH") { diff --git a/packages/workforce/README.md b/packages/workforce/README.md index c803158df0..4a61d5e5a5 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2184,7 +2184,7 @@ before fire removed inventory rows is left out that way. | `hiredSeatRowSchema` / `HiredSeatRow` | One roster row — `{ seatId, flow, settings, instructions, owningOrgId, ownerUserId, pendingRepair, incarnation }`. `owningOrgId`, `ownerUserId`, `pendingRepair` (set only while a `rehire` is unfinished) and `incarnation` (the hire or re-hire that wrote it) are nullable and default to `null`. `pendingRepair` is server-only; `incarnation` is published to browsers by `defineHiredRosterCollection`, beside `seatId`, `flow` and `instructions`, so a browser can join a roster row to its inventory row. The envelope is closed when parsed; the roster collections store it with unknown keys kept, so a key a newer version wrote survives this version's rewrite of the row (a re-hire). `settings` is a passthrough bag belonging to the kind's own schema. | | `HIRED_ROSTER_PREFIX` | The roster's storage prefix, `"workforce/roster/"`. Moving it strands every roster already written. | | `HIRED_ROSTER_BROWSER_PATTERN` / `HIRED_ROSTER_PRIVATE_PATTERN` | The two roster collections' patterns, `"workforce/roster/*"` and `"workforce/roster/[owner]/[seat]"`. Like the prefix, they spell stored keys. | -| `seatAddress(orgId, seatId, ownerUserId?)` / `splitSeatAddress(orgId, address)` | Join an organization and a seat id into the address a hired seat answers on, and take the seat id back out. Org-visible is `.`. User-owned is `.~.`, with the user escaped. The organization is percent-escaped like the user (`seatAddress("org_pentest_lab", "helper")` is `org%5Fpentest%5Flab.helper`). The pin is the hire row, not the address. `seatAddress` throws when the organization id is empty, or when the seat id is empty or starts with `~`. `splitSeatAddress` returns `undefined` when the address isn't under that organization. Both are also exported from `@flow-state-dev/workforce/browser`. | +| `seatAddress(orgId, seatId, ownerUserId?)` / `splitSeatAddress(orgId, address)` | Join an organization and a seat id into the address a hired seat answers on, and take the seat id back out. Org-visible is `.`. User-owned is `.~.`, with the user escaped. The organization is percent-escaped like the user (`seatAddress("org_pentest_lab", "helper")` is `org%5Fpentest%5Flab.helper`). The pin is the hire row, not the address. `seatAddress` throws when the organization id is empty, whitespace-only, or not well-formed Unicode (a lone UTF-16 surrogate), or when the seat id is empty or starts with `~`. `splitSeatAddress` returns `undefined` when the address isn't under that organization. Both are also exported from `@flow-state-dev/workforce/browser`. | | `newIncarnation()` / `tagIncarnation(seat, incarnation)` | For a host that writes roster rows itself rather than through `createSeatHireCapability`. Stamp each hire's row with `toHiredSeatRow({ ..., incarnation: newIncarnation() })` and tag the seat minted from it with the same id. A fire then removes only the inventory row carrying that id, so a replacement hired at the same address keeps its own. A row written with no incarnation can't be told from a replacement written the same way. | | `toHiredSeatRow(input)` / `parseHiredSeatRow(value)` | Build a row from what a hire supplied, and read a stored value back into one. `parseHiredSeatRow` returns `{ row }` or `{ problem }` — it never throws and never rewrites the stored value. | | `hiredRosterStorageKey(row)` | `seatId` for an org-visible row, `~/` for a user-owned one. The user id is escaped, so a `/` in it stays one segment. | diff --git a/packages/workforce/src/roster/address.ts b/packages/workforce/src/roster/address.ts index 90cb2c1896..ebd87fa1f9 100644 --- a/packages/workforce/src/roster/address.ts +++ b/packages/workforce/src/roster/address.ts @@ -29,8 +29,9 @@ import { encodeUserSegment, isValidOrgId } from "@flow-state-dev/core/types"; * shape: dotted for a team seat (`"."`), bare for an org seat * (`""`). Only the leading segment has to be dot-free. * - * @throws when the org id or the seat id is empty, or the seat id starts with - * `~` (that marker is the user-owned form). + * @throws when the org id is empty, whitespace-only, or not well-formed + * Unicode (a lone UTF-16 surrogate; see `isValidOrgId`), or when the seat id + * is empty or starts with `~` (that marker is the user-owned form). */ export function seatAddress( orgId: string, @@ -61,7 +62,8 @@ export function seatAddress( * every other character (`_`, `.`, `%`, upper case) is percent-encoded, so the * result holds no `.` and two org ids never share one. * - * @throws when the org id is empty. + * @throws when the org id is empty, whitespace-only, or not well-formed + * Unicode (a lone UTF-16 surrogate), the ids `isValidOrgId` refuses. */ function orgSegment(orgId: string): string { if (orgId.length === 0) { From 37c0d738dba62c8f6ecbc1022b13a132ea0cc804 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 01:44:38 +0000 Subject: [PATCH 11/28] test(goal),docs: drive the default-org seat over HTTP with a control that can fail (FIX-1757) The reload goal now computes the default-org seat's expected address from the documented escape rule (not seatAddress), and calls it over HTTP with no identity on a resolver-less restarted host. Its control now breaks default-org admission in instance-pin.ts and fails leg (c) with a 404. The authentication architecture doc no longer says the default resolver names no organization: the runtime supplies DEFAULT_ORG_ID, which a default-org pin admits on a resolver-less host. The workforce README's "cannot hire" line is corrected the same way. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- docs/architecture/authentication.md | 2 +- .../goal.md | 9 ++-- .../run.mts | 46 ++++++++++++++++--- packages/workforce/README.md | 2 +- 4 files changed, 48 insertions(+), 11 deletions(-) diff --git a/docs/architecture/authentication.md b/docs/architecture/authentication.md index ef5d17980b..71d4d81102 100644 --- a/docs/architecture/authentication.md +++ b/docs/architecture/authentication.md @@ -135,7 +135,7 @@ The switch is exhaustive over `ParsedFlowRoute["kind"]`. An owner-pinned instance is registered with `register(flow, { pin })`, where the pin is `{ orgId, userId? }`. The registering code supplies the pin; it never comes from the address. Workforce pins every instance it hires this way, and its `registerHiredSeat` refuses one that arrives with no pin. `create_session` and a session-less `execute_action` compare the caller to the pin before the acknowledgement and answer a mismatch with `404 Unknown flow`, the same sentence an address this process does not hold gets. An internal dispatch to a pinned instance is refused at the dispatch seam, before a child session is written: a sending principal outside the pin gets `flow-not-found`, the same refusal an unregistered address gets (see [Dispatched Work](./dispatched-work.md)). Execution admission is the backstop. Every run, including resume and retry, compares the bound session to the pin before any block and throws `InstancePinMismatchError` on a mismatch. Its `reason` is `"owning-org"` or `"owning-user"`, the half of the pin the caller missed; the organization is compared first. An instance registered without a pin stays shared. -The comparison uses the principal the host resolved. On the framework default resolver that principal names no organization, so opening a pinned instance answers `404 Unknown flow`, even for its owner. Install a resolver that verifies the organization where the instance is resolved: at the host when every flow authenticates, or on the instance itself (its `authentication.resolvePrincipal`) in a mixed app whose other flows stay on the development default. A host resolver that merely delegates to the default does not work, because the engine recognises the development default by the resolver it runs (`isDefaultBodyUserIdPrincipalResolver`), not by the principal it returns: a tokenless caller then gets 401 on actions (no verified organization) and on the management routes and listings (enforcement switches on). With the resolver on the instance, the flow catalog lists it to a caller that resolver admits and the pin matches, because the catalog resolves each pinned instance through its own resolver, as the doors do. The host listings (`list_sessions`, `active_requests`) show its sessions and in-flight requests to the same caller, because they judge each of its rows through its resolver too. The pin also picks where the instance stores a person's shared user data: one cell per (pin org, person), never the person's cross-org cell (FIX-1538, [State and Scopes](./state-and-scopes.md#the-owner-pinned-cell)). +The comparison uses the principal the host resolved. On the framework default resolver the runtime supplies `DEFAULT_ORG_ID` as that principal's organization, so an instance pinned to `DEFAULT_ORG_ID` (a seat hired with no resolver in play, for instance) admits callers on a host where neither the instance nor the host configures a resolver, and an instance pinned to any other organization answers `404 Unknown flow` there, even for its owner. A configured resolver can never return `DEFAULT_ORG_ID` (401), so a default-org pin admits no caller once one applies. For any other pin, install a resolver that verifies the organization where the instance is resolved: at the host when every flow authenticates, or on the instance itself (its `authentication.resolvePrincipal`) in a mixed app whose other flows stay on the development default. A host resolver that merely delegates to the default does not work, because the engine recognises the development default by the resolver it runs (`isDefaultBodyUserIdPrincipalResolver`), not by the principal it returns: a tokenless caller then gets 401 on actions (no verified organization) and on the management routes and listings (enforcement switches on). With the resolver on the instance, the flow catalog lists it to a caller that resolver admits and the pin matches, because the catalog resolves each pinned instance through its own resolver, as the doors do. The host listings (`list_sessions`, `active_requests`) show its sessions and in-flight requests to the same caller, because they judge each of its rows through its resolver too. The pin also picks where the instance stores a person's shared user data: one cell per (pin org, person), never the person's cross-org cell (FIX-1538, [State and Scopes](./state-and-scopes.md#the-owner-pinned-cell)). Enforcement is off when the host resolver is the framework default **and** no registered flow configures its own resolver. A flow-scoped route whose diff --git a/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md b/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md index 1fa205d2ce..40d41634fa 100644 --- a/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md +++ b/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md @@ -6,14 +6,15 @@ **Signal:** against `createFlowState`'s HTTP router, one in-memory store shared by three app instances (dev, signed-in, restarted), no model. (a) The dev app's `hire` action, run with no identity, completes and leaves a roster row under `DEFAULT_ORG_ID`. (b) The signed-in app's `hire` action completes for the named org. -(c) `reloadHiredSeats` over `[DEFAULT_ORG_ID, ]` resolves. It returns `.` and the dev row at `seatAddress(DEFAULT_ORG_ID, )`, names no default-org problem, and the named seat registers on the restarted app and completes an `answer` run. +(c) `reloadHiredSeats` over `[DEFAULT_ORG_ID, ]` resolves. It returns `.` and the dev row at the escaped default-org address, written out in the runner from the documented escape rule (not taken from `seatAddress`), and names no default-org problem. Both seats then answer an `answer` run over HTTP: the named seat on the restarted signed-in app, and the dev seat on a restarted app with no resolver, called with no identity at its escaped address. (d) A row in the named org's cell stamped `owningOrgId: ` is a `cannot be registered under` problem, and no seat with its id is returned. **Anti-game:** a hollow pass would check that `problems` is non-empty, which holds when reload names both bad rows and returns nothing else. So the check MUST see the named org's seat come back and answer a real run after the restart, MUST see the dev row named by its org and key, and MUST see the stray row refused rather than minted. It must not grade the address string alone. **Model:** n/a — handlers only. The property is which stored rows come back as seats. **Run:** `pnpm tsx goals/hire-plane/reload-survives-an-unaddressable-row/run.mts` (build `@flow-state-dev/workforce` first; the goal imports its `dist`). -**Controls:** none in the runner. The red state is a source revert, so it fails for the reason the bug fails. -- Revert `packages/workforce/src/roster/reload.ts` to `ffe2b6e26` (the manifest build outside the per-row guard), rebuild workforce. Must FAIL leg (c) only. +**Controls:** none in the runner. The red state is a source edit, so it fails for the reason the bug fails. +- Break default-org admission: in `packages/engine/src/context/instance-pin.ts` `pinMismatchReason`, return `"owning-org"` whenever `pin.orgId === DEFAULT_ORG_ID`, then rebuild engine. Must FAIL leg (c) only, with the dev seat answering `404 Unknown flow` at its escaped address. +- (Historical, pre-FIX-1757) reverting `packages/workforce/src/roster/reload.ts` to `ffe2b6e26` failed leg (c) by rejecting the reload. Since the default org became addressable, that revert no longer turns this goal red. ## Verdict log | Date | Commit | Model | Verdict | Notes | @@ -21,3 +22,5 @@ | 2026-09-23 | `636542bc6` with `reload.ts` reverted to `ffe2b6e26`, then restored | n/a | FAIL (expected) | **Leg (c) only:** `reload rejected, so no org's seats came back: Organization id "__fsd_default_org__" must be lowercase letters, digits, and single hyphens ...`. Legs (a) and (b) completed, so the dev hire really does write under the default org through the HTTP path. Restored with `git checkout HEAD -- packages/workforce/src/roster/reload.ts` and rebuilt. | | 2026-09-23 | `636542bc6` (fix present) | n/a | PASS | Exit 0. Dev hire stored under `__fsd_default_org__`; reload over `[__fsd_default_org__, acme]` returned `["acme.support.ada"]` and 2 problems; `acme.support.ada` answered after restart; default-org row named as `organization "__fsd_default_org__", row "workforce/roster/lead"`; stray row refused as `owned by organization "globex" and cannot be registered under "acme"`. | | 2026-10-04 | `d5225ecd8` + FIX-1757 (org escaped into the address) | n/a | PASS | Leg (c) re-pointed: the default org is now addressable. Reload returned `["%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead","acme.support.ada"]` and 1 problem (the stray row, refused as before); `acme.support.ada` answered after restart. | +| 2026-10-04 | FIX-1757 `a584e0a83` + this change, default-org admission broken in `instance-pin.ts`, then restored | n/a | FAIL (expected) | **Leg (c) only:** `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead did not answer over HTTP on the resolver-less host: {"http":404,"detail":{"error":"Unknown flow \"%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead\""}}`. Restored and rebuilt. | +| 2026-10-04 | FIX-1757 `a584e0a83` + this change | n/a | PASS | Exit 0. The dev seat came back at `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead` (expected address computed independently of `seatAddress`) and answered over HTTP with no identity on a resolver-less host; `acme.support.ada` answered on the signed-in host; stray row refused. | diff --git a/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts b/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts index 3953b6279e..dd46ad16a0 100644 --- a/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts +++ b/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts @@ -16,7 +16,6 @@ import { createFlowState, inMemoryStores } from "@flow-state-dev/engine"; import { defineHiredRosterCollection, reloadHiredSeats, - seatAddress, toHiredSeatRow, workerConfigSchema, } from "@flow-state-dev/workforce"; @@ -41,6 +40,21 @@ type Router = { const fixture = loadFixture(import.meta.url); +/** + * The address a hire under `orgId` should answer on, written out here from + * the documented rule (`[a-z0-9-]` kept, every other UTF-8 byte as `%XX`) + * rather than taken from `seatAddress`, the helper under test. + */ +function expectedAddress(orgId: string, seatId: string): string { + const org = [...new TextEncoder().encode(orgId)] + .map((byte) => { + const ch = String.fromCharCode(byte); + return /[a-z0-9-]/.test(ch) ? ch : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`; + }) + .join(""); + return `${org}.${seatId}`; +} + /** A roster row as the store's JSON shape — the same cast the seat-hire writer makes. */ function asStored(row: ReturnType): JsonObject { return row as unknown as JsonObject; @@ -114,7 +128,9 @@ async function call( headers["x-verified-org"] = who.org; } const response = await router[method]( - new Request(`http://goal/api/flows/${path.join("/")}`, { + // The URL as a client builds it (each segment encoded); `params.path` as + // Next hands it (each decoded once). + new Request(`http://goal/api/flows/${path.map(encodeURIComponent).join("/")}`, { method, headers, ...(body === undefined ? {} : { body: JSON.stringify(body) }), @@ -229,7 +245,7 @@ await runGoal(async () => { if (!ids.includes(namedAddress)) fail("c", `reload did not return ${namedAddress}; got ${JSON.stringify(ids)}`); // The dev hire comes back as a seat: the default org is escaped into its // address rather than refused. - const devAddress = seatAddress(DEFAULT_ORG_ID, fixture.devSeatId); + const devAddress = expectedAddress(DEFAULT_ORG_ID, fixture.devSeatId); const devProblem = reload.problems.find((problem) => problem.includes(DEFAULT_ORG_ID)); if (!ids.includes(devAddress) || devProblem !== undefined) { fail( @@ -246,9 +262,26 @@ await runGoal(async () => { fail("d", `the row stamped for ${fixture.strayOrg} was minted: ${JSON.stringify(ids)}`); } - // (c) The reloaded seat is not just returned; it registers and answers. + // (c) The reloaded seats are not just returned; they register and answer. + // The named org's on the signed-in host; the dev seat on a host with + // no resolver, the only place a default-org pin admits anyone. + const devRestarted = createFlowState({ + flows: {}, + stores: { default: { primary: stores } }, + }); for (const seat of reload.seats) { - restarted.register(seat as FlowInstance, { pin: seat.ownerPin ?? { orgId: fixture.namedOrg } }); + const pin = seat.ownerPin ?? { orgId: fixture.namedOrg }; + (pin.orgId === DEFAULT_ORG_ID ? devRestarted : restarted).register(seat as FlowInstance, { pin }); + } + const devAnswered = await runAction( + (await devRestarted.getRouter()) as Router, + devAddress, + fixture.devUser, + "answer", + { tag: fixture.marker }, + ); + if (devAnswered.outcome !== "completed") { + fail("c", `${devAddress} did not answer over HTTP on the resolver-less host: ${JSON.stringify(devAnswered)}`); } const restartedRouter = (await restarted.getRouter()) as Router; const answered = await runAction( @@ -269,7 +302,8 @@ await runGoal(async () => { evidence: `dev hire stored under ${DEFAULT_ORG_ID}; reload over [${DEFAULT_ORG_ID}, ${fixture.namedOrg}] ` + `returned ${JSON.stringify(ids)} and ${reload.problems.length} problems; ` + - `${namedAddress} answered after restart; default-org row came back as ${devAddress}; ` + + `${namedAddress} answered after restart; default-org row came back as ${devAddress} ` + + `and answered over HTTP with no identity; ` + `stray row refused: ${strayProblem}`, }; } diff --git a/packages/workforce/README.md b/packages/workforce/README.md index 4a61d5e5a5..e51c6c4fc6 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2115,7 +2115,7 @@ before fire removed inventory rows is left out that way. | `createWorkforceCapability({ roster, inventory, hiredRoster?, sources? })` | The discovery door. Installs the seat and channel sources plus whatever other domains' sources you pass, and contributes one control tool, `discover`. Pass `hiredRoster` so a runtime hire is listed the same way a file-declared seat is. Omit it and `discover` lists only file-declared seats. | | `workforceManifestSources({ roster, inventory, hiredRoster? })` | The seat and channel sources on their own, for an app assembling its own manifest registry. Same `hiredRoster?` meaning as `createWorkforceCapability`. | | `createSeatHireCapability({ kinds, register, unregister, kindAt?, instanceAt?, allowKinds?, refuseRosterAdmin?, channelBoards?, askBefore? })` | Puts catalog tools `hire`, `fire`, `brokenSeats` and `rehire` on a worker kind; `askBefore` puts `hire` and/or `fire` behind a person's approval, and `rehire` is always behind one. Compose it into `defineAgentWorkerFlow({ uses })`. A seat calls them by selecting `seat-hire: [tools]` with no `tools:` line, or by naming them in `tools:`; `tools: []` withholds them. Writes the hired roster and `inventory/seats/*`. The seat is hired in the caller's organization; a body `orgId` is ignored. The roster row carries that organization as `owningOrgId`, so a copy read under another organization is a reload problem rather than a seat. `register` receives `{ orgId, userId? }` from the hire row's roster owner; hire refuses rather than omit it. | -| `createSeatHireBlocks({ kinds, register, unregister, kindAt?, instanceAt?, allowKinds?, refuseRosterAdmin?, channelBoards? })` | Returns `{ hire, fire, brokenSeats, rehire }`; `hire` and `fire` are the handlers behind `createSeatHireCapability`'s catalog tools, for mounting as a flow's actions, where they never ask for approval. Same options, inputs, outputs and refusals. Declare `defineHiredRosterCollection()` under `HIRED_ROSTER_RESOURCE` and `defineSeatInventoryCollection()` under `SEAT_INVENTORY_RESOURCE` on that flow. The organization comes from the session's principal; a body `orgId` is ignored, and a session whose principal names no organization cannot hire. Each hire and re-hire stamps a fresh `incarnation` on its roster row, its inventory row and the seat it mints; `fire` deletes only that incarnation's inventory row and, given `instanceAt` (the registry's instance at an address), releases only the seat minted from the row. Without `instanceAt` those checks fall back to the kind, and a `rehire` retry that finds the address already served is refused. `refuseRosterAdmin: true` refuses a hire or re-hire whose settings would give the seat the roster tools; off by default. | +| `createSeatHireBlocks({ kinds, register, unregister, kindAt?, instanceAt?, allowKinds?, refuseRosterAdmin?, channelBoards? })` | Returns `{ hire, fire, brokenSeats, rehire }`; `hire` and `fire` are the handlers behind `createSeatHireCapability`'s catalog tools, for mounting as a flow's actions, where they never ask for approval. Same options, inputs, outputs and refusals. Declare `defineHiredRosterCollection()` under `HIRED_ROSTER_RESOURCE` and `defineSeatInventoryCollection()` under `SEAT_INVENTORY_RESOURCE` on that flow. The organization comes from the session's principal; a body `orgId` is ignored, and with no resolver in play the session is in the default organization, so the hire lands there. Each hire and re-hire stamps a fresh `incarnation` on its roster row, its inventory row and the seat it mints; `fire` deletes only that incarnation's inventory row and, given `instanceAt` (the registry's instance at an address), releases only the seat minted from the row. Without `instanceAt` those checks fall back to the kind, and a `rehire` retry that finds the address already served is refused. `refuseRosterAdmin: true` refuses a hire or re-hire whose settings would give the seat the roster tools; off by default. | | `registerHiredSeat(register, seat, pin)` | The hire writer's register path. Refuses when `pin` has no `orgId`. The pin is the hire row's roster owner, not the address. | | `HiredSeatOwnerPin` | Another name for core's `InstanceOwnerPin`: `{ orgId, userId? }`, with `userId` present only for a user-owned hire row. Either name works wherever the other is expected. | | `SEAT_HIRE_CAPABILITY` | The capability name, `"seat-hire"`. | From 3a5222e7c60df14adc91d9d4e81157b0a5759b1d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 01:50:04 +0000 Subject: [PATCH 12/28] test(goal): align the reload goal's contract with its runner (FIX-1757) The anti-game clause now requires the independently computed escaped default-org address and the resolver-less HTTP answer, not the old problem-entry wording; the signal counts four app instances, the run note names every package to build, and the verdict rows cite the commit. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .../reload-survives-an-unaddressable-row/goal.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md b/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md index 40d41634fa..dcf744c251 100644 --- a/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md +++ b/goals/hire-plane/reload-survives-an-unaddressable-row/goal.md @@ -3,15 +3,15 @@ **Issue:** FIX-1536 **Outcome:** An app with no authentication that hires a seat at runtime does not take the rest of the roster down at the next boot. That hire lands under the development organization, and comes back as a seat at that organization's escaped address (FIX-1757; before it, the id could not be an address and the row came back as one named problem). Every other organization's seats still reload, register and answer. A row stamped for a different organization is still refused, not minted. **Input:** `fixtures/input.json` — the signed-in org and user, the dev user, the two seat ids, the stray org and seat id, and a marker. Held-out: every id is read from the fixture and graded against the reload result and a real run on the reloaded seat. Swapping any of them must still pass. -**Signal:** against `createFlowState`'s HTTP router, one in-memory store shared by three app instances (dev, signed-in, restarted), no model. +**Signal:** against `createFlowState`'s HTTP router, one in-memory store shared by four app instances (dev, signed-in, and a restart of each: one with the signed-in resolver, one with none), no model. (a) The dev app's `hire` action, run with no identity, completes and leaves a roster row under `DEFAULT_ORG_ID`. (b) The signed-in app's `hire` action completes for the named org. (c) `reloadHiredSeats` over `[DEFAULT_ORG_ID, ]` resolves. It returns `.` and the dev row at the escaped default-org address, written out in the runner from the documented escape rule (not taken from `seatAddress`), and names no default-org problem. Both seats then answer an `answer` run over HTTP: the named seat on the restarted signed-in app, and the dev seat on a restarted app with no resolver, called with no identity at its escaped address. (d) A row in the named org's cell stamped `owningOrgId: ` is a `cannot be registered under` problem, and no seat with its id is returned. -**Anti-game:** a hollow pass would check that `problems` is non-empty, which holds when reload names both bad rows and returns nothing else. So the check MUST see the named org's seat come back and answer a real run after the restart, MUST see the dev row named by its org and key, and MUST see the stray row refused rather than minted. It must not grade the address string alone. +**Anti-game:** a hollow pass would check that `problems` is non-empty, which holds when reload names both bad rows and returns nothing else. So the check MUST see the named org's seat come back and answer a real run after the restart, MUST see the dev row come back at the escaped default-org address the runner computes from the documented rule (never from `seatAddress`, the helper under test) and answer an `answer` run over HTTP with no identity on the resolver-less restart, and MUST see the stray row refused rather than minted. It must not grade the address string alone. **Model:** n/a — handlers only. The property is which stored rows come back as seats. -**Run:** `pnpm tsx goals/hire-plane/reload-survives-an-unaddressable-row/run.mts` (build `@flow-state-dev/workforce` first; the goal imports its `dist`). +**Run:** `pnpm tsx goals/hire-plane/reload-survives-an-unaddressable-row/run.mts` (build `@flow-state-dev/core`, `@flow-state-dev/engine` and `@flow-state-dev/workforce` first; the goal imports their `dist`). **Controls:** none in the runner. The red state is a source edit, so it fails for the reason the bug fails. - Break default-org admission: in `packages/engine/src/context/instance-pin.ts` `pinMismatchReason`, return `"owning-org"` whenever `pin.orgId === DEFAULT_ORG_ID`, then rebuild engine. Must FAIL leg (c) only, with the dev seat answering `404 Unknown flow` at its escaped address. - (Historical, pre-FIX-1757) reverting `packages/workforce/src/roster/reload.ts` to `ffe2b6e26` failed leg (c) by rejecting the reload. Since the default org became addressable, that revert no longer turns this goal red. @@ -22,5 +22,5 @@ | 2026-09-23 | `636542bc6` with `reload.ts` reverted to `ffe2b6e26`, then restored | n/a | FAIL (expected) | **Leg (c) only:** `reload rejected, so no org's seats came back: Organization id "__fsd_default_org__" must be lowercase letters, digits, and single hyphens ...`. Legs (a) and (b) completed, so the dev hire really does write under the default org through the HTTP path. Restored with `git checkout HEAD -- packages/workforce/src/roster/reload.ts` and rebuilt. | | 2026-09-23 | `636542bc6` (fix present) | n/a | PASS | Exit 0. Dev hire stored under `__fsd_default_org__`; reload over `[__fsd_default_org__, acme]` returned `["acme.support.ada"]` and 2 problems; `acme.support.ada` answered after restart; default-org row named as `organization "__fsd_default_org__", row "workforce/roster/lead"`; stray row refused as `owned by organization "globex" and cannot be registered under "acme"`. | | 2026-10-04 | `d5225ecd8` + FIX-1757 (org escaped into the address) | n/a | PASS | Leg (c) re-pointed: the default org is now addressable. Reload returned `["%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead","acme.support.ada"]` and 1 problem (the stray row, refused as before); `acme.support.ada` answered after restart. | -| 2026-10-04 | FIX-1757 `a584e0a83` + this change, default-org admission broken in `instance-pin.ts`, then restored | n/a | FAIL (expected) | **Leg (c) only:** `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead did not answer over HTTP on the resolver-less host: {"http":404,"detail":{"error":"Unknown flow \"%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead\""}}`. Restored and rebuilt. | -| 2026-10-04 | FIX-1757 `a584e0a83` + this change | n/a | PASS | Exit 0. The dev seat came back at `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead` (expected address computed independently of `seatAddress`) and answered over HTTP with no identity on a resolver-less host; `acme.support.ada` answered on the signed-in host; stray row refused. | +| 2026-10-04 | FIX-1757 `37c0d738d`, default-org admission broken in `instance-pin.ts`, then restored | n/a | FAIL (expected) | **Leg (c) only:** `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead did not answer over HTTP on the resolver-less host: {"http":404,"detail":{"error":"Unknown flow \"%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead\""}}`. Restored and rebuilt. | +| 2026-10-04 | FIX-1757 `37c0d738d` | n/a | PASS | Exit 0. The dev seat came back at `%5F%5Ffsd%5Fdefault%5Forg%5F%5F.lead` (expected address computed independently of `seatAddress`) and answered over HTTP with no identity on a resolver-less host; `acme.support.ada` answered on the signed-in host; stray row refused. | From 36c795a3af4e70261583c467ae5fb1696d2dafac Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 02:03:09 +0000 Subject: [PATCH 13/28] fix(workforce,node,engine): splitSeatAddress never throws; strip an encoded basePath; name FIX-1757 in the changeset - splitSeatAddress returns undefined for every org id seatAddress refuses (empty, whitespace-only, lone surrogate) instead of throwing. - The Node host and the HTTP adapter's Request.url fallback strip the basePath in its encoded form, as URL.pathname carries it, so a base like "/api/my path" comes off before the rest is decoded. - The reload goal escapes the named org's address by the documented rule, so a fixture org like org_pentest_lab still passes. - The changeset names FIX-1757 (it only passed the ref check because "UTF-16" matches the issue-ref pattern). Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 2 +- .../reload-survives-an-unaddressable-row/run.mts | 4 ++-- .../transports/http/createHttpTransportAdapter.ts | 4 +++- .../test/http-transport-adapter-segments.test.ts | 12 +++++++++++- packages/node/src/app.ts | 7 +++++-- packages/node/test/app.test.ts | 9 +++++++++ packages/workforce/src/roster/address.ts | 7 +++++-- packages/workforce/test/roster.test.ts | 9 +++++++++ 8 files changed, 45 insertions(+), 9 deletions(-) diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index b27574245c..70d35f6ae8 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -7,4 +7,4 @@ "@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path. +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path (FIX-1757). diff --git a/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts b/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts index dd46ad16a0..e0d5c71c0c 100644 --- a/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts +++ b/goals/hire-plane/reload-survives-an-unaddressable-row/run.mts @@ -41,7 +41,7 @@ type Router = { const fixture = loadFixture(import.meta.url); /** - * The address a hire under `orgId` should answer on, written out here from + * The address an org-visible hire under `orgId` answers on, written out here from * the documented rule (`[a-z0-9-]` kept, every other UTF-8 byte as `%XX`) * rather than taken from `seatAddress`, the helper under test. */ @@ -171,7 +171,7 @@ await runGoal(async () => { const failures: string[] = []; const fail = (leg: string, line: string) => failures.push(`[${leg}] ${line}`); const stores = inMemoryStores(); - const namedAddress = `${fixture.namedOrg}.${fixture.namedSeatId}`; + const namedAddress = expectedAddress(fixture.namedOrg, fixture.namedSeatId); // (a) An app with no resolver hires at runtime. One store is shared by both // apps below because it is ONE deployment's database seen twice. diff --git a/packages/engine/src/transports/http/createHttpTransportAdapter.ts b/packages/engine/src/transports/http/createHttpTransportAdapter.ts index 94740dd63a..b18760dc23 100644 --- a/packages/engine/src/transports/http/createHttpTransportAdapter.ts +++ b/packages/engine/src/transports/http/createHttpTransportAdapter.ts @@ -92,8 +92,10 @@ function pathFromContextOrUrl( // The raw URL is still encoded, while framework params arrive decoded. // Decode here so both reach `parseFlowRoute` in the same shape. + // The prefix is compared in its encoded form, the one `url.pathname` holds. const url = new URL(request.url); - const prefix = basePath.endsWith("/") ? basePath : `${basePath}/`; + const encodedBase = new URL(basePath, url.origin).pathname; + const prefix = encodedBase.endsWith("/") ? encodedBase : `${encodedBase}/`; if (!url.pathname.startsWith(prefix)) return []; return decodePathSegments(url.pathname.slice(prefix.length)); } diff --git a/packages/engine/test/http-transport-adapter-segments.test.ts b/packages/engine/test/http-transport-adapter-segments.test.ts index 8a5a16d7be..87b79c706a 100644 --- a/packages/engine/test/http-transport-adapter-segments.test.ts +++ b/packages/engine/test/http-transport-adapter-segments.test.ts @@ -12,9 +12,14 @@ import { parseFlowRoute, type ParsedFlowRoute } from "../src/routes/parseFlowRou const TOPIC = " report "; const KIND = "org%5Fpentest%5Flab.helper"; -async function routeVia(url: string, params: Record): Promise { +async function routeVia( + url: string, + params: Record, + basePath?: string +): Promise { let parsed: ParsedFlowRoute | undefined; const adapter = createHttpTransportAdapter({ + ...(basePath === undefined ? {} : { basePath }), handle: async (request, { path }) => { parsed = parseFlowRoute(request.method, path); return new Response(null, { status: 204 }); @@ -38,6 +43,11 @@ describe("createHttpTransportAdapter — ids reach the route as the client encod expect(await routeVia(contentUrl, {})).toEqual(expected); }); + it("strips a basePath that needs encoding on the Request.url fallback", async () => { + const url = `http://localhost/api/my%20path/sessions/s1/resources/notes/${encodeURIComponent(TOPIC)}/content`; + expect(await routeVia(url, {}, "/api/my path")).toEqual(expected); + }); + it("keeps a percent escape in a flow kind from the Request.url fallback", async () => { const url = `http://localhost/api/flows/${encodeURIComponent(KIND)}/requests/r1/stream`; expect(await routeVia(url, {})).toEqual({ kind: "request_stream", flowKind: KIND, requestId: "r1" }); diff --git a/packages/node/src/app.ts b/packages/node/src/app.ts index cfe1aac1e5..bf8ab1c134 100644 --- a/packages/node/src/app.ts +++ b/packages/node/src/app.ts @@ -73,10 +73,13 @@ function escapeRegExp(value: string): string { /** * Decoded segments after the mount prefix, e.g. `/api/flows/chat/send` → * `["chat","send"]`. `pathname` is the raw URL path; each segment is decoded - * once, the same shape Next hands the router as `params.path`. + * once, the same shape Next hands the router as `params.path`. The prefix is + * matched in its encoded form, the one `URL.pathname` carries, so a basePath + * holding a space or other escaped character still comes off. */ function pathSegments(pathname: string, basePath: string): string[] { - const prefix = new RegExp(`^${escapeRegExp(basePath)}/?`); + const encodedBase = new URL(basePath, "http://base.invalid").pathname; + const prefix = new RegExp(`^${escapeRegExp(encodedBase)}/?`); return decodePathSegments(pathname.replace(prefix, "")); } diff --git a/packages/node/test/app.test.ts b/packages/node/test/app.test.ts index caa8cf8b86..3196ee650c 100644 --- a/packages/node/test/app.test.ts +++ b/packages/node/test/app.test.ts @@ -104,6 +104,15 @@ describe("createServerApp — translation", () => { expect(await res.json()).toEqual({ method: "GET", path: [] }); }); + it("strips a basePath that needs encoding, and decodes only what follows it", async () => { + // The request URL carries the base path encoded (`/api/my%20path`); the + // option is written decoded. The prefix must still come off. + const { app } = createServerApp(echoRouter, { basePath: "/api/my path" }); + const res = await app.fetch(new Request(url("/api/my%20path/chat/actions/a%2Fb"))); + expect(res.status).toBe(200); + expect(await res.json()).toEqual({ method: "GET", path: ["chat", "actions", "a/b"] }); + }); + it("reads the body for POST and forwards it to the router", async () => { const payload = JSON.stringify({ hello: "world" }); const { app } = createServerApp(echoRouter); diff --git a/packages/workforce/src/roster/address.ts b/packages/workforce/src/roster/address.ts index ebd87fa1f9..b4e9a5bde7 100644 --- a/packages/workforce/src/roster/address.ts +++ b/packages/workforce/src/roster/address.ts @@ -79,7 +79,8 @@ function orgSegment(orgId: string): string { } /** - * The seat id inside an address this org owns, or `undefined`. + * The seat id inside an address this org owns, or `undefined` — including + * for an org id `seatAddress` would refuse. Never throws. * * One split at the first dot, which is correct only because the escaped org * holds no dot. A user-owned address is `.~.`; the user @@ -87,7 +88,9 @@ function orgSegment(orgId: string): string { * hire row. */ export function splitSeatAddress(orgId: string, address: string): string | undefined { - if (orgId.length === 0) return undefined; + // No address is under an org id `seatAddress` refuses (empty, whitespace-only, + // a lone surrogate), so answer that rather than throwing. + if (!isValidOrgId(orgId)) return undefined; const prefix = `${orgSegment(orgId)}.`; if (!address.startsWith(prefix)) return undefined; const rest = address.slice(prefix.length); diff --git a/packages/workforce/test/roster.test.ts b/packages/workforce/test/roster.test.ts index f7fe19cdc5..270b73385e 100644 --- a/packages/workforce/test/roster.test.ts +++ b/packages/workforce/test/roster.test.ts @@ -242,6 +242,15 @@ describe("V4 · the org segment is what makes the address unambiguous", () => { expect(seatAddress("😀", "ada")).toBe("%F0%9F%98%80.ada"); }); + it("finds no seat, rather than throwing, under an org id seatAddress refuses", () => { + // `splitSeatAddress` is a lookup: an address is never under such an org. + for (const orgId of ["", " ", "\uD800", "acme\uDC00"]) { + expect(() => splitSeatAddress(orgId, "%EF%BF%BD.ada")).not.toThrow(); + expect(splitSeatAddress(orgId, "%EF%BF%BD.ada")).toBeUndefined(); + expect(splitSeatAddress(orgId, "%20%20%20.ada")).toBeUndefined(); + } + }); + it("refuses an empty org id", () => { expect(() => seatAddress("", "support.ada")).toThrow(/organization id must not be empty/); expect(splitSeatAddress("", ".ada")).toBeUndefined(); From f85ab61cf34d93a0275884a9eae9d37542cd9493 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 02:14:49 +0000 Subject: [PATCH 14/28] docs: state the whole org-id contract everywhere; mintFor names the projects collection, under any key (FIX-1757) A repo-wide sweep of every statement of which org ids are refused now lists all of them (empty, whitespace-only, not well-formed Unicode, DEFAULT_ORG_ID for a resolver): flow config, state operations, the org-scope guide, the authentication page, the CLI docs and README, the core JSDoc, and the three runtime error messages that said "nonempty". The mintFor refusal now reads "other than the projects collection" in channels.md and the workforce README, matching the any-key guidance. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- apps/docs/docs/cli/configuration.md | 2 +- apps/docs/docs/configuration/flow.md | 2 +- apps/docs/docs/fundamentals/state-operations.md | 2 +- apps/docs/docs/server/authentication.md | 3 ++- apps/docs/docs/workforce/channels.md | 2 +- apps/docs/guides/projects-on-org-scope.md | 4 ++-- packages/cli/README.md | 2 +- packages/cli/src/principal.ts | 2 +- packages/core/src/types/auth.ts | 8 +++++--- packages/engine/src/transports/errors.ts | 2 +- .../src/transports/host/createInboundTransportHost.ts | 2 +- packages/workforce/README.md | 4 ++-- 12 files changed, 19 insertions(+), 16 deletions(-) diff --git a/apps/docs/docs/cli/configuration.md b/apps/docs/docs/cli/configuration.md index 5d332b285d..b50d4d4ac6 100644 --- a/apps/docs/docs/cli/configuration.md +++ b/apps/docs/docs/cli/configuration.md @@ -156,7 +156,7 @@ fsdev run billing refund -i '{"id":"r_1"}' --org acme --user support-bot ``` `--org` skips your resolver entirely and runs as `--user`, or `cli-user` without it. It can't be -blank or `DEFAULT_ORG_ID`. `fsdev serve` and `fsdev dev` have no such flag, so requests that arrive +blank, not well-formed Unicode (a lone UTF-16 surrogate), or `DEFAULT_ORG_ID`. `fsdev serve` and `fsdev dev` have no such flag, so requests that arrive over the network always go through your resolver. `--user` on its own asks your resolver as usual, keeps the organization it returns, and replaces diff --git a/apps/docs/docs/configuration/flow.md b/apps/docs/docs/configuration/flow.md index fc0d509924..9f8d2a7e96 100644 --- a/apps/docs/docs/configuration/flow.md +++ b/apps/docs/docs/configuration/flow.md @@ -139,7 +139,7 @@ Each key in `actions` is a public name. Clients call it with `sendAction("chat", | Field | Type | Default | What it does | |-------|------|---------|--------------| -| `resolvePrincipal` | `(ctx) => principal \| null` | — | Map the inbound request to `{ userId?, orgId }`. The `orgId` is required — returning none, a blank one, or `DEFAULT_ORG_ID` is refused with 401. Throw a `PrincipalResolutionError` to pick the HTTP status (401/403). | +| `resolvePrincipal` | `(ctx) => principal \| null` | — | Map the inbound request to `{ userId?, orgId }`. The `orgId` is required — returning none, a blank one, one that is not well-formed Unicode (a lone UTF-16 surrogate), or `DEFAULT_ORG_ID` is refused with 401. Throw a `PrincipalResolutionError` to pick the HTTP status (401/403). | | `defaultUserId` | `string` | — | Used when the resolver returns no `userId`. Typical for schedules and webhooks. | | `requireUser` | `boolean` | `true` | Reject requests that still have no `userId` after the fallback. `false` forbids user-scoped state, client projections, and resources at registration. | diff --git a/apps/docs/docs/fundamentals/state-operations.md b/apps/docs/docs/fundamentals/state-operations.md index 7c00addd2a..d6093ee81d 100644 --- a/apps/docs/docs/fundamentals/state-operations.md +++ b/apps/docs/docs/fundamentals/state-operations.md @@ -134,7 +134,7 @@ type ScopeIdentity = { }; ``` -Both fields are optional on `ScopeIdentity`, but every action execution supplies a `userId` and an `orgId`. Call `runAction` yourself and you pass both: a blank or missing `orgId` throws `OrgRequiredError` before anything is written, so pass the organization you verified, or [`DEFAULT_ORG_ID`](/docs/server/authentication#every-request-runs-in-an-organization) for single-organization development. Through a transport you pass neither. The server takes both from the resolved principal, and nothing in the request body can name the organization. `sessionId` is optional, and when it is omitted the framework auto-creates an ephemeral session. +Both fields are optional on `ScopeIdentity`, but every action execution supplies a `userId` and an `orgId`. Call `runAction` yourself and you pass both: a missing or blank `orgId`, or one that is not well-formed Unicode (a lone UTF-16 surrogate), throws `OrgRequiredError` before anything is written, so pass the organization you verified, or [`DEFAULT_ORG_ID`](/docs/server/authentication#every-request-runs-in-an-organization) for single-organization development. Through a transport you pass neither. The server takes both from the resolved principal, and nothing in the request body can name the organization. `sessionId` is optional, and when it is omitted the framework auto-creates an ephemeral session. A request id can be chosen by the caller, and once a request's record is gone (session retention deletes old ones) the same id can name a new request. `ctx.request.incarnation` tells the two requests apart. It is a random token that stays the same for this request, including retries and resumes. If you key anything of your own on a request id, such as a scratch directory or a cache that outlives the request, key it on `incarnation` as well. See [Ids you choose are addresses](/docs/server/authentication#ids-you-choose-are-addresses) for what a caller-chosen id does and doesn't give you. diff --git a/apps/docs/docs/server/authentication.md b/apps/docs/docs/server/authentication.md index b44f6a54f6..1596da69ad 100644 --- a/apps/docs/docs/server/authentication.md +++ b/apps/docs/docs/server/authentication.md @@ -58,7 +58,8 @@ server checks it on reads and on execution alongside the user. It comes from one of two places, and never from the caller: - **A configured resolver** returns the organization it verified. If it - returns none, a blank one, or the reserved default below, the request is + returns none, a blank one, one that isn't well-formed Unicode, or the + reserved default below, the request is refused with 401. Returning `null` is refused too: `defaultUserId` fills in a user, never an organization. - **No configured resolver at all**, which is the development case. The diff --git a/apps/docs/docs/workforce/channels.md b/apps/docs/docs/workforce/channels.md index b76d2b6911..fe03cb21b4 100644 --- a/apps/docs/docs/workforce/channels.md +++ b/apps/docs/docs/workforce/channels.md @@ -862,7 +862,7 @@ When a template is in place, any code that creates a project inside a flow turn A room's lines aren't in any session's history. Read them with `read` on a member's talk session. -`channelInstances` checks templates along with your channels and reports every problem at once. It refuses a template whose `mintFor:` names no collection in the resources you passed, or one that isn't `projects`, a seat that isn't a seat id or is listed twice, seats on a kind that can't wake them, and a second template for the same collection, whether it's in `org/resources/projects.ts` or another `CHANNEL.md`. +`channelInstances` checks templates along with your channels and reports every problem at once. It refuses a template whose `mintFor:` names no collection in the resources you passed, or names something other than the projects collection, a seat that isn't a seat id or is listed twice, seats on a kind that can't wake them, and a second template for the same collection, whether it's in `org/resources/projects.ts` or another `CHANNEL.md`. ## Registering a kind of your own diff --git a/apps/docs/guides/projects-on-org-scope.md b/apps/docs/guides/projects-on-org-scope.md index ae27c771eb..bbf5837b11 100644 --- a/apps/docs/guides/projects-on-org-scope.md +++ b/apps/docs/guides/projects-on-org-scope.md @@ -113,9 +113,9 @@ const flow = defineFlow({ }); ``` -An `orgId` posted in the request body, query or metadata is ignored, so a caller cannot name someone else's organization. A resolver that returns no organization, a blank one, or `DEFAULT_ORG_ID` is refused with `401`. +An `orgId` posted in the request body, query or metadata is ignored, so a caller cannot name someone else's organization. A resolver that returns no organization, a blank one, one that is not well-formed Unicode (a lone UTF-16 surrogate), or `DEFAULT_ORG_ID` is refused with `401`. -Organization ids are opaque nonempty strings, app-owned like `userId`. [Authentication](/docs/server/authentication#every-request-runs-in-an-organization) covers the resolver in full. +Organization ids are opaque strings, app-owned like `userId`: any string that is not empty, whitespace-only, or not well-formed Unicode (a lone UTF-16 surrogate). [Authentication](/docs/server/authentication#every-request-runs-in-an-organization) covers the resolver in full. ## Switching projects mid-conversation diff --git a/packages/cli/README.md b/packages/cli/README.md index ae8d2ee9df..2a1f213101 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -62,7 +62,7 @@ Every run executes as a user in an organization, the same as a request to your s - An app with no resolver runs as `cli-user` (or `--user`) in the development organization, `DEFAULT_ORG_ID`. - A resolver that checks a credential refuses the terminal, which carries none. The run stops before it writes anything, exits `2`, and the message names the flow and `--org`. -- `--org ` skips the resolver and runs as `--user` (default `cli-user`) in that organization. It may not be blank or `DEFAULT_ORG_ID`. `fsdev serve` and `fsdev dev` have no such flag. +- `--org ` skips the resolver and runs as `--user` (default `cli-user`) in that organization. It may not be blank, not well-formed Unicode (a lone UTF-16 surrogate), or `DEFAULT_ORG_ID`. `fsdev serve` and `fsdev dev` have no such flag. - `--user` alone keeps the organization the resolver gives and replaces only the user. - `--session` / `--seed-session` on a session another user or organization owns is refused before anything is written, including the seed. Sessions keep the identity they were created with. A session stored before organizations were required is refused with the migration message. - A seat pinned to an owner refuses any identity outside its pin, before anything is written. diff --git a/packages/cli/src/principal.ts b/packages/cli/src/principal.ts index 9e28dd4b2b..98a5eb0ab7 100644 --- a/packages/cli/src/principal.ts +++ b/packages/cli/src/principal.ts @@ -79,7 +79,7 @@ export function askFlowState( export function validatePrincipalFlags(flags: PrincipalFlags): void { if (flags.org !== undefined) { if (!isValidOrgId(flags.org)) { - throw new CliError("--org must be a nonempty organization id.", EXIT_INVALID_ARGS); + throw new CliError("--org must be a nonempty, well-formed organization id.", EXIT_INVALID_ARGS); } if (flags.org === DEFAULT_ORG_ID) { throw new CliError( diff --git a/packages/core/src/types/auth.ts b/packages/core/src/types/auth.ts index 1640c7c14f..649a82153a 100644 --- a/packages/core/src/types/auth.ts +++ b/packages/core/src/types/auth.ts @@ -40,7 +40,8 @@ export const DEFAULT_ORG_ID = "__fsd_default_org__"; /** * Whether `value` is usable as an organization id. * - * Organization ids are opaque nonempty strings. A whitespace-only id is + * Organization ids are opaque strings: not empty, not whitespace-only, and + * well-formed Unicode (see below). A whitespace-only id is * rejected rather than trimmed, and a valid id is never rewritten — the * framework stores exactly what the trusted source supplied, so a stored id * and the identity that produced it compare equal. @@ -112,8 +113,9 @@ export interface PrincipalResolutionContext { * `defaultUserId` and enforce `requireUser`), or `null`. * * Whatever shape it returns, the framework requires a verified organization - * before any effect: a resolver that yields no `orgId`, a whitespace-only one, - * or the reserved {@link DEFAULT_ORG_ID} is refused at principal resolution + * before any effect: a resolver that yields no `orgId`, one {@link isValidOrgId} + * rejects (empty, whitespace-only, a lone surrogate), or the reserved + * {@link DEFAULT_ORG_ID} is refused at principal resolution * (FIX-1442). `null` is refused for the same reason — it cannot be repaired by * the `defaultUserId` fallback, which supplies a user and never an * organization. A machine transport returns `{ orgId }` and lets diff --git a/packages/engine/src/transports/errors.ts b/packages/engine/src/transports/errors.ts index 0f24f53065..a29643cf51 100644 --- a/packages/engine/src/transports/errors.ts +++ b/packages/engine/src/transports/errors.ts @@ -39,7 +39,7 @@ export class OrgRequiredError extends Error { constructor(flowKind: string, seam = "this call") { super( `${seam} requires an organization for flow "${flowKind}". Trusted direct ` + - `execution must pass a nonempty orgId — the verified organization for an ` + + `execution must pass a nonempty, well-formed orgId — the verified organization for an ` + `authenticated caller, or DEFAULT_ORG_ID for single-organization development.` ); this.name = "OrgRequiredError"; diff --git a/packages/engine/src/transports/host/createInboundTransportHost.ts b/packages/engine/src/transports/host/createInboundTransportHost.ts index 170a87facb..091ef63585 100644 --- a/packages/engine/src/transports/host/createInboundTransportHost.ts +++ b/packages/engine/src/transports/host/createInboundTransportHost.ts @@ -258,7 +258,7 @@ function createPrincipalResolution(options: { if (resolvedOrgId === undefined) { throw new PrincipalResolutionError( "Request requires a verified organization: authentication.resolvePrincipal " + - "returned no usable orgId. Return a nonempty orgId from the resolver.", + "returned no usable orgId. Return a nonempty, well-formed orgId from the resolver.", { status: 401 } ); } diff --git a/packages/workforce/README.md b/packages/workforce/README.md index e51c6c4fc6..c80638714d 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2059,7 +2059,7 @@ Talk sessions run on the built-in `channel` kind, so pass it built with a `notif `kinds: { channel: defineChannelFlow({ notify: wakeMemberSeats(seats) }) }`. `channelInstances` refuses, with its other refusals, a template that declares `flow:`, `boards:`, `routing:` or `boardActions:`, a `mintFor:` that names no collection in `resources` or names one -other than `projects`, a bad or repeated seat id, seats on a `channel` kind built with no `notify` +other than the projects collection (under whatever key you passed it), a bad or repeated seat id, seats on a `channel` kind built with no `notify` block (none of them would wake), and a second template for the collection at either site. The first call that finds the template registers it for the process. Every later call builds its `channel` kind holding it, with or without `resources`, and a later call that finds a different @@ -2248,7 +2248,7 @@ before fire removed inventory rows is left out that way. | Channel folder fails to load | Collected in `readChannelsDirectory`'s `errors` as `kind: "channel-load-failed"`, keyed by the folder's path — an unusable name, a symlink, or a missing, unreadable or malformed `CHANNEL.md` | | `system:` in a `CHANNEL.md` | Collected in `readChannelsDirectory`'s `errors` as `kind: "refused-declaration"`, keyed by the channel folder's path | | Workforce root unreadable or symlinked, read for channels | `readChannelsDirectory` throws — the root is never followed through a link | -| Channel cannot be bound | `channelInstances` — a `flow:` naming a kind nobody passed, a kind filed under another kind's key, a duplicate id, an `id:`, a `system:`, an undeclared key, a `members:` that is not a list of names, a `boards:` that is not a list of plain names, a board name carrying a dot or declared twice, a minted board id two channels would share, or `boards:` on a custom kind that does not support them. Also `instructions:` given both in the frontmatter and as a body. For a talk template (`mintFor:`, or the org default): `boards:`, `routing:` or `boardActions:` on it, a `mintFor:` naming no collection in `resources` or one other than `projects`, a seat that is not a seat id or is listed twice, a kind filed under another kind's key or one `defineChannelFlow` did not build, seats on a kind with no `notify` block, or a second template for the collection. Collected: one error names every bad channel, and nothing is registered | +| Channel cannot be bound | `channelInstances` — a `flow:` naming a kind nobody passed, a kind filed under another kind's key, a duplicate id, an `id:`, a `system:`, an undeclared key, a `members:` that is not a list of names, a `boards:` that is not a list of plain names, a board name carrying a dot or declared twice, a minted board id two channels would share, or `boards:` on a custom kind that does not support them. Also `instructions:` given both in the frontmatter and as a body. For a talk template (`mintFor:`, or the org default): `boards:`, `routing:` or `boardActions:` on it, a `mintFor:` naming no collection in `resources` or one other than the projects collection, a seat that is not a seat id or is listed twice, a kind filed under another kind's key or one `defineChannelFlow` did not build, seats on a kind with no `notify` block, or a second template for the collection. Collected: one error names every bad channel, and nothing is registered | | Channel cannot be opened | `openChannels` throws, naming the channel — except a 409, which means the id is taken. An open channel there is left alone, and this kind's own empty session is bound. Anything else holding the id — another flow's session, another user's, or one carrying state that is not a readable channel — is named and refused rather than released | | `channel-not-bound` | A `post` or `read` naming a session nobody opened. Per-request; nothing is written and the session stays inert | | `author-not-a-member` | A `post` claiming an `author` outside the channel's declared members. Per-request; nothing is written | From e9b4809f72c5075ed2d9f22168ec5ea82fde31be Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 02:25:04 +0000 Subject: [PATCH 15/28] docs,changeset: match escaped seat-address prefixes with an escaped LIKE; fsdev minor (FIX-1757) The hired-seat migration step built its flow_id prefix from the raw org. It now builds the escaped prefix (seatAddress's rule), escapes LIKE metacharacters, and matches with ESCAPE '\', with an org_pentest_lab worked example. The changeset bumps @flow-state-dev/fsdev to minor and says `fsdev run --org` now rejects a lone-surrogate id. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 3 ++- apps/docs/docs/persistence/overview.md | 15 ++++++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index 70d35f6ae8..bce2091576 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -2,9 +2,10 @@ "@flow-state-dev/workforce": minor "@flow-state-dev/core": minor "@flow-state-dev/engine": minor +"@flow-state-dev/fsdev": minor "@flow-state-dev/node": patch "@flow-state-dev/next": patch "@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path (FIX-1757). +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate, so a resolver returning one gets 401 and `fsdev run --org` rejects it. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path (FIX-1757). diff --git a/apps/docs/docs/persistence/overview.md b/apps/docs/docs/persistence/overview.md index bb150b771a..0ee4bafcc7 100644 --- a/apps/docs/docs/persistence/overview.md +++ b/apps/docs/docs/persistence/overview.md @@ -251,7 +251,20 @@ A seat keeps what it saves for a person under a user-scope key for its organizat Copying is optional and offline, with writers quiesced and a backup taken, as in the [owner attribution procedure](#who-owns-a-record) above. It copies only data you can show a seat wrote. 1. **List the keys.** For each seat kind, the user-scoped resources and collections it declares without `flowIsolation: true`. Strike the keys a flow that is not a hired seat also declares, and the person's `users` row. Those stay where they are, so the seat starts without them. Copy a struck key only if your own records show a seat wrote it. -2. **List the people and their organizations.** Hired seat addresses start with their organization (`acme.research`, `acme.~alice.research`). Include seats you have since fired. Their addresses remain in `sessions.flow_id`, so `SELECT DISTINCT flow_id FROM sessions WHERE flow_id LIKE 'acme.%'` lists every address used in `acme`. Keep the ones that were hired seats. +2. **List the people and their organizations.** A hired seat's address is `.`, or `.~.` for a [seat only one member can reach](/docs/workforce/durable-hire#hiring-a-seat-only-one-member-can-reach). Include seats you have since fired. Their addresses remain in `sessions.flow_id`, so a prefix match lists every address used in an organization. Keep the ones that were hired seats. + + 1. Build the escaped organization prefix. Lowercase letters, digits and `-` stay as they are. Every other character becomes `%XX`, the uppercase hex of its UTF-8 bytes, so `acme` stays `acme`, `org_pentest_lab` becomes `org%5Fpentest%5Flab` and `Acme.EU` becomes `%41cme%2E%45%55`. Or let `seatAddress` from `@flow-state-dev/workforce` do it: `seatAddress(orgId, "x")` without the trailing `x` is the prefix, ending in `.`. + 2. In that prefix, escape the characters `LIKE` treats specially: `\` becomes `\\`, `%` becomes `\%` and `_` becomes `\_`. + 3. Match with `ESCAPE '\'`, which SQLite and Postgres both accept. For `org_pentest_lab`: + + ```sql + SELECT DISTINCT flow_id FROM sessions + WHERE flow_id LIKE 'org\%5Fpentest\%5Flab.%' ESCAPE '\'; + ``` + + For `acme` nothing needs escaping: `LIKE 'acme.%' ESCAPE '\'`. + + Then count the organizations each person appears in: ```sql SELECT user_id, COUNT(DISTINCT org_id) AS orgs, GROUP_CONCAT(DISTINCT org_id) AS which From c355fc4f57a014fb230b37bcef334d3a4524f8e4 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 02:34:42 +0000 Subject: [PATCH 16/28] docs,changeset: encode a seat address in a hand-built URL; version every isValidOrgId consumer (FIX-1757) The changeset now covers every published package whose behavior the lone-surrogate refusal changes, found by grepping isValidOrgId / orgSegment / seatAddress / splitSeatAddress across packages/*/src: bullmq (an enqueued job with such an org fails) and scheduled (such a row is quarantined) join core, engine, fsdev and workforce at minor, each with its upgrade impact. durable-hire.md's "Calling a hired seat" says to put the address in a hand-built URL with encodeURIComponent, with the org_pentest_lab example. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 4 +++- apps/docs/docs/workforce/durable-hire.md | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index bce2091576..7021eb0f08 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -3,9 +3,11 @@ "@flow-state-dev/core": minor "@flow-state-dev/engine": minor "@flow-state-dev/fsdev": minor +"@flow-state-dev/bullmq": minor +"@flow-state-dev/scheduled": minor "@flow-state-dev/node": patch "@flow-state-dev/next": patch "@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate, so a resolver returning one gets 401 and `fsdev run --org` rejects it. Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path (FIX-1757). +`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate (FIX-1757). Upgrade impact of that refusal, wherever `isValidOrgId` gates: a resolver returning such an id gets 401 and `runAction` or a dispatch throws `OrgRequiredError` (engine); `fsdev run --org` rejects it (fsdev); an already-enqueued BullMQ job carrying one fails with `OrgRequiredError` instead of running (bullmq); a stored schedule row carrying one is quarantined and no longer dispatches (scheduled). Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path. diff --git a/apps/docs/docs/workforce/durable-hire.md b/apps/docs/docs/workforce/durable-hire.md index a0f251b807..5f32a5e7fc 100644 --- a/apps/docs/docs/workforce/durable-hire.md +++ b/apps/docs/docs/workforce/durable-hire.md @@ -254,6 +254,8 @@ curl -X POST localhost:3000/api/flows/acme.support.ada/actions/answer \ -d '{"userId":"you","input":{"note":"is the printer fixed?"}}' ``` +When you build the URL by hand, pass the address through `encodeURIComponent(address)` and use the result as one path segment. The address `org%5Fpentest%5Flab.helper`, for the organization `org_pentest_lab`, goes out as `/api/flows/org%255Fpentest%255Flab.helper/actions/answer`. Sent as-is, the `%5F` is read as an underscore, which names a different seat, and the seat is not found. `acme.support.ada` has nothing to escape and works as written. `@flow-state-dev/client` and the React hooks encode the address for you. + The organization is part of the address because two organizations can both want a seat called `support.ada`, and an app serves one flat set of addresses. It identifies the seat. It does not authorize anything: who may call it is decided by the principal on the request. The body does not name the organization. ## Who can reach a hired seat From a1eab1b191fb55c0220c8304bfab3f4fad69f43f Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 02:41:01 +0000 Subject: [PATCH 17/28] chore(changeset): one user-facing sentence, per AGENTS.md (FIX-1757) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .changeset/hire-any-org-id.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.changeset/hire-any-org-id.md b/.changeset/hire-any-org-id.md index 7021eb0f08..2b689a9562 100644 --- a/.changeset/hire-any-org-id.md +++ b/.changeset/hire-any-org-id.md @@ -10,4 +10,4 @@ "@flow-state-dev/vercel": patch --- -`seatAddress` accepts any well-formed organization id by percent-escaping it (ids of lowercase letters, digits and `-` keep their addresses; the `"Org"` member leaves `SegmentLabel`), and `isValidOrgId` now refuses an id containing a lone UTF-16 surrogate (FIX-1757). Upgrade impact of that refusal, wherever `isValidOrgId` gates: a resolver returning such an id gets 401 and `runAction` or a dispatch throws `OrgRequiredError` (engine); `fsdev run --org` rejects it (fsdev); an already-enqueued BullMQ job carrying one fails with `OrgRequiredError` instead of running (bullmq); a stored schedule row carrying one is quarantined and no longer dispatches (scheduled). Route segments are now decoded exactly once on every host, so a seat or flow id carrying a literal `%XX` no longer 404s on Next and Vercel; `parseFlowRoute`'s input contract changed to already-decoded segments (it no longer decodes or trims them), and the new `decodePathSegments` builds those from a raw URL path. +Organization ids are now validated as well-formed, non-blank Unicode everywhere (resolver, `runAction`, dispatch, BullMQ jobs, schedules, `fsdev run --org`) and seat addresses escape any such id, while route segments are decoded exactly once on every host (`parseFlowRoute` now takes decoded segments, built from a raw URL by the new `decodePathSegments`), so escaped seat ids resolve on Next and Vercel and stored rows or queued jobs with a lone-surrogate org id are now refused (FIX-1757). From f4e6d1393ff647f4b5cceb0ff8ccc23e60abeef6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 21:08:56 +0000 Subject: [PATCH 18/28] Name MAILBOX.md in the FIX-1756 verdict row The mailbox-rename guard rejects the old file name. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Cb565RgMJYrvVrK9Jsqi4U --- .../devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md b/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md index ae2e6c0e79..0488119d53 100644 --- a/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md +++ b/goals/devforce-lab/it-ships-an-artifact-a-person-can-open/goal.md @@ -168,4 +168,4 @@ own verdict log, which re-proves BR-10 and BR-17. **Re-run on `origin/main` at ` while the same read with an org lands"*. The paragraph above is kept as history. | 2026-09-30 | a1b122eb1 | n/a | PASS | Local leg. Row read back in a fresh process from the organization's storage under the mailbox's board id; the transcript count reads mailbox-post items. The published branch carries `eng.feature.work`. | | 2026-10-01 | a25134ebd+wip (FIX-1691/1692) | Claude Code (Agent SDK) | PASS | Local leg. 19 lab TypeScript files classified, `harness.mts` among them. | -| 2026-10-04 | d5225ecd8+FIX-1756 | Claude Code (Agent SDK) | PASS | Local leg. The skip list is read off `CHANNEL.md`: 3 declared members seen and skipped (`chief-of-staff`, `eng.coder`, `eng.reviewer`). All nine controls red. Red on `d5225ecd8` before the change: *the fan-out skipped [chief-of-staff, eng.coder, eng.reviewer]; wanted [eng.coder, eng.reviewer]*. | +| 2026-10-04 | d5225ecd8+FIX-1756 | Claude Code (Agent SDK) | PASS | Local leg. The skip list is read off `MAILBOX.md`: 3 declared members seen and skipped (`chief-of-staff`, `eng.coder`, `eng.reviewer`). All nine controls red. Red on `d5225ecd8` before the change: *the fan-out skipped [chief-of-staff, eng.coder, eng.reviewer]; wanted [eng.coder, eng.reviewer]*. | From 58e92e18fc327c52a103d1c47aadaddeee3b7371 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 21:28:53 +0000 Subject: [PATCH 19/28] feat(workforce): FIX-1762 project repository and project files (2/4) A project row records the git remote its code lives in, and a project keeps its own files in an org collection only its members can read. - `repository: string | null` on the projects row, default null, in the browser read. Stored rows are not re-parsed on read, so a legacy row is read through `projectRowSchema` or guarded with `== null`. - `createProject.repository` and `setRepository { projectId, repository }` (members only, rewritten from the stored state, retried on a lost CAS race). One validator, `repository-value.ts`, refuses a path, a leading `-`, a control character, a remote-helper address and a credential with `invalid-repository`, never repeating the value. Both SSH spellings and file:// pass; which remotes a host reaches is the host's call. - `project-files/**`: org-scoped, shared, lazy, no browser read, keyed `/`. `readProjectFiles { projectId }` lists only that project's prefix, members only. - Controls: FSD_CONTROL=any-repository turns the refusal test red; no-retry turns the repository burst red; no-gate the non-member tests. Workforce README, the Projects docs page, and a minor changeset. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5 --- .changeset/project-repository-and-files.md | 5 + apps/docs/docs/workforce/projects.md | 57 +++- packages/workforce/README.md | 20 +- .../workforce/src/projects/collections.ts | 68 ++++- packages/workforce/src/projects/index.ts | 18 +- .../workforce/src/projects/project-files.ts | 71 +++++ .../workforce/src/projects/project-refusal.ts | 3 + .../workforce/src/projects/project-writes.ts | 90 +++++- .../src/projects/repository-value.ts | 76 ++++++ packages/workforce/test/projects.test.ts | 258 +++++++++++++++++- 10 files changed, 644 insertions(+), 22 deletions(-) create mode 100644 .changeset/project-repository-and-files.md create mode 100644 packages/workforce/src/projects/project-files.ts create mode 100644 packages/workforce/src/projects/repository-value.ts diff --git a/.changeset/project-repository-and-files.md b/.changeset/project-repository-and-files.md new file mode 100644 index 0000000000..96ab39d58b --- /dev/null +++ b/.changeset/project-repository-and-files.md @@ -0,0 +1,5 @@ +--- +"@flow-state-dev/workforce": minor +--- + +A project row records the git remote its code lives in: `repository: string | null`, default `null`, readable from the browser with the row. `createProject` takes an optional `repository`, and the new `setRepository { projectId, repository }` sets, changes or clears it for a member. Both refuse a path, a value starting with `-`, a control character, a remote-helper address and a value carrying a credential with the new refusal reason `invalid-repository`, without repeating the value. Stored rows are not re-parsed on read, so treat a missing `repository` as `null` or read through `projectRowSchema.parse`. A project's files live in the new org-scoped `project-files//…` collection (`defineProjectFilesCollection()`), with no browser read; members read them with the new `readProjectFiles` block, also in `defineProjectBlocks().actions` (FIX-1762). diff --git a/apps/docs/docs/workforce/projects.md b/apps/docs/docs/workforce/projects.md index 621db89397..1607413420 100644 --- a/apps/docs/docs/workforce/projects.md +++ b/apps/docs/docs/workforce/projects.md @@ -30,6 +30,7 @@ The organization owns the projects. A project groups the workstreams that belong | `ownerUserId` | The person who created it | | `members` | Who can read and post in the room. Always includes the owner | | `workstreams` | Full mailbox ids of the declared mailboxes it groups, such as `eng.feature` and `ops.release` | +| `repository` | The git remote the project's code lives in, such as `https://github.com/acme/storefront.git`, or `null` | | `sessions` | Each member's own talk session on the room, at most one per person | Everyone in the organization can list the rows. That a project exists isn't a secret. Its room is. @@ -50,7 +51,7 @@ Its one option, `talk`, is the template every project's room is built from: the ## Creating a project -`defineProjectBlocks()` gives you two blocks, `createProject` and `setWorkstreams`, and the same two as an `actions` map to spread into a flow: +`defineProjectBlocks()` gives you the project blocks, `createProject`, `setWorkstreams`, `setRepository` and `readProjectFiles`, and the same blocks as an `actions` map to spread into a flow: ```ts import { defineFlow } from "@flow-state-dev/core"; @@ -64,7 +65,7 @@ export const lab = defineFlow({ }); ``` -Call `createProject` with an id, a title, and optionally a brief, the other members, and the workstreams: +Call `createProject` with an id, a title, and optionally a brief, the other members, the workstreams, and the [repository](#a-projects-code-and-files): ```ts { @@ -73,6 +74,7 @@ Call `createProject` with an id, a title, and optionally a brief, the other memb brief: "Ship the new checkout.", members: ["bob"], workstreams: ["eng.feature", "ops.release"], + repository: "https://github.com/acme/storefront.git", } ``` @@ -151,6 +153,57 @@ A refused write leaves nothing behind. If one workstream is already claimed, the A workstream no project lists isn't lost. A UI shows it under **No project**. +## A project's code and files + +A project can name the repository its code lives in. It's a remote, the address you'd pass to `git clone`, not a folder on some machine. Set it when you create the project, or later with `setRepository`. Send `null` to clear it: + +```ts +// at create +{ id: "storefront", title: "Storefront", repository: "https://github.com/acme/storefront.git" } + +// later, from a member's session +{ projectId: "storefront", repository: "git@github.com:acme/storefront.git" } +{ projectId: "storefront", repository: null } +``` + +`setRepository` returns `{ project }`, the row as written. It changes `repository` and nothing else on the row. Only members can call it; anyone else is refused with `not-a-member`, and an id no project holds with `no-such-project`. When two members set it at the same moment, one of the two values is kept whole. + +A value has to be a remote. Both writes refuse these with `invalid-repository`, and the refusal never repeats the value: + +| Refused | Example | +|---------|---------| +| A path | `/srv/git/storefront`, `./storefront`, `~/code/storefront`, `C:\code\storefront` | +| A value starting with `-` | `--upload-pack=…` | +| A control character | A newline or tab anywhere in the address | +| A remote-helper address | `ext::…` | +| A user or password on `http` or `https` | `https://alice:token@github.com/acme/storefront.git`, `https://token@github.com/…` | +| A password on any other scheme | `ssh://git:secret@github.com/acme/storefront.git` | + +An SSH login name isn't a credential, so `git@github.com:acme/storefront.git` and `ssh://git@github.com/acme/storefront.git` are both accepted. So is `file:///srv/git/storefront.git`. Give the machine that clones the repository its credentials, rather than putting them in the address. + +Stored rows aren't re-parsed when they're read, so a row saved without a `repository` key reads without one. Treat a missing value as `null`, or read rows through `projectRowSchema.parse(row)`, which fills it in. + +### The project's own files + +Notes, memory and anything else kept for a project live in the organization's `project-files` collection, under the project's id: `project-files//`. Declare it with `defineProjectFilesCollection()`. Like `defineProjectsCollection()`, every call returns the same declaration. It's org-scoped, shared across flows, and loaded only when read. + +Only the project's members can read the files, with `readProjectFiles`: + +```ts +// input +{ projectId: "storefront" } + +// output: each file's path under the project, and its body +{ + files: [ + { path: "notes.md", content: "# Notes" }, + { path: "src/index.ts", content: "export {};" }, + ], +} +``` + +It returns that project's files, never another project's. A non-member is refused with `not-a-member`, and an unknown id with `no-such-project`. The collection has no browser read: a request for it through the collection route gets a 403. + ## The room and talk sessions A project's room is stored on the organization's side, one row per line. Nobody reaches it directly. Each member gets their own **talk session**: a session on the mailbox kind that knows which project it's about. Every room call goes through one. diff --git a/packages/workforce/README.md b/packages/workforce/README.md index 7c419039a4..4725ac5687 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2022,8 +2022,8 @@ membershipPrefix(""); ## Projects A project is a row in the organization's `projects` collection: a title, a brief, an owner, its -`members`, the workstreams (declared mailboxes, from any team) it groups, and each member's talk -session. Declare the collection once in `workforce/org/resources/projects.ts` with +`members`, the workstreams (declared mailboxes, from any team) it groups, the git remote its code +lives in (`repository`, or `null`), and each member's talk session. Declare the collection once in `workforce/org/resources/projects.ts` with `defineProjectsCollection()`. The guide is the docs site's Workforce → Projects page. ```ts @@ -2033,13 +2033,25 @@ const projects = defineProjectBlocks(); defineFlow({ kind: "lab", actions: { ...projects.actions } }); ``` -- **`createProject { id, title, brief?, members?, workstreams? }`** writes a row with `create`. +- **`createProject { id, title, brief?, members?, workstreams?, repository? }`** writes a row with `create`. The owner is the calling session's owner, and is always a member. An id held by another owner, `unassigned`, a workstream not in the mailbox inventory, and a workstream another project holds are each refused, and nothing is half written. The same owner re-sending an id gets the row back (`created: false`) and its talk session bound if it wasn't. - **`setWorkstreams { projectId, workstreams }`** replaces the list. Members only. -- **As a seat's tools.** Put both in `defineAgentWorkerFlow({ catalog })` under the names a seat's +- **`setRepository { projectId, repository }`** sets, changes or clears (`null`) the repository and + returns `{ project }`. Members only. Nothing else on the row moves, and of two members setting it + at once one value is kept whole. A value must be a remote, the address you'd pass to `git clone`: + both writes refuse a path, a value starting with `-`, a control character, a remote-helper address (`ext::…`), a user + or password on `http(s)`, and a password on any scheme, with `invalid-repository`, and never + repeat the value. `git@host:org/repo` and `ssh://git@host/org/repo` are accepted. Stored rows + aren't re-parsed on read: treat a missing `repository` as `null`, or read through + `projectRowSchema.parse`. +- **`readProjectFiles { projectId }`** returns `{ files: [{ path, content }] }`, the files the + project keeps in the org's `project-files` collection (`defineProjectFilesCollection()`), at + `project-files//`. Members only. The collection is org-scoped, shared, lazy, and + has no browser read. +- **As a seat's tools.** Put the writes in `defineAgentWorkerFlow({ catalog })` under the names a seat's `tools:` spells. A catalog key must be the tool's own name, so wrap each in a one-step `sequencer({ name: "createProject", inputSchema: createProjectInputSchema, outputSchema: createProjectOutputSchema }).step(projects.createProject)`. The owner is the session the seat diff --git a/packages/workforce/src/projects/collections.ts b/packages/workforce/src/projects/collections.ts index 13de07c114..f31624f5bf 100644 --- a/packages/workforce/src/projects/collections.ts +++ b/packages/workforce/src/projects/collections.ts @@ -1,11 +1,12 @@ /** - * Projects — the organization's `projects` rows, and the three collections a - * project's room and its workstream claims live in. + * Projects — the organization's `projects` rows, and the collections a + * project's room, its workstream claims and its files live in. * - * projects/ one row per project: title, brief, owner, members, workstreams, talk sessions + * projects/ one row per project: title, brief, owner, members, workstreams, repository, talk sessions * room-lines// one row per line of the project's room, created and never edited * room-seq/ the room's sequence counter and its committed watermark, alone * workstream-claims/ which project holds a workstream; one shared key, written with `create` + * project-files// one row per file the project keeps: notes, memory, a no-repository project's code * * A project is runtime data. It is created after the tree was read, so no * `MAILBOX.md` and no inventory row can name it; the row is the project's one @@ -21,6 +22,8 @@ * member's talk session (`talk.ts`), which checks the row's `members` first; * a browser read of `room-lines` would skip that check, so neither it nor the * counter declares one, and the collection route refuses both with a 403. + * Project files are the same: `readProjectFiles` checks `members` first, and + * the collection has no browser read. * * These keys are a public surface: Shift Manager and the chief of staff read * them, and moving a prefix breaks every store that already holds a project. @@ -38,6 +41,8 @@ export const ROOM_LINES_RESOURCE = "room-lines"; export const ROOM_SEQ_RESOURCE = "room-seq"; /** The resource-map ref of the workstream claims. */ export const WORKSTREAM_CLAIMS_RESOURCE = "workstream-claims"; +/** The resource-map ref of the project files. */ +export const PROJECT_FILES_RESOURCE = "project-files"; /** The resource-map ref of the seat answers a room holds. Not re-exported from the package root. */ export const ROOM_ANSWERS_RESOURCE = "room-answers"; /** The resource-map ref of the deliveries a room's fan-out made. Not re-exported from the package root. */ @@ -88,6 +93,17 @@ export const projectRowSchema = z.object({ members: z.array(z.string()).default([]), /** Full mailbox ids of the declared mailboxes this project holds, from any team. */ workstreams: z.array(z.string()).default([]), + /** + * The git remote the project's code lives in, as a member wrote it (for + * example `https://github.com/acme/storefront.git` or + * `git@github.com:acme/storefront.git`), or `null` for a project with no + * repository. A remote, never a folder on some machine: the writes refuse a + * bare path and a value carrying a credential (`repository-value.ts`). + * A row written before the field existed has no key in storage, and stored + * state is not re-parsed on read: read rows through this schema, or guard + * with `== null` (BP-030). + */ + repository: z.string().nullable().default(null), /** * The token each listed workstream's claim carried when this row was written. * A write that drops a workstream deletes its claim only while the claim @@ -116,6 +132,7 @@ const PROJECT_CLIENT_FIELDS = [ "ownerUserId", "members", "workstreams", + "repository", "sessions" ] as const; @@ -359,6 +376,51 @@ const ROOM_DELIVERIES_COLLECTION = defineResourceCollection({ stateSchema: roomDeliverySchema }); +/** + * One file a project keeps, as a workspace projection commits it: its path + * under the project, its content hash, and when it was last synced. The file's + * body is the row's content, not its state. Nullable with a `null` default + * (BP-023), so a row written with less still reads. + */ +export const projectFileSchema = z.object({ + path: z.string().nullable().default(null), + hash: z.string().nullable().default(null), + updatedAt: z.string().nullable().default(null) +}); + +/** @see projectFileSchema */ +export type ProjectFile = z.infer; + +/** + * The files each project keeps, at `project-files//`: an + * agent's notes and memory, and the whole of a no-repository project's code. + * One collection for the organization, keyed by project, so a reader or a + * workspace mount scoped to `/` sees that project's files and no + * other's. Lazy, because a project's files grow without bound; no browser + * read, because only the project's members may read them, through + * `readProjectFiles` (`project-files.ts`). + */ +export function defineProjectFilesCollection() { + return PROJECT_FILES_COLLECTION; +} + +const PROJECT_FILES_COLLECTION = defineResourceCollection({ + pattern: "project-files/**", + scope: "org", + flowIsolation: SHARED_ACROSS_FLOWS, + prefetchMode: "lazy", + stateSchema: projectFileSchema +}); + +/** + * The key prefix of one project's files, relative to the collection: + * `/`. The trailing slash is what keeps `apollo` from reading + * `apollo2`'s files. + */ +export function projectFilesPrefix(projectId: string): string { + return `${projectId}/`; +} + /** Digits a sequence number is padded to, so keys sort by `seq`. */ const SEQ_DIGITS = 12; diff --git a/packages/workforce/src/projects/index.ts b/packages/workforce/src/projects/index.ts index 082ef449d0..1cb6fa9412 100644 --- a/packages/workforce/src/projects/index.ts +++ b/packages/workforce/src/projects/index.ts @@ -2,18 +2,23 @@ * Projects: the organization's `projects` rows, the writes that create them, * and each project's room, reached through a member's own talk session. * - * `collections.ts` is canonical for the keys and row shapes; `talk.ts` for how + * `collections.ts` is canonical for the keys and row shapes; `project-files.ts` + * for a member's read of a project's files; `talk.ts` for how * a session reaches a room; `room-store.ts` for how a room is written and read; * `talk-template.ts` for a room's seats and charter, and the mint on create. * The talk entries are built into every mailbox kind by `defineMailboxFlow`. */ export { + defineProjectFilesCollection, defineProjectsCollection, defineRoomLinesCollection, defineRoomSeqCollection, defineWorkstreamClaimsCollection, NO_PROJECT_ID, + PROJECT_FILES_RESOURCE, + projectFileSchema, + projectFilesPrefix, PROJECTS_RESOURCE, projectRowSchema, projectSessionLinkSchema, @@ -24,6 +29,7 @@ export { roomSeqSchema, WORKSTREAM_CLAIMS_RESOURCE, workstreamClaimSchema, + type ProjectFile, type ProjectRow, type ProjectsCollectionOptions, type ProjectSessionLink, @@ -37,14 +43,24 @@ export { createProjectOutputSchema, defineProjectBlocks, projectWritesMailboxInventory, + setRepositoryInputSchema, + setRepositoryOutputSchema, setWorkstreamsInputSchema, setWorkstreamsOutputSchema, type CreateProjectInput, type CreateProjectOutput, type ProjectBlocks, + type SetRepositoryInput, type SetWorkstreamsInput } from "./project-writes"; +export { + readProjectFilesInputSchema, + readProjectFilesOutputSchema, + type ReadProjectFilesInput, + type ReadProjectFilesOutput +} from "./project-files"; + export { ProjectRefusedError, type ProjectRefusalReason } from "./project-refusal"; export { ROOM_LINE_GRACE_MS, ROOM_PAGE_SIZE } from "./room-store"; diff --git a/packages/workforce/src/projects/project-files.ts b/packages/workforce/src/projects/project-files.ts new file mode 100644 index 0000000000..33a2f51bca --- /dev/null +++ b/packages/workforce/src/projects/project-files.ts @@ -0,0 +1,71 @@ +/** + * `readProjectFiles`: a member's read of the files a project keeps. + * + * The `project-files` collection has no browser read, so this is how a person + * reads them. It checks the session's owner against the row's `members` first + * (`membership-gate.ts`), then lists only `project-files//…`, + * filtered at the source (BP-033), never the whole collection. + */ + +import { handler } from "@flow-state-dev/core"; +import type { BlockContext, ResourceCollectionRef } from "@flow-state-dev/core/types"; +import { z } from "zod"; +import { + defineProjectFilesCollection, + defineProjectsCollection, + PROJECT_FILES_RESOURCE, + projectFilesPrefix, + PROJECTS_RESOURCE, + type ProjectFile, + type ProjectRow +} from "./collections"; +import { isMember } from "./membership-gate"; +import { ProjectRefusedError } from "./project-refusal"; + +/** What reading a project's files takes. */ +export const readProjectFilesInputSchema = z.object({ projectId: z.string().min(1) }).strict(); + +/** @see readProjectFilesInputSchema */ +export type ReadProjectFilesInput = z.infer; + +/** What reading a project's files returns: each file's path under the project, and its body. */ +export const readProjectFilesOutputSchema = z.object({ + files: z.array(z.object({ path: z.string(), content: z.string() })) +}); + +/** @see readProjectFilesOutputSchema */ +export type ReadProjectFilesOutput = z.infer; + +/** The collection's storage prefix, stripped from a ref's `path`. */ +const COLLECTION_PREFIX = `${PROJECT_FILES_RESOURCE}/`; + +/** Read a project's files. Members only; `no-such-project` and `not-a-member` otherwise. */ +export const readProjectFiles = handler({ + name: "project-read-files", + inputSchema: readProjectFilesInputSchema, + outputSchema: readProjectFilesOutputSchema, + resources: { + [PROJECTS_RESOURCE]: defineProjectsCollection(), + [PROJECT_FILES_RESOURCE]: defineProjectFilesCollection() + }, + execute: async (input, rawCtx): Promise => { + const ctx = rawCtx as unknown as BlockContext; + const projects = ctx.resources[PROJECTS_RESOURCE] as unknown as ResourceCollectionRef; + const files = ctx.resources[PROJECT_FILES_RESOURCE] as unknown as ResourceCollectionRef; + const row = await projects.getOptional(input.projectId); + if (row === undefined) { + throw new ProjectRefusedError("no-such-project", `this organization has no project "${input.projectId}".`); + } + if (!isMember(row.state, ctx.session.identity.userId)) { + throw new ProjectRefusedError("not-a-member", `only project "${input.projectId}"'s members may read its files.`); + } + const prefix = projectFilesPrefix(input.projectId); + const out: ReadProjectFilesOutput["files"] = []; + for (const ref of await files.list(prefix)) { + const content = await ref.readContent(); + if (content === null) continue; + out.push({ path: ref.path.slice(COLLECTION_PREFIX.length + prefix.length), content }); + } + return { files: out }; + } +}); diff --git a/packages/workforce/src/projects/project-refusal.ts b/packages/workforce/src/projects/project-refusal.ts index abbda39f02..e3326b3b3a 100644 --- a/packages/workforce/src/projects/project-refusal.ts +++ b/packages/workforce/src/projects/project-refusal.ts @@ -12,6 +12,8 @@ * - `no-such-project`: no row holds the id. * - `project-id-held`: another owner's row holds the id. * - `invalid-project-id`: the id is `unassigned`, empty, or not one path segment. + * - `invalid-repository`: the repository is a path, starts with `-`, or carries a + * credential. The refusal never repeats the value. * - `unknown-workstream`: a workstream id is not a mailbox in the inventory. * - `workstream-claimed`: another project holds the workstream. * - `talk-not-bound`: a room entry ran on a session bound to no project. @@ -24,6 +26,7 @@ export type ProjectRefusalReason = | "no-such-project" | "project-id-held" | "invalid-project-id" + | "invalid-repository" | "unknown-workstream" | "workstream-claimed" | "talk-not-bound" diff --git a/packages/workforce/src/projects/project-writes.ts b/packages/workforce/src/projects/project-writes.ts index eb3dd005fb..280e65443d 100644 --- a/packages/workforce/src/projects/project-writes.ts +++ b/packages/workforce/src/projects/project-writes.ts @@ -1,9 +1,10 @@ /** - * The project writes: `createProject` and `setWorkstreams`. + * The project writes: `createProject`, `setWorkstreams` and `setRepository`. * - * Both are blocks an app installs on the flow that creates projects — its own + * Each is a block an app installs on the flow that creates projects — its own * boot code, or the chief of staff's tool — and {@link defineProjectBlocks} - * also hands back the two as an `actions` map to spread into a flow. + * also hands them back, with the project files read (`project-files.ts`), as + * an `actions` map to spread into a flow. * * **Who the owner is.** The creating session's owner, as the engine recorded * it, never a field of the input. `members` in the input is the creator's own @@ -63,7 +64,9 @@ import { } from "./collections"; import { isMember } from "./membership-gate"; import { isAlreadyExists, isConcurrentModification, isResourceDeleted } from "./store-errors"; +import { readProjectFiles } from "./project-files"; import { ProjectRefusedError } from "./project-refusal"; +import { repositoryProblem } from "./repository-value"; import { noteBindRefusal, TALK_BIND_ACTION, talkSessionKey } from "./talk-template"; /** @@ -96,7 +99,9 @@ export const createProjectInputSchema = z /** Who besides the creator may read and post the room. The creator is always a member. */ members: z.array(z.string().min(1)).optional(), /** Full ids of declared mailboxes, from any team. */ - workstreams: z.array(z.string().min(1)).optional() + workstreams: z.array(z.string().min(1)).optional(), + /** The git remote the project's code lives in. Omitted or `null`: a project with no repository. */ + repository: z.string().nullable().optional() }) .strict(); @@ -124,14 +129,32 @@ export type SetWorkstreamsInput = z.infer; /** What setting a project's workstreams returns: the row as written. */ export const setWorkstreamsOutputSchema = z.object({ project: projectRowSchema }); -/** The two project writes, and the same two as an `actions` map. */ +/** What setting a project's repository takes: the new remote, or `null` to clear it. */ +export const setRepositoryInputSchema = z + .object({ projectId: z.string().min(1), repository: z.string().nullable() }) + .strict(); + +/** @see setRepositoryInputSchema */ +export type SetRepositoryInput = z.infer; + +/** What setting a project's repository returns: the row as written. */ +export const setRepositoryOutputSchema = z.object({ project: projectRowSchema }); + +/** The project writes and the project files read, and the same blocks as an `actions` map. */ export type ProjectBlocks = { createProject: ReturnType; setWorkstreams: typeof setWorkstreams; - actions: { createProject: ActionConfig; setWorkstreams: ActionConfig }; + setRepository: typeof setRepository; + readProjectFiles: typeof readProjectFiles; + actions: { + createProject: ActionConfig; + setWorkstreams: ActionConfig; + setRepository: ActionConfig; + readProjectFiles: ActionConfig; + }; }; -/** One map, shared by both writes: a flow refuses two declarations under one ref. */ +/** One map, shared by every write: a flow refuses two declarations under one ref. */ const WRITE_RESOURCES = { [PROJECTS_RESOURCE]: defineProjectsCollection(), [WORKSTREAM_CLAIMS_RESOURCE]: defineWorkstreamClaimsCollection(), @@ -248,6 +271,13 @@ class ClaimMovedError extends Error { } } +/** Refuse a repository value no row may record. `null` and omitted are a project with none. */ +function assertRepository(repository: string | null | undefined): void { + if (repository == null) return; + const problem = repositoryProblem(repository); + if (problem !== undefined) throw new ProjectRefusedError("invalid-repository", `${problem}.`); +} + const ownerBound = (row: ProjectRow): boolean => row.sessions.some((link) => link.userId === row.ownerUserId); const writeProject = handler({ @@ -259,6 +289,7 @@ const writeProject = handler({ const ctx = rawCtx as unknown as BlockContext; const problem = projectIdProblem(input.id); if (problem !== undefined) throw new ProjectRefusedError("invalid-project-id", `${problem}.`); + assertRepository(input.repository); const owner = ctx.session.identity.userId; if (owner === undefined || owner.length === 0) { throw new Error("createProject needs a session with an owner: the owner is the session's user."); @@ -310,6 +341,7 @@ const writeProject = handler({ ownerUserId: owner, members: unique([owner, ...(input.members ?? [])]), workstreams, + repository: input.repository ?? null, claimTokens: Object.fromEntries(workstreams.map((id) => [id, token])), sessions: [] }); @@ -423,6 +455,37 @@ const setWorkstreams = handler({ } }); +/** + * `setRepository`: set, change or clear a project's repository. Members only. + * The row is rewritten from the state the store hands the updater, so a + * concurrent `join` or `setWorkstreams` keeps what it wrote, and of two + * `setRepository` writes at once the later one wins whole. A lost race is + * retried past the engine's own budget, as the other contended row writes are. + */ +const setRepository = handler({ + name: "project-set-repository", + inputSchema: setRepositoryInputSchema, + outputSchema: setRepositoryOutputSchema, + resources: WRITE_RESOURCES, + execute: async (input, rawCtx) => { + const ctx = rawCtx as unknown as BlockContext; + const { projects } = refsOf(ctx); + const row = await projects.getOptional(input.projectId); + if (row === undefined) { + throw new ProjectRefusedError("no-such-project", `this organization has no project "${input.projectId}".`); + } + if (!isMember(row.state, ctx.session.identity.userId)) { + throw new ProjectRefusedError( + "not-a-member", + `only project "${input.projectId}"'s members may change its repository.` + ); + } + assertRepository(input.repository); + await retryOnConflict(() => row.updateState((state) => ({ ...state, repository: input.repository }))); + return { project: projectRowSchema.parse(row.state) }; + } +}); + /** * After a `setWorkstreams` that did not commit: hand each claim it stamped back * to the row. Decided against the row as it stands at that moment, then @@ -472,7 +535,7 @@ async function settleFailedStamps( } /** - * Build the project writes. + * Build the project writes and the project files read. * * @example * const projects = defineProjectBlocks(); @@ -483,6 +546,8 @@ export function defineProjectBlocks(): ProjectBlocks { return { createProject, setWorkstreams, + setRepository, + readProjectFiles, actions: { createProject: { block: createProject, @@ -492,6 +557,15 @@ export function defineProjectBlocks(): ProjectBlocks { setWorkstreams: { block: setWorkstreams, description: "Replace a project's workstreams. Members only; a workstream belongs to at most one project." + }, + setRepository: { + block: setRepository, + description: + "Set, change or clear (null) the git remote a project's code lives in. Members only; a bare path or a remote carrying a credential is refused." + }, + readProjectFiles: { + block: readProjectFiles, + description: "Read the files a project keeps: each file's path under the project, and its body. Members only." } } }; diff --git a/packages/workforce/src/projects/repository-value.ts b/packages/workforce/src/projects/repository-value.ts new file mode 100644 index 0000000000..5031eccbee --- /dev/null +++ b/packages/workforce/src/projects/repository-value.ts @@ -0,0 +1,76 @@ +/** + * What a project's `repository` may hold: a git remote, the address you'd pass + * to `git clone`, and never a folder on some machine or a secret. + * + * One function, in a module of its own, so `createProject` and `setRepository` + * give the same answer and a test can swap it to prove the writes have no + * other fence (the `any-repository` control). + * + * Two spellings are remotes: a URL (`https://…`, `ssh://…`, `file://…`, any + * `scheme://`), and git's scp-like form `[user@]host:path`, which git + * recognises only when no `/` comes before the first `:`. Anything else is a + * path and is refused. So is a value that starts with `-` (git would read it + * as an option), one holding a control character, a remote-helper address (`ext::…`), and a credential: a user + * or password on `http(s)`, or a password on any scheme. An SSH login name + * (`git@host:org/repo`, `ssh://git@host/org/repo`) is not a credential. + * + * The answer never repeats the value: a refused value may carry a token. + * + * Which schemes and hosts a host actually reaches is the host's call, made + * when it provisions a run; this only decides what a row may record. + */ + +/** A URL remote: a scheme, then `://`. */ +const URL_REMOTE = /^([A-Za-z][A-Za-z0-9+.-]*):\/\//; +/** git's remote-helper syntax, `::
`, such as `ext::sh -c …`. */ +const REMOTE_HELPER = /^[A-Za-z][A-Za-z0-9+.-]*::/; + +const CREDENTIAL = + "the repository carries a credential (a user or password in the address). Give the host its credentials instead"; +const OPTION = 'a repository can\'t start with "-": git would read it as an option'; +const NOT_A_REMOTE = + "the repository is a path, not a remote. Name the address you'd pass to git clone, such as https://github.com/acme/storefront.git or git@github.com:acme/storefront.git"; + +/** + * Why `value` can't be a project's repository, or `undefined` when it can. + * Never includes `value` itself. + */ +export function repositoryProblem(value: string): string | undefined { + if (value.length === 0) return "a repository can't be empty. Send null to clear it"; + if (value !== value.trim()) return "a repository can't start or end with whitespace"; + // A URL parser drops a newline or tab silently, so the stored string and the parsed one would differ. + if (/[\u0000-\u001f\u007f]/.test(value)) return "a repository can't contain control characters"; + if (value.startsWith("-")) return OPTION; + if (REMOTE_HELPER.test(value)) return "a repository can't be a remote-helper address (transport::address)"; + + const url = URL_REMOTE.exec(value); + if (url !== null) { + let parsed: URL; + try { + parsed = new URL(value); + } catch { + return "the repository is not a valid URL"; + } + const scheme = url[1]!.toLowerCase(); + if (parsed.password !== "") return CREDENTIAL; + if ((scheme === "http" || scheme === "https") && parsed.username !== "") return CREDENTIAL; + if (parsed.hostname.startsWith("-")) return OPTION; + if (scheme !== "file" && parsed.hostname === "") return "the repository URL names no host"; + return undefined; + } + + // scp-like: `[user@]host:path`, only when no `/` comes before the first `:`. + const colon = value.indexOf(":"); + const slash = value.indexOf("/"); + if (colon <= 0 || (slash !== -1 && slash < colon)) return NOT_A_REMOTE; + const at = value.indexOf("@"); + if (at !== -1 && value.slice(0, at).includes(":")) return CREDENTIAL; + const login = value.slice(0, colon); + const host = login.slice(login.lastIndexOf("@") + 1); + // `C:\code` or `C:/code`: a Windows drive, not a one-letter host. + if (/^[A-Za-z]$/.test(login) && /^[\\/]/.test(value.slice(colon + 1))) return NOT_A_REMOTE; + if (host.length === 0) return "the repository names no host"; + if (host.startsWith("-")) return OPTION; + if (colon === value.length - 1) return "the repository names no path on its host"; + return undefined; +} diff --git a/packages/workforce/test/projects.test.ts b/packages/workforce/test/projects.test.ts index 91843f56bc..a1fdb44375 100644 --- a/packages/workforce/test/projects.test.ts +++ b/packages/workforce/test/projects.test.ts @@ -3,18 +3,21 @@ * in one organization: `alice` and `bob` (members), and `mallory` (in the org, * not a member). * - * Covers the row writes (`createProject`, `setWorkstreams`, workstream claims, - * the bind repair) and the room (`join`, `post`, `read { after }`, the + * Covers the row writes (`createProject`, `setWorkstreams`, `setRepository`, + * workstream claims, the bind repair), the project files read, and the room (`join`, `post`, `read { after }`, the * membership gate, the counter's retry and its committed watermark). Identity * comes from a verified header, never the body (BP-031). * - * **Controls.** Two modules are swappable on purpose, and each swap must turn + * **Controls.** Three modules are swappable on purpose, and each swap must turn * this file red: * * FSD_CONTROL=no-gate pnpm --filter @flow-state-dev/workforce exec vitest run test/projects.test.ts * The membership gate admits everyone: the outsider tests fail. * FSD_CONTROL=no-retry pnpm --filter @flow-state-dev/workforce exec vitest run test/projects.test.ts - * The room's own retry runs once: the post burst and the join burst lose writes. + * The room's own retry runs once: the post burst, the join burst and the + * repository burst lose writes. + * FSD_CONTROL=any-repository pnpm --filter @flow-state-dev/workforce exec vitest run test/projects.test.ts + * The repository check admits every value: the invalid-repository test fails. */ import { describe, expect, it, vi } from "vitest"; import { defineFlow, handler } from "@flow-state-dev/core"; @@ -28,11 +31,13 @@ import { mailboxFlow, defineMailboxInventoryCollection, defineProjectBlocks, + defineProjectFilesCollection, defineProjectsCollection, projectWritesMailboxInventory, defineRoomLinesCollection, defineRoomSeqCollection, defineWorkstreamClaimsCollection, + projectRowSchema, roomLineKey, type RoomLine, type RoomSeq @@ -43,6 +48,9 @@ import { postedLines } from "./mailbox-post-lines"; vi.mock("../src/projects/membership-gate", async (original) => process.env.FSD_CONTROL === "no-gate" ? { isMember: () => true } : original() ); +vi.mock("../src/projects/repository-value", async (original) => + process.env.FSD_CONTROL === "any-repository" ? { repositoryProblem: () => undefined } : original() +); vi.mock("../src/projects/cas-retry", async (original) => { const real = (await original()) as Record; return process.env.FSD_CONTROL === "no-retry" @@ -59,6 +67,7 @@ const inventory = defineMailboxInventoryCollection(); const claims = defineWorkstreamClaimsCollection(); const projects = defineProjectsCollection(); const rooms = { lines: defineRoomLinesCollection(), seq: defineRoomSeqCollection() }; +const projectFiles = defineProjectFilesCollection(); /** Registers the declared mailboxes, as `openInventory` does at boot. */ const seedMailboxes = handler({ @@ -108,11 +117,26 @@ const roomStep = (name: string, run: (input: any, ctx: unknown) => Promise { + const files = ctx.resources["project-files"] as unknown as ResourceCollectionRef; + const ref = await files.create(input.key, { path: input.key, hash: "seeded", updatedAt: "2026-10-04T00:00:00.000Z" }); + await ref.writeContent(input.content); + return {}; + } +}); + const projectBlocks = defineProjectBlocks(); const labFlow = defineFlow({ kind: "lab", actions: { ...projectBlocks.actions, + seedProjectFile: { block: seedProjectFile }, inspect: { block: inspect }, allocate: { block: roomStep("allocate", (i, ctx) => allocateSeq(roomRefs(ctx), i.projectId)) }, writeAt: { @@ -644,6 +668,232 @@ describe("project rows under racing writes", () => { }); }); +describe("a project's repository", () => { + it("records the repository a project is created with, and null when none is given", async () => { + const h = await boot(); + const lab = await h.openSession("alice", "lab"); + const named = await h.ok("alice", "lab", lab, "createProject", { + id: "storefront", + title: "Storefront", + repository: "https://github.com/acme/storefront.git" + }); + const bare = await h.ok("alice", "lab", lab, "createProject", { id: "sandbox", title: "Sandbox" }); + expect(named.project.repository).toBe("https://github.com/acme/storefront.git"); + expect(bare.project.repository).toBeNull(); + expect((await h.inspectRow("storefront")).row.repository).toBe("https://github.com/acme/storefront.git"); + expect((await h.inspectRow("sandbox")).row.repository).toBeNull(); + + // Anyone in the org reads it with the row, as Shift Manager's Brief does. + const malloryLab = await h.openSession("mallory", "lab"); + const listed = await h.call("GET", "mallory", ["sessions", malloryLab, "resources", "projects"]); + const byId = Object.fromEntries(listed.json.items.map((i: any) => [i.clientData.id, i.clientData.repository])); + expect(byId).toEqual({ storefront: "https://github.com/acme/storefront.git", sandbox: null }); + }); + + it("lets a member set, change and clear it, and moves nothing else on the row", async () => { + const h = await boot(); + await apollo(h); + const before = (await h.inspectRow("apollo")).row; + const bobLab = await h.openSession("bob", "lab"); + const without = ({ repository, ...rest }: Record) => rest; + + for (const repository of ["https://github.com/acme/storefront.git", "git@github.com:acme/shop.git", null]) { + const out = await h.ok("bob", "lab", bobLab, "setRepository", { projectId: "apollo", repository }); + expect(out.project.repository).toBe(repository); + const row = (await h.inspectRow("apollo")).row; + expect(row.repository).toBe(repository); + expect(without(row)).toEqual(without(before)); + } + }); + + // Each refused value is refused by both writes, and its refusal never repeats + // the value: a credential in it would otherwise reach logs and the request record. + const REFUSED_REPOSITORIES: Array<[string, string]> = [ + ["an absolute path", "/srv/git/storefront"], + ["a relative path", "./storefront"], + ["a parent path", "../storefront"], + ["a home path", "~/code/storefront"], + ["a bare name", "storefront"], + ["a Windows path", "C:\\code\\storefront"], + ["a Windows path with forward slashes", "C:/code/storefront"], + ["an empty value", ""], + ["a leading dash", "--upload-pack=touch /tmp/pwned"], + ["a leading dash, short", "-oProxyCommand=touch"], + ["leading whitespace hiding a dash", " -oProxyCommand=touch"], + ["an ssh host that is an option", "ssh://-oProxyCommand=touch/x/y"], + ["a remote helper", "ext::sh -c touch% /tmp/pwned"], + ["a user and password on https", "https://alice:hunter2@github.com/acme/storefront.git"], + ["a token as the https user", "https://ghp_tokenvalue@github.com/acme/storefront.git"], + ["a user on http", "http://alice@git.internal/acme/storefront.git"], + ["a password on ssh", "ssh://git:hunter2@github.com/acme/storefront.git"], + ["a password in the scp form", "git:hunter2@github.com:acme/storefront.git"], + ["a control character", "https://github.com/acme/store\nfront.git"] + ]; + const ACCEPTED_REPOSITORIES = [ + "https://github.com/acme/storefront.git", + "https://github.com/acme/storefront", + "git@github.com:acme/storefront.git", + "ssh://git@github.com/acme/storefront.git", + "ssh://github.com:2222/acme/storefront.git", + "file:///srv/git/storefront.git" + ]; + + it("refuses a bare path, a leading dash and a credential as invalid-repository, without repeating the value", async () => { + const h = await boot(); + await apollo(h); + const before = (await h.inspectRow("apollo")).row; + const lab = await h.openSession("alice", "lab"); + for (const [what, repository] of REFUSED_REPOSITORIES) { + const set = await h.act("alice", "lab", lab, "setRepository", { projectId: "apollo", repository }); + const create = await h.act("alice", "lab", lab, "createProject", { id: "fresh", title: "Fresh", repository }); + for (const result of [set, create]) { + expect(result.settled, what).not.toBe("completed"); + expect(refusal(result), what).toContain("invalid-repository"); + for (const secret of ["hunter2", "ghp_tokenvalue"]) expect(refusal(result), what).not.toContain(secret); + } + } + expect((await h.inspectRow("apollo")).row).toEqual(before); + expect((await h.inspectRow("fresh")).row).toBeNull(); + }); + + it("accepts both SSH spellings, https, a custom port and file://, on create and on set", async () => { + const h = await boot(); + await apollo(h); + const lab = await h.openSession("alice", "lab"); + for (const [i, repository] of ACCEPTED_REPOSITORIES.entries()) { + const set = await h.ok("alice", "lab", lab, "setRepository", { projectId: "apollo", repository }); + expect(set.project.repository).toBe(repository); + const created = await h.ok("alice", "lab", lab, "createProject", { id: `p${i}`, title: "P", repository }); + expect(created.project.repository).toBe(repository); + } + }); + + it("reads a row written before the field existed as a project with no repository, and sets one on it", async () => { + const h = await boot(); + // Learn where a row is stored by watching one be written. + const states = h.stores.resourceState; + const set = states.set.bind(states); + let where: { scopeType: Parameters[0]; scopeId: string; key: string } | undefined; + states.set = async (scopeType, scopeId, key, state, expected) => { + if (where === undefined && /(^|\/)projects\/seed$/.test(key)) where = { scopeType, scopeId, key }; + return set(scopeType, scopeId, key, state, expected); + }; + await h.ok("alice", "lab", await h.openSession("alice", "lab"), "createProject", { id: "seed", title: "Seed" }); + states.set = set; + expect(where).toBeDefined(); + + // The stored shape of a row from before `repository`: the key is absent. + const { scopeType, scopeId, key } = where!; + const legacy: Record = { ...(await states.get(scopeType, scopeId, key))!.state, id: "old", title: "Old" }; + delete legacy.repository; + const oldKey = key.replace(/seed$/, "old"); + expect((await set(scopeType, scopeId, oldKey, legacy as never, "absent")).ok).toBe(true); + expect(Object.keys((await states.get(scopeType, scopeId, oldKey))!.state)).not.toContain("repository"); + + // Stored state is not re-parsed on read, so a reader parses the row (or + // guards with `== null`, as a browser reader does), and either way it is a + // project with no repository. + expect(projectRowSchema.parse((await h.inspectRow("old")).row).repository).toBeNull(); + const malloryLab = await h.openSession("mallory", "lab"); + const listed = await h.call("GET", "mallory", ["sessions", malloryLab, "resources", "projects"]); + expect(listed.json.items.find((i: any) => i.clientData.id === "old").clientData.repository ?? null).toBeNull(); + const lab = await h.openSession("alice", "lab"); + const resent = await h.ok("alice", "lab", lab, "createProject", { id: "old", title: "Old" }); + expect(resent).toMatchObject({ created: false, project: { id: "old", repository: null } }); + + const written = await h.ok("alice", "lab", lab, "setRepository", { projectId: "old", repository: "git@github.com:acme/old.git" }); + expect(written.project).toMatchObject({ id: "old", title: "Old", ownerUserId: "alice", repository: "git@github.com:acme/old.git" }); + }); + + it("keeps one value whole, and every other write, when a burst of members set it at once", async () => { + const h = await boot(); + const lab = await h.openSession("alice", "lab"); + const people = ["alice", "bob", "carol", "dave", "erin", "frank", "grace", "heidi"]; + await h.ok("alice", "lab", lab, "createProject", { id: "race", title: "Race", members: people.slice(1) }); + const values = people.map((user) => `https://github.com/acme/${user}.git`); + const labs = await Promise.all(people.map((user) => h.openSession(user, "lab"))); + const talks = await Promise.all(people.map((user) => h.openSession(user, MAILBOX_KIND))); + // Each member sets its own value twice while joining the room: the joins + // write `sessions` on the same row, so every write contends with the rest. + const outcomes = await Promise.all([ + ...people.flatMap((user, i) => [ + h.act(user, "lab", labs[i]!, "setRepository", { projectId: "race", repository: values[i] }), + h.act(user, "lab", labs[i]!, "setRepository", { projectId: "race", repository: values[i] }) + ]), + ...people.map((user, i) => h.act(user, MAILBOX_KIND, talks[i]!, "join", { projectId: "race" })) + ]); + expect(outcomes.filter((o) => o.settled !== "completed").map(refusal)).toEqual([]); + const row = (await h.inspectRow("race")).row; + expect(values).toContain(row.repository); + expect(row.sessions.map((s: { userId: string }) => s.userId).sort()).toEqual([...people].sort()); + expect(row.members).toEqual(people); + }); + + it("refuses a non-member and an unknown project, and writes nothing", async () => { + const h = await boot(); + await apollo(h); + const before = (await h.inspectRow("apollo")).row; + const malloryLab = await h.openSession("mallory", "lab"); + const outsider = await h.act("mallory", "lab", malloryLab, "setRepository", { + projectId: "apollo", + repository: "https://github.com/mallory/evil.git" + }); + expect(outsider.settled).not.toBe("completed"); + expect(refusal(outsider)).toContain("not-a-member"); + const nowhere = await h.act("mallory", "lab", malloryLab, "setRepository", { projectId: "nope", repository: null }); + expect(refusal(nowhere)).toContain("no-such-project"); + expect((await h.inspectRow("apollo")).row).toEqual(before); + expect((await h.inspectRow("nope")).row).toBeNull(); + }); +}); + +describe("a project's files", () => { + it("is declared org-scoped, shared across flows, lazy, and with no browser read", () => { + expect(projectFiles).toMatchObject({ pattern: "project-files/**", scope: "org", flowIsolation: false, prefetchMode: "lazy" }); + expect((projectFiles as { client?: unknown }).client).toBeUndefined(); + expect(defineProjectFilesCollection()).toBe(projectFiles); + }); + + it("hands a member the files under the project's id, and no other project's", async () => { + const h = await boot(); + await apollo(h); + const lab = await h.openSession("alice", "lab"); + await h.ok("alice", "lab", lab, "createProject", { id: "apollo2", title: "Apollo 2" }); + await h.ok("alice", "lab", lab, "seedProjectFile", { key: "apollo/notes.md", content: "# Notes" }); + await h.ok("alice", "lab", lab, "seedProjectFile", { key: "apollo/src/index.ts", content: "export {};" }); + // A project whose id starts with the other's: a bare prefix match would leak it. + await h.ok("alice", "lab", lab, "seedProjectFile", { key: "apollo2/plan.md", content: "not apollo's" }); + + const bobLab = await h.openSession("bob", "lab"); + const read = await h.ok("bob", "lab", bobLab, "readProjectFiles", { projectId: "apollo" }); + expect([...read.files].sort((a: { path: string }, b: { path: string }) => a.path.localeCompare(b.path))).toEqual([ + { path: "notes.md", content: "# Notes" }, + { path: "src/index.ts", content: "export {};" } + ]); + expect((await h.ok("alice", "lab", lab, "readProjectFiles", { projectId: "apollo2" })).files).toEqual([ + { path: "plan.md", content: "not apollo's" } + ]); + }); + + it("refuses a non-member, an unknown project, and a browser read of the collection", async () => { + const h = await boot(); + await apollo(h); + const lab = await h.openSession("alice", "lab"); + await h.ok("alice", "lab", lab, "seedProjectFile", { key: "apollo/notes.md", content: "secret plan" }); + + const malloryLab = await h.openSession("mallory", "lab"); + const outsider = await h.act("mallory", "lab", malloryLab, "readProjectFiles", { projectId: "apollo" }); + expect(outsider.settled).not.toBe("completed"); + expect(refusal(outsider)).toContain("not-a-member"); + expect(refusal(outsider)).not.toContain("secret plan"); + expect(refusal(await h.act("mallory", "lab", malloryLab, "readProjectFiles", { projectId: "nope" }))).toContain( + "no-such-project" + ); + expect((await h.call("GET", "mallory", ["sessions", malloryLab, "resources", "project-files"])).status).toBe(403); + expect((await h.call("GET", "alice", ["sessions", lab, "resources", "project-files"])).status).toBe(403); + }); +}); + describe("a project's room", () => { it("two members read each other's lines by cursor, each through their own session", async () => { const h = await boot(); From fb8a2495706f8729f979d7ab3cf5697c0d92845d Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 21:30:39 +0000 Subject: [PATCH 20/28] docs(workforce): say worker, not seat, in the project tools line Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01UyaSbP7u4EMjKM6U3bXQ6t --- packages/workforce/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/workforce/README.md b/packages/workforce/README.md index 4725ac5687..a3e4116013 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2051,7 +2051,7 @@ defineFlow({ kind: "lab", actions: { ...projects.actions } }); project keeps in the org's `project-files` collection (`defineProjectFilesCollection()`), at `project-files//`. Members only. The collection is org-scoped, shared, lazy, and has no browser read. -- **As a seat's tools.** Put the writes in `defineAgentWorkerFlow({ catalog })` under the names a seat's +- **As a worker's tools.** Put the writes in `defineAgentWorkerFlow({ catalog })` under the names a worker's `tools:` spells. A catalog key must be the tool's own name, so wrap each in a one-step `sequencer({ name: "createProject", inputSchema: createProjectInputSchema, outputSchema: createProjectOutputSchema }).step(projects.createProject)`. The owner is the session the seat From bb13b589bf8a3dc93d6bf895303d26cbfcd84c30 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 21:45:03 +0000 Subject: [PATCH 21/28] fix(engine): a lazy collection's list(prefix) loads only that sub-prefix readProjectFiles lists one project's files, but the lazy wrapper loaded the whole project-files/ collection for the org first. Push the caller's prefix to the loader, and treat an already-loaded ancestor prefix as covering it. Also condense the FIX-1762 changeset to one sentence. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01UyaSbP7u4EMjKM6U3bXQ6t --- .changeset/project-repository-and-files.md | 2 +- .../src/context/createExecutionContext.ts | 5 ++-- .../engine/src/context/resource-registry.ts | 9 ++++--- .../test/prefetch-lazy-collection.test.ts | 27 +++++++++++++++++++ 4 files changed, 36 insertions(+), 7 deletions(-) diff --git a/.changeset/project-repository-and-files.md b/.changeset/project-repository-and-files.md index 96ab39d58b..99446a7f98 100644 --- a/.changeset/project-repository-and-files.md +++ b/.changeset/project-repository-and-files.md @@ -2,4 +2,4 @@ "@flow-state-dev/workforce": minor --- -A project row records the git remote its code lives in: `repository: string | null`, default `null`, readable from the browser with the row. `createProject` takes an optional `repository`, and the new `setRepository { projectId, repository }` sets, changes or clears it for a member. Both refuse a path, a value starting with `-`, a control character, a remote-helper address and a value carrying a credential with the new refusal reason `invalid-repository`, without repeating the value. Stored rows are not re-parsed on read, so treat a missing `repository` as `null` or read through `projectRowSchema.parse`. A project's files live in the new org-scoped `project-files//…` collection (`defineProjectFilesCollection()`), with no browser read; members read them with the new `readProjectFiles` block, also in `defineProjectBlocks().actions` (FIX-1762). +A project can record its git remote (`repository`, set with `createProject` or the new `setRepository`) and keep members-only files in the new `project-files` collection, read with `readProjectFiles` (FIX-1762). diff --git a/packages/engine/src/context/createExecutionContext.ts b/packages/engine/src/context/createExecutionContext.ts index 849b25f654..579c47d0cb 100644 --- a/packages/engine/src/context/createExecutionContext.ts +++ b/packages/engine/src/context/createExecutionContext.ts @@ -1682,9 +1682,8 @@ export async function createExecutionContext< async getByPrefix(keyPrefix: string): Promise { // FIX-735: the collection's prefix resolves to its isolation bucket. const scopeId = resolveResourceStorageScopeId(scope, keyPrefix)!; - if (loadedCollectionPrefixes[scope].has(coverageToken(scopeId, keyPrefix))) { - return { fetched: false, durationMs: 0 }; - } + // A loaded ancestor prefix (the whole collection) already covers a sub-prefix. + if (isMissAuthoritative(scope, keyPrefix)) return { fetched: false, durationMs: 0 }; let fetched = false; let durationMs = 0; await runSingleFlight(`${scope}:prefix:${keyPrefix}`, async () => { diff --git a/packages/engine/src/context/resource-registry.ts b/packages/engine/src/context/resource-registry.ts index 4d0301f319..d23d90ba2a 100644 --- a/packages/engine/src/context/resource-registry.ts +++ b/packages/engine/src/context/resource-registry.ts @@ -1893,7 +1893,10 @@ export function createScopeResourceRegistry): Promise => lazyLoad.getInstance(resolveCollectionKey(nsConfig.pattern, key)); - const ensurePrefix = (): Promise => lazyLoad.getByPrefix(collectionKeyPrefix); + // A scoped `list(prefix)` loads only that sub-tree, so one caller's read + // never pulls its siblings' rows and content into memory. + const ensurePrefix = (prefix?: string): Promise => + lazyLoad.getByPrefix(`${collectionKeyPrefix}${prefix ?? ""}`); // FIX-701: record a lazy read — `cacheHit = !fetched` (true when the // ensure short-circuited on an already-loaded key/prefix), with the // store round-trip's wall time. The accessor that triggered it is the @@ -1931,8 +1934,8 @@ export function createScopeResourceRegistry[]> { - const outcome = await ensurePrefix(); - recordLazyRead("list", collectionKeyPrefix, outcome); + const outcome = await ensurePrefix(prefix); + recordLazyRead("list", `${collectionKeyPrefix}${prefix ?? ""}`, outcome); return nsHandle.list(prefix); }, async count(): Promise { diff --git a/packages/engine/test/prefetch-lazy-collection.test.ts b/packages/engine/test/prefetch-lazy-collection.test.ts index b6a6b6dfa8..20eee0d43c 100644 --- a/packages/engine/test/prefetch-lazy-collection.test.ts +++ b/packages/engine/test/prefetch-lazy-collection.test.ts @@ -119,6 +119,33 @@ describe("FIX-688: lazy collection accessor", () => { expect(get.mock.calls.filter((c) => c[2] === "lz/a").length).toBe(0); // served from warmed cache }); + it("list(prefix) reads only that sub-prefix from the store", async () => { + const { stores, getByPrefix } = spyStores(); + await stores.resourceState.set("session", "s1", "lz/p1/a", { n: 1 }, "any"); + await stores.resourceState.set("session", "s1", "lz/p2/b", { n: 2 }, "any"); + const ctx = await ctxFor(stores); + getByPrefix.mockClear(); + + const p1 = await coll(ctx).list("p1/"); + expect(p1.map((r) => r.state.n)).toEqual([1]); + const prefixes = getByPrefix.mock.calls.map((c) => c[2]); + // A list scoped to one sub-tree must not pull its siblings into memory. + expect(prefixes).toEqual(["lz/p1/"]); + }); + + it("list(prefix) after a whole-collection list costs no further store read", async () => { + const { stores, getByPrefix } = spyStores(); + await stores.resourceState.set("session", "s1", "lz/p1/a", { n: 1 }, "any"); + await stores.resourceState.set("session", "s1", "lz/p2/b", { n: 2 }, "any"); + const ctx = await ctxFor(stores); + getByPrefix.mockClear(); + + await coll(ctx).list(); + const p2 = await coll(ctx).list("p2/"); + expect(p2.map((r) => r.state.n)).toEqual([2]); + expect(getByPrefix.mock.calls.map((c) => c[2])).toEqual(["lz/"]); + }); + it("does not resurrect a key deleted while the prefix read was in flight", async () => { const { stores } = spyStores(); await stores.resourceState.set("session", "s1", "lz/a", { n: 1 }, "any"); From b11c0b6984093ae67fabd172e590c42dda9061bb Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 21:48:07 +0000 Subject: [PATCH 22/28] fix(workforce): readProjectFiles lists path and size, never file bodies A handler's output is logged as the tool result, so returning every file's body would put a whole project's files into the session log and the model's context. Return each file's path and UTF-8 byte size instead. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01UyaSbP7u4EMjKM6U3bXQ6t --- apps/docs/docs/workforce/projects.md | 10 ++++++---- packages/workforce/README.md | 3 ++- .../workforce/src/projects/project-files.ts | 13 +++++++++---- packages/workforce/test/projects.test.ts | 18 +++++++++++++++--- 4 files changed, 32 insertions(+), 12 deletions(-) diff --git a/apps/docs/docs/workforce/projects.md b/apps/docs/docs/workforce/projects.md index 1607413420..672c3a12af 100644 --- a/apps/docs/docs/workforce/projects.md +++ b/apps/docs/docs/workforce/projects.md @@ -187,21 +187,23 @@ Stored rows aren't re-parsed when they're read, so a row saved without a `reposi Notes, memory and anything else kept for a project live in the organization's `project-files` collection, under the project's id: `project-files//`. Declare it with `defineProjectFilesCollection()`. Like `defineProjectsCollection()`, every call returns the same declaration. It's org-scoped, shared across flows, and loaded only when read. -Only the project's members can read the files, with `readProjectFiles`: +Only the project's members can list the files, with `readProjectFiles`: ```ts // input { projectId: "storefront" } -// output: each file's path under the project, and its body +// output: each file's path under the project, and its size in bytes { files: [ - { path: "notes.md", content: "# Notes" }, - { path: "src/index.ts", content: "export {};" }, + { path: "notes.md", size: 7 }, + { path: "src/index.ts", size: 10 }, ], } ``` +It lists paths and sizes, not file contents. A block's output is recorded in the session log and can reach a model's context, so a listing stays small however large the files are. + It returns that project's files, never another project's. A non-member is refused with `not-a-member`, and an unknown id with `no-such-project`. The collection has no browser read: a request for it through the collection route gets a 403. ## The room and talk sessions diff --git a/packages/workforce/README.md b/packages/workforce/README.md index a3e4116013..6df37d01bb 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2047,7 +2047,8 @@ defineFlow({ kind: "lab", actions: { ...projects.actions } }); repeat the value. `git@host:org/repo` and `ssh://git@host/org/repo` are accepted. Stored rows aren't re-parsed on read: treat a missing `repository` as `null`, or read through `projectRowSchema.parse`. -- **`readProjectFiles { projectId }`** returns `{ files: [{ path, content }] }`, the files the +- **`readProjectFiles { projectId }`** returns `{ files: [{ path, size }] }` (size in UTF-8 bytes, + never the body, since the output is logged as the tool result), the files the project keeps in the org's `project-files` collection (`defineProjectFilesCollection()`), at `project-files//`. Members only. The collection is org-scoped, shared, lazy, and has no browser read. diff --git a/packages/workforce/src/projects/project-files.ts b/packages/workforce/src/projects/project-files.ts index 33a2f51bca..5e6598ba93 100644 --- a/packages/workforce/src/projects/project-files.ts +++ b/packages/workforce/src/projects/project-files.ts @@ -4,7 +4,10 @@ * The `project-files` collection has no browser read, so this is how a person * reads them. It checks the session's owner against the row's `members` first * (`membership-gate.ts`), then lists only `project-files//…`, - * filtered at the source (BP-033), never the whole collection. + * filtered at the source (BP-033), never the whole collection. It returns each + * file's path and size, never its body: a handler's output is logged as the + * tool result, so a body here would land whole in the session log and the + * model's context. */ import { handler } from "@flow-state-dev/core"; @@ -28,14 +31,16 @@ export const readProjectFilesInputSchema = z.object({ projectId: z.string().min( /** @see readProjectFilesInputSchema */ export type ReadProjectFilesInput = z.infer; -/** What reading a project's files returns: each file's path under the project, and its body. */ +/** What reading a project's files returns: each file's path under the project, and its size in UTF-8 bytes. */ export const readProjectFilesOutputSchema = z.object({ - files: z.array(z.object({ path: z.string(), content: z.string() })) + files: z.array(z.object({ path: z.string(), size: z.number().int().nonnegative() })) }); /** @see readProjectFilesOutputSchema */ export type ReadProjectFilesOutput = z.infer; +const utf8 = new TextEncoder(); + /** The collection's storage prefix, stripped from a ref's `path`. */ const COLLECTION_PREFIX = `${PROJECT_FILES_RESOURCE}/`; @@ -64,7 +69,7 @@ export const readProjectFiles = handler({ for (const ref of await files.list(prefix)) { const content = await ref.readContent(); if (content === null) continue; - out.push({ path: ref.path.slice(COLLECTION_PREFIX.length + prefix.length), content }); + out.push({ path: ref.path.slice(COLLECTION_PREFIX.length + prefix.length), size: utf8.encode(content).length }); } return { files: out }; } diff --git a/packages/workforce/test/projects.test.ts b/packages/workforce/test/projects.test.ts index a1fdb44375..b991732cbf 100644 --- a/packages/workforce/test/projects.test.ts +++ b/packages/workforce/test/projects.test.ts @@ -866,12 +866,24 @@ describe("a project's files", () => { const bobLab = await h.openSession("bob", "lab"); const read = await h.ok("bob", "lab", bobLab, "readProjectFiles", { projectId: "apollo" }); + // Path and UTF-8 byte size only: the output is logged as the tool result, so a body never rides in it. expect([...read.files].sort((a: { path: string }, b: { path: string }) => a.path.localeCompare(b.path))).toEqual([ - { path: "notes.md", content: "# Notes" }, - { path: "src/index.ts", content: "export {};" } + { path: "notes.md", size: 7 }, + { path: "src/index.ts", size: 10 } ]); + expect(JSON.stringify(read)).not.toContain("# Notes"); expect((await h.ok("alice", "lab", lab, "readProjectFiles", { projectId: "apollo2" })).files).toEqual([ - { path: "plan.md", content: "not apollo's" } + { path: "plan.md", size: 12 } + ]); + }); + + it("counts a file's size in UTF-8 bytes, not characters", async () => { + const h = await boot(); + await apollo(h); + const lab = await h.openSession("alice", "lab"); + await h.ok("alice", "lab", lab, "seedProjectFile", { key: "apollo/café.md", content: "café" }); + expect((await h.ok("alice", "lab", lab, "readProjectFiles", { projectId: "apollo" })).files).toEqual([ + { path: "café.md", size: 5 } ]); }); From 04717255a9529195272dfbc19d21ac040b25e3da Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 22:34:27 +0000 Subject: [PATCH 23/28] feat(workforce): projectWorkspace, the run source for a project's board (FIX-1762) A coding run on a mailbox board now gets its files from the project that holds the board's workstream: board -> mailbox (derived from the board's minted id) -> the workstream's claim -> the project row -> its repository with the project's files beside the checkout, or the project's files alone. Reads only the claim and the row; refuses a run whose owner is not a member, or whose workstream no project holds, before any file is read. projectWorkspaceCapability declares the collections it reads. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5 --- .changeset/project-workspace-run-source.md | 5 + packages/workforce/README.md | 19 ++ packages/workforce/package.json | 1 + packages/workforce/src/projects/index.ts | 10 +- .../src/projects/project-workspace.ts | 185 +++++++++++++ .../workforce/test/project-workspace.test.ts | 255 ++++++++++++++++++ packages/workforce/tsconfig.json | 2 +- pnpm-lock.yaml | 3 + 8 files changed, 478 insertions(+), 2 deletions(-) create mode 100644 .changeset/project-workspace-run-source.md create mode 100644 packages/workforce/src/projects/project-workspace.ts create mode 100644 packages/workforce/test/project-workspace.test.ts diff --git a/.changeset/project-workspace-run-source.md b/.changeset/project-workspace-run-source.md new file mode 100644 index 0000000000..3e9762903f --- /dev/null +++ b/.changeset/project-workspace-run-source.md @@ -0,0 +1,5 @@ +--- +"@flow-state-dev/workforce": minor +--- + +`projectWorkspace({ board })` is a run source for a workspace host: a coding run on a project's mailbox board works in a branch of the project's repository with the project's files beside it, or on the project's files alone when it has no repository. It refuses a run whose owner is not a member, or whose workstream no project holds. The block that asks it holds `projectWorkspaceCapability` (FIX-1762). diff --git a/packages/workforce/README.md b/packages/workforce/README.md index 6df37d01bb..877752f16f 100644 --- a/packages/workforce/README.md +++ b/packages/workforce/README.md @@ -2052,6 +2052,24 @@ defineFlow({ kind: "lab", actions: { ...projects.actions } }); project keeps in the org's `project-files` collection (`defineProjectFilesCollection()`), at `project-files//`. Members only. The collection is org-scoped, shared, lazy, and has no browser read. +- **`projectWorkspace({ board })`** is a run source for a workspace host (`@flow-state-dev/workspace`): + for a run on that mailbox board, the repository of the project that holds the board's + workstream, with the project's files beside the checkout, or the project's files alone when it + has no repository. It reads only the workstream's claim and the project row, and refuses the run + with `no-project` when no project holds the workstream and `not-a-member` when the run's owner is + not one of the project's members. The block that asks it must hold + `projectWorkspaceCapability`; with harness-manager, pass it on `uses`: + + ```ts + const work = mailboxBoard("eng.feature", "work"); + harnessManager({ + boardCollectionId: work.id, + boardCollection: work, + workspace: localWorkspaceHost({ root, remotes: { allow: ["github.com"] }, source: projectWorkspace({ board: work }) }), + uses: [projectWorkspaceCapability], + // ... + }); + ``` - **As a worker's tools.** Put the writes in `defineAgentWorkerFlow({ catalog })` under the names a worker's `tools:` spells. A catalog key must be the tool's own name, so wrap each in a one-step `sequencer({ name: "createProject", inputSchema: createProjectInputSchema, outputSchema: @@ -2202,6 +2220,7 @@ before fire removed inventory rows is left out that way. | `defineProjectsCollection({ talk? })` | The organization's `projects` collection: org-scoped, shared across flows, browser-readable through `expose`. `talk` is the org-level talk template: the first one declared stands, the same one again is a no-op, and a different one throws. You can call `defineProjectsCollection()` anywhere you need it. Every call returns the same declaration, so they never conflict. `defineRoomLinesCollection`, `defineRoomSeqCollection` and `defineWorkstreamClaimsCollection` declare the room and the claims; none has a browser read. | | `projectWritesMailboxInventory` | The mailbox inventory declaration the project writes read. A flow that installs the writes and reads the inventory itself declares that read with this object, under any accessor; its own `defineMailboxInventoryCollection()` there is a resource collision when the flow is built. | | `defineProjectBlocks()` | Returns `{ createProject, setWorkstreams, actions }`. See [Projects](#projects). A created project's `bind` is dispatched to the built-in `mailbox` kind. | +| `projectWorkspace({ board })` / `projectWorkspaceCapability` | A run source for a coding run on a project's mailbox board, and the capability holding the collections it reads. See [Projects](#projects). | | `openMailboxes(manifests, { client, userId })` | Runtime. One named session per record, carrying its members, charter and description. The server binds each session's organization. Idempotent. | | `readMailboxesDirectory(root)` | Read a `teams//mailboxes//` tree into one `MailboxManifest` per mailbox. Ships from the `./loader` subpath (Node only). | | `MailboxManifest` | One mailbox record: `{ id, declared, body }`. | diff --git a/packages/workforce/package.json b/packages/workforce/package.json index 0cabab521e..3c19408a34 100644 --- a/packages/workforce/package.json +++ b/packages/workforce/package.json @@ -78,6 +78,7 @@ "dependencies": { "@flow-state-dev/core": "workspace:*", "@flow-state-dev/orchestration": "workspace:*", + "@flow-state-dev/workspace": "workspace:*", "zod": "^3.24.1" }, "devDependencies": { diff --git a/packages/workforce/src/projects/index.ts b/packages/workforce/src/projects/index.ts index 1cb6fa9412..ff08c3aec5 100644 --- a/packages/workforce/src/projects/index.ts +++ b/packages/workforce/src/projects/index.ts @@ -3,7 +3,8 @@ * and each project's room, reached through a member's own talk session. * * `collections.ts` is canonical for the keys and row shapes; `project-files.ts` - * for a member's read of a project's files; `talk.ts` for how + * for a member's read of a project's files; `project-workspace.ts` for the run + * source a coding run on a project's board gets its files from; `talk.ts` for how * a session reaches a room; `room-store.ts` for how a room is written and read; * `talk-template.ts` for a room's seats and charter, and the mint on create. * The talk entries are built into every mailbox kind by `defineMailboxFlow`. @@ -63,6 +64,13 @@ export { export { ProjectRefusedError, type ProjectRefusalReason } from "./project-refusal"; +export { + projectWorkspace, + projectWorkspaceCapability, + type ProjectWorkspaceOptions, + type ProjectWorkspaceRefusalReason +} from "./project-workspace"; + export { ROOM_LINE_GRACE_MS, ROOM_PAGE_SIZE } from "./room-store"; export { diff --git a/packages/workforce/src/projects/project-workspace.ts b/packages/workforce/src/projects/project-workspace.ts new file mode 100644 index 0000000000..48a8198d53 --- /dev/null +++ b/packages/workforce/src/projects/project-workspace.ts @@ -0,0 +1,185 @@ +/** + * `projectWorkspace({ board })`: where a coding run on a project's board gets + * its files. + * + * A run source (`@flow-state-dev/workspace`) answers one question for a + * workspace host: does this run cut a branch of a repository, or work on a set + * of kept files? For a run on a mailbox's board, Workforce knows the answer, + * and this is where it gives it: + * + * board → its mailbox → the workstream's claim → the project row + * → the project's repository, with its files beside the checkout + * → or, with no repository, the project's files alone + * + * Every step reads stored, server-written data (BP-031): the mailbox id is + * derived from the board's minted id (`.`), never passed + * beside it, so the two cannot disagree; the claim and the row are read from + * the organization's collections; and the run's owner is the request's + * resolved user, the same identity harness-manager records as the run's owner. + * Nothing on the row being worked (its input, its metadata, anything a model + * wrote) is read. + * + * Three answers are refusals, each naming what it refused on, before any file + * or clone exists: + * + * - `no-project`: no project holds the board's workstream, so there is nowhere + * to keep the run's files. + * - `no-such-project`: the workstream's claim names a project with no row. + * - `not-a-member`: the run's owner is not one of the project's members. + * + * The kept files are the project's slice of `project-files/**`: the answer + * names the project's id as the key prefix, so a host hydrates and saves + * `project-files//…` and nothing else. + * + * The collections are reached through {@link projectWorkspaceCapability}, + * which the block that asks the source must hold: pass it on the manager's + * `uses`. + */ + +import { defineCapability } from "@flow-state-dev/core"; +import type { BlockContext, ResourceCollectionRef } from "@flow-state-dev/core/types"; +import { + collectionIdFor, + principalFromContext, + type ProjectedEntryState, + type RunSource, + type RunSourceAnswer, + type RunSourceRefusal +} from "@flow-state-dev/workspace"; +import { + defineProjectFilesCollection, + defineProjectsCollection, + defineWorkstreamClaimsCollection, + PROJECT_FILES_RESOURCE, + PROJECTS_RESOURCE, + projectRowSchema, + WORKSTREAM_CLAIMS_RESOURCE, + workstreamClaimSchema +} from "./collections"; +import { isMember } from "./membership-gate"; + +/** + * Why {@link projectWorkspace} refused a run. The answer's `message` names the + * workstream or the project. + */ +export type ProjectWorkspaceRefusalReason = "no-project" | "no-such-project" | "not-a-member"; + +/** + * The collections {@link projectWorkspace} reads: the workstream claims and + * the projects, and the project files it hands the host. Pass it on the + * `uses` of the block that asks the source (for harness-manager, + * `harnessManager({ uses: [projectWorkspaceCapability] })`). + * + * The same declarations the project writes install, so it meets them in one + * flow without a conflict. + */ +export const projectWorkspaceCapability = defineCapability({ + name: "project-workspace", + resources: { + [WORKSTREAM_CLAIMS_RESOURCE]: defineWorkstreamClaimsCollection(), + [PROJECTS_RESOURCE]: defineProjectsCollection(), + [PROJECT_FILES_RESOURCE]: defineProjectFilesCollection() + } +}); + +/** What {@link projectWorkspace} takes. */ +export interface ProjectWorkspaceOptions { + /** + * The mailbox board the runs are on: the same declaration the manager drains + * (`mailboxBoard(mailboxId, name)`). Only its minted id is read, and the + * mailbox is derived from it. + */ + board: { readonly id: string }; +} + +/** + * The run source for coding runs on a board a project holds. + * + * Answers `{ kind: "repo", repo, projectId, files }` for a project with a + * repository, `{ kind: "files", projectId, files }` for one with none, or a + * refusal ({@link ProjectWorkspaceRefusalReason}). + * + * @param options `board`: the mailbox board whose rows the runs work. + * @returns A `RunSource` to hand `localWorkspaceHost({ source })`. + * @throws When built, if the board's id is not a mailbox board's + * (`.`). When asked, if the block asking does not hold + * {@link projectWorkspaceCapability}. + * @example + * const work = mailboxBoard("eng.feature", "work"); + * harnessManager({ + * boardCollectionId: work.id, + * boardCollection: work, + * workspace: localWorkspaceHost({ root, remotes: { allow: ["github.com"] }, source: projectWorkspace({ board: work }) }), + * uses: [projectWorkspaceCapability], + * // ... + * }); + */ +export function projectWorkspace(options: ProjectWorkspaceOptions): RunSource { + const boardId = options.board.id; + const dot = boardId.lastIndexOf("."); + if (dot <= 0 || dot === boardId.length - 1) { + throw new Error( + `projectWorkspace: "${boardId}" is not a mailbox board's id (\`.\`), so it ` + + `names no workstream to find a project by. Pass the board \`mailboxBoard\` returns.` + ); + } + const workstream = boardId.slice(0, dot); + + const source: RunSource = async (looseCtx): Promise => { + const ctx = looseCtx as unknown as BlockContext; + const claims = collectionOn(ctx, WORKSTREAM_CLAIMS_RESOURCE); + const projects = collectionOn(ctx, PROJECTS_RESOURCE); + const files = collectionOn(ctx, PROJECT_FILES_RESOURCE) as ResourceCollectionRef; + + const claim = workstreamClaimSchema.safeParse((await claims.getOptional(workstream))?.state); + if (!claim.success) { + return refused( + "no-project", + `the workstream "${workstream}" belongs to no project, so its coding runs have nowhere to keep their files.` + ); + } + const projectId = claim.data.projectId; + const stored = await projects.getOptional(projectId); + if (stored === undefined) { + return refused( + "no-such-project", + `the workstream "${workstream}" is claimed by project "${projectId}", which this organization does not have.` + ); + } + // Through the schema, so a row written before `repository` existed reads as none (BP-030). + const project = projectRowSchema.parse(stored.state); + const owner = ctx.user?.identity?.id; + if (!isMember(project, owner)) { + return refused( + "not-a-member", + `the run's owner${owner ? ` "${owner}"` : ""} is not a member of project "${projectId}", so it may not work on its files.` + ); + } + + const kept = { + collection: files, + collectionId: collectionIdFor(defineProjectFilesCollection(), principalFromContext(ctx)) + }; + return project.repository == null + ? { kind: "files", projectId, files: kept } + : { kind: "repo", repo: project.repository, projectId, files: kept }; + }; + return source; +} + +/** A refusal answer. */ +function refused(reason: ProjectWorkspaceRefusalReason, message: string): RunSourceRefusal { + return { kind: "refused", reason, message }; +} + +/** The collection at `accessor`, or a loud error naming the capability that installs it. */ +function collectionOn(ctx: BlockContext, accessor: string): ResourceCollectionRef { + const ref = (ctx.resources as Record | undefined)?.[accessor]; + if (ref === undefined) { + throw new Error( + `projectWorkspace: the block asking for a run's source does not hold "${accessor}". ` + + `Pass projectWorkspaceCapability on its \`uses\` (for harness-manager, \`harnessManager({ uses })\`).` + ); + } + return ref as ResourceCollectionRef; +} diff --git a/packages/workforce/test/project-workspace.test.ts b/packages/workforce/test/project-workspace.test.ts new file mode 100644 index 0000000000..79fe615497 --- /dev/null +++ b/packages/workforce/test/project-workspace.test.ts @@ -0,0 +1,255 @@ +/** + * `projectWorkspace({ board })`, the run source for a coding run on a project's + * board, over the real HTTP router as three verified users in one organization: + * `alice` and `bob` (members) and `mallory` (in the org, on no project). + * + * What is pinned: the source answers from the workstream's claim and the + * project row and from nothing else; it hands a host the project's own files + * and no other project's; and it refuses a run whose owner is not a member, or + * whose workstream no project holds, before a single file is read. + */ +import { afterAll, describe, expect, it } from "vitest"; +import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { defineFlow, handler } from "@flow-state-dev/core"; +import type { ResourceCollectionRef } from "@flow-state-dev/core/types"; +import { createFlowState, inMemoryStores } from "@flow-state-dev/engine"; +import { createMockModelResolver } from "@flow-state-dev/testing"; +import { localWorkspaceHost, WorkspaceRefusedError, type RunSourceAnswer } from "@flow-state-dev/workspace"; +import { z } from "zod"; +import { + MAILBOX_KIND, + defineMailboxInventoryCollection, + defineProjectBlocks, + defineProjectFilesCollection, + mailboxBoard, + projectWorkspace, + projectWorkspaceCapability +} from "../src/index"; + +const ORG = "lab"; +const MAILBOXES = ["eng.feature", "eng.triage", "ops.release"]; +const board = mailboxBoard("eng.feature", "work"); + +const root = mkdtempSync(join(tmpdir(), "project-workspace-")); +afterAll(() => rmSync(root, { recursive: true, force: true })); +const host = localWorkspaceHost({ root, remotes: { allow: ["file"] }, source: projectWorkspace({ board }) }); + +/** Every read the source made through `ctx.resources`, as `.()`. */ +function recording(ctx: object, log: string[]): object { + const resources = (ctx as { resources: Record }).resources; + const watched = new Proxy(resources, { + get(target, accessor, receiver) { + const ref = Reflect.get(target, accessor, receiver); + if (typeof accessor !== "string" || ref === null || typeof ref !== "object") return ref; + return new Proxy(ref as object, { + get(inner, method, innerReceiver) { + const value = Reflect.get(inner, method, innerReceiver); + if (typeof value !== "function") return value; + return (...args: unknown[]) => { + log.push(`${accessor}.${String(method)}(${args.filter((a) => typeof a === "string").join(",")})`); + return (value as (...a: unknown[]) => unknown).apply(inner, args); + }; + } + }); + } + }); + return new Proxy(ctx, { get: (target, prop, receiver) => (prop === "resources" ? watched : Reflect.get(target, prop, receiver)) }); +} + +/** A plain view of an answer: the collection ref does not cross the action boundary. */ +function view(answer: RunSourceAnswer) { + if (answer.kind === "refused") return answer; + if (answer.kind === "files") return { kind: answer.kind, projectId: answer.projectId }; + return { kind: answer.kind, repo: answer.repo, projectId: answer.projectId }; +} + +/** Ask the source as the calling user; with `provision`, also hand its answer to the host and list what it laid down. */ +const askSource = handler({ + name: "ask-source", + inputSchema: z.object({ provision: z.string().optional() }), + outputSchema: z.unknown(), + uses: [projectWorkspaceCapability], + execute: async (input, ctx) => { + const reads: string[] = []; + const answer = await projectWorkspace({ board })(recording(ctx, reads) as never); + if (input.provision === undefined) return { answer: view(answer), reads }; + const place = [input.provision]; + try { + const made = await host.provision(answer, { place }); + return { answer: view(answer), reads, files: readdirSync(made.cwd).sort() }; + } catch (error) { + return { + answer: view(answer), + reads, + refusedBy: error instanceof WorkspaceRefusedError ? error.reason : String(error), + placeExists: existsSync(join(root, ...place)) + }; + } + } +}); + +/** Writes one project file, as a run's save does. */ +const seedProjectFile = handler({ + name: "seed-project-file", + inputSchema: z.object({ key: z.string(), content: z.string() }), + outputSchema: z.object({}), + resources: { "project-files": defineProjectFilesCollection() }, + execute: async (input, ctx) => { + const files = ctx.resources["project-files"] as unknown as ResourceCollectionRef; + const ref = await files.create(input.key, { path: input.key, hash: null, updatedAt: null }); + await ref.writeContent(input.content); + return {}; + } +}); + +/** The same source, on a block that does not hold its collections. */ +const askWithout = handler({ + name: "ask-without", + inputSchema: z.object({}), + outputSchema: z.unknown(), + execute: async (_input, ctx) => projectWorkspace({ board })(ctx as never) +}); + +const seedMailboxes = handler({ + name: "seed-mailboxes", + inputSchema: z.object({}), + outputSchema: z.object({}), + resources: { "mailbox-inventory": defineMailboxInventoryCollection() }, + execute: async (_input, ctx) => { + const rows = ctx.resources["mailbox-inventory"] as unknown as ResourceCollectionRef; + for (const id of MAILBOXES) await rows.upsert(id, { id, kind: MAILBOX_KIND, members: [], openedAt: null }); + return {}; + } +}); + +const labFlow = defineFlow({ + kind: "lab", + actions: { + ...defineProjectBlocks().actions, + askSource: { block: askSource }, + seedProjectFile: { block: seedProjectFile } + } +}); +const seederFlow = defineFlow({ kind: "seeder", actions: { seedMailboxes: { block: seedMailboxes } } }); +/** A flow of its own: a capability's collections are installed flow-wide, so beside `askSource` they would be there. */ +const bareFlow = defineFlow({ kind: "bare", actions: { askWithout: { block: askWithout } } }); + +async function boot() { + const state = createFlowState({ + flows: { lab: labFlow, seeder: seederFlow, bare: bareFlow }, + stores: { default: { primary: inMemoryStores() } }, + modelResolver: createMockModelResolver({}), + resolvePrincipal: (context: any) => { + const user = context.request?.headers.get("x-verified-user"); + return user == null ? null : { userId: user, orgId: ORG }; + } + } as never); + const router = (await state.getRouter()) as any; + + const call = async (method: "GET" | "POST", user: string, path: string[], body?: unknown, query = "") => { + const response = await router[method]( + new Request(`http://test/api/flows/${path.join("/")}${query}`, { + method, + headers: { "content-type": "application/json", "x-verified-user": user }, + ...(body === undefined ? {} : { body: JSON.stringify(body) }) + }), + { params: { path } } + ); + const text = await response.text(); + return { status: response.status as number, json: text.length > 0 ? JSON.parse(text) : undefined }; + }; + const session = async (user: string, flow: string): Promise => { + const { status, json } = await call("POST", user, [flow, "sessions"], { userId: user }); + if (status >= 400) throw new Error(`createSession ${status}: ${JSON.stringify(json)}`); + return json.session.id; + }; + /** Run an action to completion and return its output, or throw naming how it settled. */ + const run = async (user: string, flow: string, action: string, input: unknown): Promise => { + const sessionId = await session(user, flow); + const answer = await call("POST", user, [flow, sessionId, "actions", action], { userId: user, input }); + const requestId = answer.json?.request?.id; + if (requestId === undefined) throw new Error(`${action}: ${JSON.stringify(answer.json)}`); + for (let i = 0; i < 1000; i += 1) { + const polled = await call("GET", user, [flow, "requests", requestId, "status"]); + if (["completed", "errored", "failed", "cancelled"].includes(polled.json?.status)) break; + await new Promise((r) => setTimeout(r, 5)); + } + const { json } = await call("GET", user, ["sessions", sessionId, "requests"], undefined, "?include_result_output=true"); + const found = ((json?.requests ?? []) as Array>).find((r) => r.id === requestId) ?? {}; + if (found.status !== "completed") throw new Error(`${action} as ${user}: ${found.status} ${JSON.stringify(found.result?.error)}`); + return found.result?.output; + }; + + await run("alice", "seeder", "seedMailboxes", {}); + return { run }; +} + +describe("projectWorkspace", () => { + it("answers a project with no repository with its files, reading only the workstream's claim and the project's row", async () => { + const h = await boot(); + await h.run("alice", "lab", "createProject", { id: "sandbox", title: "Sandbox", members: ["bob"], workstreams: ["eng.feature"] }); + // A project whose id starts with the other's: a bare prefix match would hand its files over. + await h.run("alice", "lab", "createProject", { id: "sandbox2", title: "Sandbox 2" }); + await h.run("alice", "lab", "seedProjectFile", { key: "sandbox/notes/plan.md", content: "the sandbox's plan" }); + await h.run("alice", "lab", "seedProjectFile", { key: "sandbox2/secret.md", content: "not the sandbox's" }); + + const asked = await h.run("bob", "lab", "askSource", {}); + expect(asked.answer).toEqual({ kind: "files", projectId: "sandbox" }); + // Where the source comes from is stored, server-written data: the claim, then the row. Nothing else. + expect(asked.reads).toEqual(["workstream-claims.getOptional(eng.feature)", "projects.getOptional(sandbox)"]); + + const provisioned = await h.run("bob", "lab", "askSource", { provision: "bob-run" }); + expect(provisioned.files).toEqual(["notes"]); + expect(readdirSync(join(root, "bob-run", "workspace", "notes"))).toEqual(["plan.md"]); + }); + + it("answers a project with a repository with that remote and the project's files beside it, and follows a change to it", async () => { + const h = await boot(); + await h.run("alice", "lab", "createProject", { + id: "storefront", + title: "Storefront", + workstreams: ["eng.feature"], + repository: "https://github.com/acme/storefront.git" + }); + expect((await h.run("alice", "lab", "askSource", {})).answer).toEqual({ + kind: "repo", + repo: "https://github.com/acme/storefront.git", + projectId: "storefront" + }); + + await h.run("alice", "lab", "setRepository", { projectId: "storefront", repository: "git@github.com:acme/shop.git" }); + expect((await h.run("alice", "lab", "askSource", {})).answer).toMatchObject({ kind: "repo", repo: "git@github.com:acme/shop.git" }); + await h.run("alice", "lab", "setRepository", { projectId: "storefront", repository: null }); + expect((await h.run("alice", "lab", "askSource", {})).answer).toEqual({ kind: "files", projectId: "storefront" }); + }); + + it("refuses a run whose owner is not a member, naming the project, before any file is read or any place made", async () => { + const h = await boot(); + await h.run("alice", "lab", "createProject", { id: "sandbox", title: "Sandbox", workstreams: ["eng.feature"] }); + await h.run("alice", "lab", "seedProjectFile", { key: "sandbox/notes.md", content: "members only" }); + + const asked = await h.run("mallory", "lab", "askSource", { provision: "mallory-run" }); + expect(asked.answer).toMatchObject({ kind: "refused", reason: "not-a-member" }); + expect(asked.answer.message).toContain('"sandbox"'); + expect(asked.reads.some((read: string) => read.startsWith("project-files"))).toBe(false); + expect(asked.refusedBy).toBe("not-a-member"); + expect(asked.placeExists).toBe(false); + }); + + it("refuses a workstream no project holds, naming the workstream", async () => { + const h = await boot(); + await h.run("alice", "lab", "createProject", { id: "elsewhere", title: "Elsewhere", workstreams: ["eng.triage"] }); + const asked = await h.run("alice", "lab", "askSource", { provision: "nowhere-run" }); + expect(asked.answer).toMatchObject({ kind: "refused", reason: "no-project" }); + expect(asked.answer.message).toContain('"eng.feature"'); + expect(asked.placeExists).toBe(false); + }); + + it("is refused at build for a board id that names no mailbox, and when asked on a block that does not hold its collections", async () => { + expect(() => projectWorkspace({ board: { id: "work" } })).toThrow(/not a mailbox board's id/); + const h = await boot(); + await expect(h.run("alice", "bare", "askWithout", {})).rejects.toThrow(/projectWorkspaceCapability/); + }); +}); diff --git a/packages/workforce/tsconfig.json b/packages/workforce/tsconfig.json index 261dbce7b9..ab479e620f 100644 --- a/packages/workforce/tsconfig.json +++ b/packages/workforce/tsconfig.json @@ -6,5 +6,5 @@ "outDir": "dist" }, "include": ["src/**/*"], - "references": [{ "path": "../core" }, { "path": "../orchestration" }] + "references": [{ "path": "../core" }, { "path": "../orchestration" }, { "path": "../workspace" }] } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6847c0080b..344dd7a41f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1857,6 +1857,9 @@ importers: '@flow-state-dev/orchestration': specifier: workspace:* version: link:../orchestration + '@flow-state-dev/workspace': + specifier: workspace:* + version: link:../workspace zod: specifier: ^3.24.1 version: 3.25.76 From 17a5bb16ac9e9a5b5736a4f5d6b30f7924197c1b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 22:53:43 +0000 Subject: [PATCH 24/28] feat(devforce-lab): DevTeam codes in each project's repository or on its files (FIX-1762) The lab's coder runs on a workspace host whose source is projectWorkspace on the board. Storefront names a bare repository beside the store; a new Sandbox project names none. The chief of staff gains setRepository, and every repository write (setRepository, or createProject with one) waits on a human_approval in Inbox first. phase.mts validate now receives the host. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5 --- goals/devforce-lab/lab/harness.mts | 10 +- goals/devforce-lab/lab/host.mts | 167 ++++++++++++++++-- goals/devforce-lab/lab/phase.mts | 69 ++++++-- goals/devforce-lab/lab/scratch-repo.mts | 49 ++++- .../lab/workforce/flows/workers/coder.mts | 13 +- .../org/workers/chief-of-staff/WORKER.md | 8 +- goals/package.json | 1 + .../teams/devteam/fsdev.config.mts | 48 +++-- .../test/devteam-repository-ask.test.ts | 162 +++++++++++++++++ pnpm-lock.yaml | 3 + 10 files changed, 485 insertions(+), 45 deletions(-) create mode 100644 labs/shift-manager/test/devteam-repository-ask.test.ts diff --git a/goals/devforce-lab/lab/harness.mts b/goals/devforce-lab/lab/harness.mts index 7e155650ef..38e7ab7c3a 100644 --- a/goals/devforce-lab/lab/harness.mts +++ b/goals/devforce-lab/lab/harness.mts @@ -22,7 +22,7 @@ * An unknown value is refused at startup rather than read as the default. */ -import { writeFileSync } from "node:fs"; +import { existsSync, writeFileSync } from "node:fs"; import { join } from "node:path"; import { claudeCodeAgent } from "@flow-state-dev/claude-code/sdk"; import type { HarnessBlock, HarnessCallbackContext } from "@flow-state-dev/core/types"; @@ -78,10 +78,14 @@ function rowLine(prompt: string): string { return prompt.split("\n").find((line) => line.startsWith("Row ")) ?? "a row"; } -/** What the scripted run does in its checkout: one file, committed. */ +/** + * What the scripted run does where it works: one file, committed when that is + * a checkout. A project with no repository runs in its files (`workspace/`, + * no git), where the file itself is the work and the manager saves it back. + */ function commitScriptedWork(run: StubRun): void { writeFileSync(join(run.cwd, "SCRIPTED-RUN.md"), `A scripted run, no model.\n\n${rowLine(run.prompt)}\n`); - commitAll(run.cwd, "scripted run: note the row"); + if (existsSync(join(run.cwd, ".git"))) commitAll(run.cwd, "scripted run: note the row"); } /** diff --git a/goals/devforce-lab/lab/host.mts b/goals/devforce-lab/lab/host.mts index cda0206fc0..0a4deda813 100644 --- a/goals/devforce-lab/lab/host.mts +++ b/goals/devforce-lab/lab/host.mts @@ -55,8 +55,11 @@ import { type FlowState, type PrincipalResolver, } from "@flow-state-dev/engine"; -import { defineCapability, sequencer } from "@flow-state-dev/core"; -import type { FlowInstance } from "@flow-state-dev/core/types"; +import { defineCapability, handler, sequencer } from "@flow-state-dev/core"; +import type { BlockContext, FlowInstance } from "@flow-state-dev/core/types"; +import type { WorkspaceConfig } from "@flow-state-dev/harness-manager"; +import { localWorkspaceHost, type WorkspaceHost } from "@flow-state-dev/workspace"; +import { z } from "zod"; import { AGENT_KIND, MAILBOX_KIND, @@ -73,6 +76,7 @@ import { createProjectInputSchema, createProjectOutputSchema, defineProjectBlocks, + projectWorkspace, projectWritesMailboxInventory, mergeSeatFlows, openMailboxes, @@ -85,6 +89,8 @@ import { type CreateProjectInput, type CreateProjectOutput, type HireOptions, + setRepositoryInputSchema, + setRepositoryOutputSchema, setWorkstreamsInputSchema, setWorkstreamsOutputSchema, type InventoryActionRequest, @@ -257,27 +263,37 @@ export function boardMailboxOf(roster: Pick): Decla } /** - * The project writes as the chief of staff's tools, `createProject` and - * `setWorkstreams`: the same blocks the Lab's own open creates projects - * through, under the names its `tools:` line spells. A catalog key must be the - * tool's own name, so each is a one-step sequencer carrying the name and what - * the model reads about it. + * The project writes as the chief of staff's tools, `createProject`, + * `setWorkstreams` and `setRepository`: the same blocks the Lab's own open + * creates projects through, under the names its `tools:` line spells. A + * catalog key must be the tool's own name, so each is a sequencer carrying the + * name and what the model reads about it. * * The owner is the session's user, so a project the chief of staff creates * belongs to the person talking to it, who is always a member; `members` adds * whoever they name. + * + * **A repository waits for the person.** Which remote a project's code is + * cloned from is the person's to say, so `setRepository`, and `createProject` + * with a `repository`, pause on a stock `human_approval` before the write. + * Approve writes it; Deny throws out of the tool before the write runs, and + * nothing changes. Without durable execution the tool refuses rather than + * writing unasked. */ -function chiefOfStaffProjectTools(blocks: ProjectBlocks) { +export function chiefOfStaffProjectTools(blocks: ProjectBlocks) { return { createProject: sequencer({ name: "createProject", description: "Create a project for the person you are talking to. They own it and are always a member. " + "`id` is a short lowercase slug; `members` adds the user ids they name; `workstreams` takes " + - "full mailbox ids (`team.mailbox`), each in at most one project.", + "full mailbox ids (`team.mailbox`), each in at most one project; `repository` is the git " + + "remote its code lives in, if they named one. With a repository, the person approves it first.", inputSchema: createProjectInputSchema, outputSchema: createProjectOutputSchema, - }).step(blocks.createProject), + }) + .tapIf((input) => input.repository != null, askRepository((input) => input.id)) + .step(blocks.createProject), setWorkstreams: sequencer({ name: "setWorkstreams", description: @@ -286,9 +302,69 @@ function chiefOfStaffProjectTools(blocks: ProjectBlocks) { inputSchema: setWorkstreamsInputSchema, outputSchema: setWorkstreamsOutputSchema, }).step(blocks.setWorkstreams), + setRepository: sequencer({ + name: "setRepository", + description: + "Set, change or clear (null) the git remote a project's code lives in. Only the project's " + + "members may, and the person approves it first.", + inputSchema: setRepositoryInputSchema, + outputSchema: setRepositoryOutputSchema, + }) + .tap(askRepository((input) => input.projectId)) + .step(blocks.setRepository), }; } +/** What a repository ask reads off a write's input. */ +const repositoryAskInputSchema = z + .object({ id: z.string().optional(), projectId: z.string().optional(), repository: z.string().nullable().optional() }) + .passthrough(); + +/** + * The approval a repository write waits on: a stock `human_approval` naming + * the project and the remote, with any user or password left out of what + * Inbox shows. Returns on Approve; on Deny the runtime throws out of it. + */ +function askRepository(projectOf: (input: z.infer) => string | undefined) { + return handler({ + name: "devforce-cos-ask-repository", + inputSchema: repositoryAskInputSchema, + outputSchema: z.void(), + execute: async (input: z.infer, ctx: BlockContext) => { + const project = projectOf(input) ?? ""; + if (ctx.suspend === undefined) { + throw new Error( + `the repository of project "${project}" waits for a person's approval here, and this app ` + + `can't ask for one: it runs without durable execution. Nothing was changed.`, + ); + } + const repository = input.repository == null ? null : withoutCredentials(input.repository); + await ctx.suspend({ + reason: "human_approval", + message: + repository === null + ? `Clear the repository of project "${project}"? Its coding work will run on its files.` + : `Set the repository of project "${project}" to ${repository}?`, + data: { project, repository }, + allow: ["approve", "reject"], + }); + }, + }); +} + +/** A remote as a person may be shown it: a URL with no user or password in it. */ +function withoutCredentials(remote: string): string { + try { + const url = new URL(remote); + if (url.username === "" && url.password === "") return remote; + url.username = ""; + url.password = ""; + return url.href; + } catch { + return remote; + } +} + /** * The organization's TypeScript resource modules (`org/resources/*.ts`), found * by walking the tree and imported, as the resource map `fsdev gen` would @@ -312,8 +388,17 @@ export interface OpenLabOptions { stores: unknown; /** The harness the `coder` kind runs. The one thing the two checks differ by. */ harness: HarnessStub["slot"]; - /** Where checkouts are cut, from what repository, off which ref. */ - workspace: { root: string; sourceRepo: string; baseRef: string }; + /** + * Where each coding run works. + * + * `{ root, sourceRepo, baseRef }`: every run is a new branch of one fixed + * repository, as the older checks run. `{ root, remotes }`: a workspace host + * whose source is `projectWorkspace` on the board the coder kind drains, so + * a run works in a branch of its project's repository (reached only if + * `remotes.allow` lists it), or on its project's files when the project has + * none. + */ + workspace: WorkspaceConfig | LabWorkspaceHost; /** * The seat instance id the board's `coder` assignee is addressed to. * @@ -401,6 +486,13 @@ export interface OpenLabOptions { */ fileBeforeAsking?: boolean; + /** + * The workspace host saves nothing back: a run's project files are laid + * down before it and dropped after. Only with a `{ root, remotes }` + * workspace. The red state of "a run's files are kept by the project". + */ + saveNothing?: boolean; + /** * Repoint a seat at a different file-declared document, by seat id. * @@ -441,6 +533,14 @@ export interface OpenLabOptions { withoutProjectTools?: boolean; } +/** A workspace host for the lab to build: where its places live, and which remotes it may reach. */ +export interface LabWorkspaceHost { + /** The host directory every clone and place lives under. */ + root: string; + /** The remotes the host may reach; list `"file"` to allow `file://` remotes. */ + remotes: { allow: readonly string[] }; +} + /** One skill on a worker record, as the loader shapes it. */ export interface SeatSkill { name: string; @@ -548,6 +648,17 @@ export interface Lab { * this open wrote it. Absent when `projects` was not asked for. */ projects?: CreateProjectOutput[]; + /** + * Run one of the project writes (`createProject`, `setWorkstreams`, + * `setRepository`) as the lab's owner, in the session the open created + * projects in. Absent when `projects` was not asked for. + */ + projectAct?(actionName: string, input: unknown): Promise<{ output?: unknown; error?: string }>; + /** + * The workspace host the coder kind runs on, when the lab built one + * (`workspace: { root, remotes }`). + */ + workspaceHost?: WorkspaceHost; /** * The flow state the seats are registered in: what a host hands `raiseAsk` * when it calls the step itself. @@ -599,6 +710,15 @@ export async function openLab(options: OpenLabOptions): Promise { const board = mailboxBoard(mailbox.id, boardName); const ledger: FeatureLedger = options.ledger ?? { id: board.id, collection: board }; + // A host's source is the project that holds the board the coder kind drains. + const workspaceHost: WorkspaceHost | undefined = + "sourceRepo" in options.workspace + ? undefined + : labWorkspaceHost(options.workspace, ledger.id, options.saveNothing === true); + if (options.saveNothing === true && workspaceHost === undefined) { + throw new Error("openLab: `saveNothing` needs a `{ root, remotes }` workspace; a fixed repository keeps no files"); + } + // The documents, as the L1 resource map a flow installs. Org-scoped, which is // what makes the seats' document reads — and BR-17 — matter. const resources = resourcesFromDocs(roster.documents); @@ -644,7 +764,7 @@ export async function openLab(options: OpenLabOptions): Promise { ledger, ...(emRecords[0] === undefined ? {} : { coordinatorSeatId: emRecords[0].id }), harness: options.harness, - workspace: options.workspace, + workspace: workspaceHost ?? (options.workspace as WorkspaceConfig), // The mailbox's charter and members, resolved once here so the prompt // builder stays a function of the run and these options. Not the whole // manifest: the charter is the only mailbox content a run is handed. @@ -1247,7 +1367,10 @@ export async function openLab(options: OpenLabOptions): Promise { }, ...(ask === undefined ? {} : { ask }), - ...(projects === undefined ? {} : { projects }), + ...(projects === undefined + ? {} + : { projects, projectAct: (actionName: string, input: unknown) => actOn(projectsFlow, PROJECTS_SESSION, actionName, input) }), + ...(workspaceHost === undefined ? {} : { workspaceHost }), state, ledger, door, @@ -1256,6 +1379,22 @@ export async function openLab(options: OpenLabOptions): Promise { }; } +/** + * The lab's workspace host: `localWorkspaceHost` over `root`, reaching only + * the remotes listed, with `projectWorkspace` on the drained board as its + * source. `saveNothing` is the `no-sync-back` control's seam: the host is the + * same, and its `save` reports nothing saved. + */ +function labWorkspaceHost(options: LabWorkspaceHost, boardId: string, saveNothing: boolean): WorkspaceHost { + const host = localWorkspaceHost({ + root: options.root, + remotes: { allow: [...options.remotes.allow] }, + source: projectWorkspace({ board: { id: boardId } }), + }); + if (!saveNothing) return host; + return { ...host, save: async () => ({ outcomes: [], conflicts: [], contested: [] }) }; +} + /** One wording for whatever a refusal turns out to be. */ function messageOf(error: unknown): string { if (error instanceof Error) return error.message; diff --git a/goals/devforce-lab/lab/phase.mts b/goals/devforce-lab/lab/phase.mts index 2575af46c9..cf1983b73e 100644 --- a/goals/devforce-lab/lab/phase.mts +++ b/goals/devforce-lab/lab/phase.mts @@ -16,14 +16,19 @@ * a commit the base ref does not have**, read out of the run's * own checkout with git. Not a pull request: conductor already proves the `gh` * probe, and re-proving it would make this check expensive to re-run a year - * from now, which is the one thing a goal is for. + * from now, which is the one thing a goal is for. On a workspace host the + * base is the remote the checkout was cut from, and a run in a project with + * no repository has no git at all: it is done when it left files in its + * `workspace/`, which the manager saves back to the project. * * The done-condition is the authority on completion, and the run record never * is. A harness that reports a clean finish and leaves no commit does not settle * its row (BR-14); one that reports a clean finish and commits does (BR-13). */ -import { assertBaseRefExists } from "@flow-state-dev/harness-manager"; +import { readdirSync } from "node:fs"; +import { basename } from "node:path"; +import { ASK_MARKER_DIR, assertBaseRefExists } from "@flow-state-dev/harness-manager"; import type { CompletionRunContext, PhaseSpec, @@ -31,16 +36,19 @@ import type { WorkspaceConfig, } from "@flow-state-dev/harness-manager"; import { GIT_TIMEOUT_MS, run } from "@flow-state-dev/harness-manager/checkout"; +import type { WorkspaceHost } from "@flow-state-dev/workspace"; import { runAcceptance } from "./acceptance.mts"; import type { SeatConfig } from "./seat-config.mts"; /** The phase segment of every run record's topic, and of every row filed here. */ export const PHASE = "implement"; -/** What {@link implementPhase}'s `validate` learned, handed back to `isDone`. */ -interface ValidatedWorkspace { - baseRef: string; -} +/** + * What {@link implementPhase}'s `validate` learned, handed back to `isDone`: + * the base ref of a fixed repository, or that runs come from a workspace host, + * where each run's base is the remote it was cut from. + */ +type ValidatedWorkspace = { baseRef: string } | { host: true }; /** * Compose the prompt: the task first, then the seat that was woken. @@ -171,6 +179,34 @@ function taskSection(task: PromptRunContext["task"]): string[] { ]; } +/** + * Is there a commit on a host-provisioned checkout's branch that its remote + * does not have? + * + * The host cuts the branch from a remote-tracking ref of its clone, so a + * commit reachable from HEAD and from no remote-tracking ref is one the run + * made. Read in the run's own checkout, like {@link hasNewCommit}. + */ +async function hasUnpushedCommit(workspacePath: string): Promise { + const { stdout } = await run("git", ["rev-list", "--count", "HEAD", "--not", "--remotes"], { + cwd: workspacePath, + timeoutMs: GIT_TIMEOUT_MS, + }); + return Number.parseInt(stdout.trim(), 10) > 0; +} + +/** + * Does a run with no repository leave any of the project's files behind? + * + * Its working directory is the project's files (`workspace/`), saved back to + * the project after the run, and there is no git to read a commit from. The + * manager's own question directory is not the run's work. + */ +function leftFiles(workspacePath: string): boolean { + const askRoot = ASK_MARKER_DIR.split(/[\\/]/)[0]; + return readdirSync(workspacePath).some((entry) => entry !== askRoot); +} + /** * Is there a commit on this run's branch that the base ref does not have? * @@ -190,8 +226,10 @@ async function hasNewCommit(workspacePath: string, baseRef: string): Promise { + validate: (workspace: WorkspaceConfig | WorkspaceHost): ValidatedWorkspace => { + // A workspace host has no one repository to check: each run's source + // names its own, and the host refuses one it cannot reach before the + // harness runs. + if ("provision" in workspace) return { host: true }; // Refused here, before any row is claimed: a base ref the repository does // not have fails the done-condition on EVERY attempt, each time after the // run has already been paid for. This is the exact shape `validate` exists diff --git a/goals/devforce-lab/lab/scratch-repo.mts b/goals/devforce-lab/lab/scratch-repo.mts index ef85113494..097803c6ac 100644 --- a/goals/devforce-lab/lab/scratch-repo.mts +++ b/goals/devforce-lab/lab/scratch-repo.mts @@ -42,10 +42,10 @@ */ import { execFileSync } from "node:child_process"; -import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; +import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { tmpdir } from "node:os"; -import { fileURLToPath } from "node:url"; +import { fileURLToPath, pathToFileURL } from "node:url"; import { ASK_MARKER_IGNORE_RULE } from "@flow-state-dev/harness-manager"; import { GIT_TIMEOUT_MS } from "@flow-state-dev/harness-manager/checkout"; @@ -163,6 +163,51 @@ export function createScratchRepo(label: string, options: ScratchRepoOptions = { return { sourceRepo, root }; } +/** A bare repository a workspace host can clone, and the `file://` remote that names it. */ +export interface BareRemote { + /** Where the bare repository is. */ + path: string; + /** Its remote, as a project's `repository` names it and a host clones it. */ + url: string; +} + +/** + * A bare repository holding one scratch repository's base commit, for a + * project to name as its `repository` and a workspace host to clone over + * `file://`. + * + * Bare, because that is what a remote is: nobody works in it, and a host only + * fetches from it. Its `main` carries what {@link createScratchRepo} commits — + * the tracked files and the ask-marker ignore rule a host checks for — plus + * `seed`, which is where a check puts a marker it later looks for on the + * run's branch. + * + * @param label A short name, so a leftover directory says which check made it. + * @param options `seed`: extra files in the base commit. `at`: where to make + * it, instead of a fresh temp directory. A repository already at `at` is + * handed back as it is, so a server that restarts keeps naming the same one. + * @returns The bare repository's path and its `file://` remote. + */ +export function createBareRemote( + label: string, + options: { seed?: Record; at?: string } = {}, +): BareRemote { + const path = options.at ?? join(mkdtempSync(join(tmpdir(), `devforce-lab-${label}-remote-`)), `${label}.git`); + const url = pathToFileURL(path).href; + if (existsSync(path)) return { path, url }; + + const scratch = createScratchRepo(label, { ...(options.seed === undefined ? {} : { seed: options.seed }) }); + mkdirSync(dirname(path), { recursive: true }); + execFileSync("git", ["init", "--bare", "--quiet", `--initial-branch=${BASE_REF}`, path], { + stdio: "pipe", + timeout: GIT_TIMEOUT_MS, + }); + git(scratch.sourceRepo, "push", "--quiet", path, BASE_REF); + rmSync(scratch.sourceRepo, { recursive: true, force: true }); + rmSync(scratch.root, { recursive: true, force: true }); + return { path, url }; +} + /** * Publish refs from the source repository to the durable artifact repository. * diff --git a/goals/devforce-lab/lab/workforce/flows/workers/coder.mts b/goals/devforce-lab/lab/workforce/flows/workers/coder.mts index fb3cab12b7..d7d64fe239 100644 --- a/goals/devforce-lab/lab/workforce/flows/workers/coder.mts +++ b/goals/devforce-lab/lab/workforce/flows/workers/coder.mts @@ -44,6 +44,8 @@ import { defineFlow } from "@flow-state-dev/core"; import type { DeclaredResources } from "@flow-state-dev/core"; import { harnessManager, type PhaseSpec, type WorkspaceConfig } from "@flow-state-dev/harness-manager"; import type { HarnessBlock, HarnessCallbackContext } from "@flow-state-dev/core/types"; +import { projectWorkspaceCapability } from "@flow-state-dev/workforce"; +import type { WorkspaceHost } from "@flow-state-dev/workspace"; import { recipientBoard, RESUME_ENTRY, WORK_ENTRY, type FeatureLedger } from "../../../board.mts"; import { INSPECT_ENTRY, @@ -73,8 +75,13 @@ export interface CoderWorkerFlowOptions { resume: (ctx: HarnessCallbackContext) => string | null | Promise; onSession: (sessionId: string, ctx: HarnessCallbackContext) => void | Promise; }) => HarnessBlock; - /** Where checkouts are cut, from what, and off which ref. */ - workspace: WorkspaceConfig; + /** + * Where each run works: a fixed repository (`{ root, sourceRepo, baseRef }`), + * or a workspace host whose source is `projectWorkspace` on this kind's + * board, so a run works in its project's repository or on its project's + * files. + */ + workspace: WorkspaceConfig | WorkspaceHost; /** The one phase: how the prompt is built, and what counts as done. */ phase: PhaseSpec; /** Wall-clock budget for one harness run. */ @@ -111,6 +118,8 @@ export function defineCoderWorkerFlow(options: CoderWorkerFlowOptions) { workspace: options.workspace, runTimeoutMs: options.runTimeoutMs, harness: options.harness, + // The collections a project's run source reads, on the blocks that ask it. + ...("provision" in options.workspace ? { uses: [projectWorkspaceCapability] } : {}), } as never); // ---- the interim tax, and the whole of it ------------------------------ diff --git a/goals/devforce-lab/lab/workforce/org/workers/chief-of-staff/WORKER.md b/goals/devforce-lab/lab/workforce/org/workers/chief-of-staff/WORKER.md index ca8dc6c4ff..ad066e89f2 100644 --- a/goals/devforce-lab/lab/workforce/org/workers/chief-of-staff/WORKER.md +++ b/goals/devforce-lab/lab/workforce/org/workers/chief-of-staff/WORKER.md @@ -2,7 +2,7 @@ description: The person's one point of contact, and the one seat that changes who works here. flow: agent model: openai/gpt-5.4-mini -tools: [hire, fire, rehire, brokenSeats, post-to-mailbox, createProject, setWorkstreams] +tools: [hire, fire, rehire, brokenSeats, post-to-mailbox, createProject, setWorkstreams, setRepository] --- You are the chief of staff for this organization. You have three jobs. @@ -45,6 +45,12 @@ and gives its members one room to talk in. project holds it. - To change a project's workstreams later, call `setWorkstreams` with the whole new list. +- A project can name the git repository its code lives in: the remote, the + address you'd pass to `git clone`, never a folder. Pass it as `repository` + to `createProject` when the person names one, or call `setRepository` later + (`null` clears it, and the project's coding work runs on its files). The + person approves every repository in their Inbox before it is written. If + they deny it, nothing changed: say so plainly. After any change, tell the person in one or two sentences what you did, or what is waiting for their approval. diff --git a/goals/package.json b/goals/package.json index b7b8047966..441769eb86 100644 --- a/goals/package.json +++ b/goals/package.json @@ -28,6 +28,7 @@ "@flow-state-dev/store-sqlite": "workspace:*", "@flow-state-dev/testing": "workspace:*", "@flow-state-dev/workforce": "workspace:*", + "@flow-state-dev/workspace": "workspace:*", "@openai/codex-sdk": "0.152.1", "bullmq": "^5.0.0", "zod": "^3.25.76" diff --git a/labs/shift-manager/teams/devteam/fsdev.config.mts b/labs/shift-manager/teams/devteam/fsdev.config.mts index 2889143933..684b5832e1 100644 --- a/labs/shift-manager/teams/devteam/fsdev.config.mts +++ b/labs/shift-manager/teams/devteam/fsdev.config.mts @@ -27,6 +27,13 @@ * run's session and commits one file so the row settles; or `claude-code`, a * real coding agent. * + * - **Each project's own code.** The coder runs on a workspace host whose + * source is the project holding the board's workstream: Storefront names a + * repository (a bare one beside the store, reached over `file://`, which the + * host allows), so its runs are branches of it with the project's files in + * `project/` beside the checkout; Sandbox names none, so a run there works on + * the project's files alone. No folder is named for any of it. + * * - **A store that survives a restart.** SQLite, at `DEVTEAM_STORE` or * `labs/shift-manager/.fsdev/devteam.sqlite` by default. Seats the chief of * staff hired are read back and serve again at the next start, a fire it @@ -38,7 +45,7 @@ * in this file. */ import { mkdirSync, readFileSync } from "node:fs"; -import { dirname } from "node:path"; +import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { sqliteStores } from "@flow-state-dev/store-sqlite"; import { readDeclaredRoster } from "@flow-state-dev/workforce/loader"; @@ -47,7 +54,7 @@ import { ASSIGNEE } from "../../../../goals/devforce-lab/lab/board.mts"; import { selectHarness } from "../../../../goals/devforce-lab/lab/harness.mts"; import { boardMailboxOf, LAB_CROWD, LAB_ORG_ID, LAB_TREE, LAB_USERS, openLab } from "../../../../goals/devforce-lab/lab/host.mts"; import { createNotifyLog } from "../../../../goals/devforce-lab/lab/notify.mts"; -import { BASE_REF, createScratchRepo } from "../../../../goals/devforce-lab/lab/scratch-repo.mts"; +import { createBareRemote } from "../../../../goals/devforce-lab/lab/scratch-repo.mts"; import { CODER_KIND } from "../../../../goals/devforce-lab/lab/workforce/flows/workers/coder.mts"; import { EM_KIND } from "../../../../goals/devforce-lab/lab/workforce/flows/workers/em.mts"; import { setAsideLegacyOrgStore, setAsidePreRenameStore } from "./legacy-org-store.mts"; @@ -64,16 +71,27 @@ const ASK_FEATURE = ( ) as { feature: AskFeature } ).feature; +/** Where this Lab keeps what it was told, across restarts. */ +const STORE = process.env.DEVTEAM_STORE ?? fileURLToPath(new URL("../../.fsdev/devteam.sqlite", import.meta.url)); +mkdirSync(dirname(STORE), { recursive: true }); + +/** + * Storefront's repository: a bare one beside the store, made once and kept, so + * the project row a restart reads back still names a remote that exists. + */ +const storefrontRemote = createBareRemote("devteam-storefront", { at: join(dirname(STORE), "devteam-storefront.git") }); + /** - * The Lab's two default projects, created at start as the Lab's owner with + * The Lab's three default projects, created at start as the Lab's owner with * the second user as a member, unless the store already holds them. * * A project belongs to the organization, not a team: `storefront` holds one - * workstream from each of the two teams. The second holds none yet. Each team - * keeps one more workstream that no default project lists, so a project - * created later (by the chief of staff, say) has one from each team to take. - * Those are the only mailbox ids written here: which workstreams a project - * holds is the app's data, not the tree's. + * workstream from each of the two teams, and names its repository. The other + * two hold none yet; `sandbox` has no repository, so coding work moved onto it + * runs on its files. Each team keeps one more workstream that no default + * project lists, so a project created later (by the chief of staff, say) has + * one from each team to take. Those are the only mailbox ids written here: + * which workstreams a project holds is the app's data, not the tree's. */ const DEFAULT_PROJECTS = [ { @@ -82,6 +100,7 @@ const DEFAULT_PROJECTS = [ brief: "Get the storefront feature built and released: engineering builds it, operations ships it.", members: [LAB_USERS.member.userId, ...LAB_CROWD.map((u) => u.userId)], workstreams: ["eng.feature", "ops.release"], + repository: storefrontRemote.url, }, { id: "platform", @@ -89,6 +108,12 @@ const DEFAULT_PROJECTS = [ brief: "Shared groundwork no single feature owns. It holds no workstream yet.", members: [LAB_USERS.member.userId, ...LAB_CROWD.map((u) => u.userId)], }, + { + id: "sandbox", + title: "Sandbox", + brief: "A prototype from scratch: no repository, so its coding work runs on the project's own files.", + members: [LAB_USERS.member.userId, ...LAB_CROWD.map((u) => u.userId)], + }, ]; // The app's addresses, read off the tree: the coder seat whose name is the @@ -101,22 +126,19 @@ if (coderSeatId === undefined) throw new Error("the DevTeam tree declares no cod const members = (boardMailboxOf(roster).declared.members as string[] | undefined) ?? []; const addresses = Object.fromEntries(members.filter((m) => kindOf(m) === EM_KIND).map((m) => [m, m])); -/** Where this Lab keeps what it was told, across restarts. */ -const STORE = process.env.DEVTEAM_STORE ?? fileURLToPath(new URL("../../.fsdev/devteam.sqlite", import.meta.url)); -mkdirSync(dirname(STORE), { recursive: true }); // A store from before the lab's org id changed is set aside, loudly, not reused. await setAsideLegacyOrgStore(STORE); // So is one from before mailboxes were renamed. await setAsidePreRenameStore(STORE, { mailboxIds: roster.mailboxes.map((m) => m.id), orgIds: [LAB_ORG_ID] }); -const scratch = createScratchRepo("shift-manager"); const harness = selectHarness(); const lab = await openLab({ stores: sqliteStores({ filename: STORE }), harness: harness.slot, runTimeoutMs: harness.runTimeoutMs, - workspace: { root: scratch.root, sourceRepo: scratch.sourceRepo, baseRef: BASE_REF }, + // Runs' places and the host's clones, beside the store; only `file://` remotes are reached. + workspace: { root: join(dirname(STORE), "devteam-runs"), remotes: { allow: ["file"] } }, coderSeatId, mailboxes: { addresses, log: createNotifyLog() }, inventory: true, diff --git a/labs/shift-manager/test/devteam-repository-ask.test.ts b/labs/shift-manager/test/devteam-repository-ask.test.ts new file mode 100644 index 0000000000..2119a8aef7 --- /dev/null +++ b/labs/shift-manager/test/devteam-repository-ask.test.ts @@ -0,0 +1,162 @@ +/** + * The DevForce Lab's chief of staff and a project's repository: whichever way + * it writes one, at create or later, it waits for a person in Inbox first. + * Approve writes it; Deny writes nothing. + * + * The Lab is opened the way DevTeam's config opens it, with its default + * projects. The chief of staff's model is scripted to make one tool call, so + * no key is needed; the answer goes through the engine's own resume route, + * as Inbox sends it. + */ +import { afterEach, describe, expect, it } from "vitest"; +import { mkdtempSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import type { FlowInstance, GeneratorModel, ModelResolver, SuspensionRecord } from "@flow-state-dev/core/types"; +import { inMemoryStores, runAction } from "@flow-state-dev/engine"; +import { selectHarness } from "../../../goals/devforce-lab/lab/harness.mts"; +import { LAB_ORG_ID, LAB_USER_ID, openLab, type Lab } from "../../../goals/devforce-lab/lab/host.mts"; +import { createNotifyLog } from "../../../goals/devforce-lab/lab/notify.mts"; + +const COS = "chief-of-staff"; +const FIRST = "https://github.com/acme/storefront.git"; +const ASKED = "git@github.com:acme/storefront-next.git"; + +let opened: Lab | undefined; +afterEach(async () => { + await opened?.dispose(); + opened = undefined; +}); + +/** A model that makes `call` once, then stops. */ +function scripted(call: { toolName: string; args: Record }): ModelResolver { + let made = false; + const model: GeneratorModel = { + modelId: "test/step", + async generate() { + throw new Error("the owned tool loop calls generateStep"); + }, + async generateStep() { + if (made) return { text: "done", finishReason: "stop" }; + made = true; + return { toolCalls: [{ toolCallId: "t1", ...call }], finishReason: "tool-calls" }; + }, + }; + return Object.assign(() => model, { resolveId: (id: string) => id }) as unknown as ModelResolver; +} + +type ToolCall = { toolName: string; args: Record }; + +async function open(): Promise { + const harness = selectHarness(); + opened = await openLab({ + stores: inMemoryStores(), + harness: harness.slot, + runTimeoutMs: harness.runTimeoutMs, + workspace: { root: mkdtempSync(join(tmpdir(), "devteam-repository-ask-")), remotes: { allow: ["file"] } }, + coderSeatId: "eng.coder", + mailboxes: { addresses: {}, log: createNotifyLog() }, + inventory: true, + projects: [{ id: "storefront", title: "Storefront", workstreams: ["eng.feature"], repository: FIRST }], + }); + return opened; +} + +/** Ask the chief of staff, as the Lab's owner, with a model that makes `call`. */ +async function run(lab: Lab, call: ToolCall, message: string) { + const runtime = await lab.state.getRuntime(); + (runtime.runtimeConfig as { modelResolver?: ModelResolver }).modelResolver = scripted(call); + return await runAction({ + orgId: LAB_ORG_ID, + flow: runtime.registry.get(COS) as FlowInstance, + actionName: "run", + input: { message }, + userId: LAB_USER_ID, + sessionId: `s-cos-${globalThis.crypto.randomUUID()}`, + stores: runtime.stores, + runtimeConfig: runtime.runtimeConfig, + } as never); +} + +/** Ask the chief of staff, as the Lab's owner, and return its request and the one approval it raised. */ +async function ask(lab: Lab, call: ToolCall, message: string): Promise<{ requestId: string; suspension: SuspensionRecord }> { + const runtime = await lab.state.getRuntime(); + const started = await run(lab, call, message); + expect((await runtime.stores.request.get(started.requestId!))?.status).toBe("suspended"); + const pending = (await runtime.stores.suspensions.list({ status: "pending" })) as SuspensionRecord[]; + expect(pending).toHaveLength(1); + expect(pending[0]!.reason).toBe("human_approval"); + return { requestId: started.requestId!, suspension: pending[0]! }; +} + +/** Answer through the resume route, as Inbox does, and wait for the request to finish. */ +async function answer(lab: Lab, asked: { requestId: string; suspension: SuspensionRecord }, action: "approve" | "reject") { + const sent = await lab.door("POST", `${COS}/requests/${asked.requestId}/resume`, { + body: { suspensionId: asked.suspension.suspensionId, action }, + }); + expect(sent.status).toBe(202); + const runtime = await lab.state.getRuntime(); + for (let i = 0; i < 400; i += 1) { + const status = String((await runtime.stores.request.get(asked.requestId))?.status); + if (status !== "suspended" && status !== "in_progress") return status; + await new Promise((r) => setTimeout(r, 25)); + } + throw new Error("the answered request never finished"); +} + +/** The stored project rows, by id. */ +async function projects(lab: Lab): Promise> { + const rows = await lab.stored("org", ""); + return Object.fromEntries( + Object.entries(rows) + .filter(([key]) => /(^|\/)projects\/[^/]+$/.test(key)) + .map(([key, state]) => [key.slice(key.lastIndexOf("/") + 1), state as { repository?: string | null }]), + ); +} + +describe("the chief of staff's repository writes wait for a person", () => { + it("setRepository: nothing changes while it waits or on Deny; Approve writes it", async () => { + const lab = await open(); + const call = { toolName: "setRepository", args: { projectId: "storefront", repository: ASKED } }; + const asked = await ask(lab, call, "move storefront to the new repository"); + expect(asked.suspension.message).toContain(ASKED); + expect((await projects(lab)).storefront?.repository).toBe(FIRST); + + await answer(lab, asked, "reject"); + expect((await projects(lab)).storefront?.repository).toBe(FIRST); + + const again = await ask(lab, call, "move storefront to the new repository"); + await answer(lab, again, "approve"); + expect((await projects(lab)).storefront?.repository).toBe(ASKED); + }, 120_000); + + it("createProject with a repository: Deny creates nothing; without one it does not ask", async () => { + const lab = await open(); + const asked = await ask( + lab, + { toolName: "createProject", args: { id: "checkout", title: "Checkout", repository: ASKED } }, + "start a checkout project on that repository", + ); + expect(asked.suspension.message).toContain('"checkout"'); + expect((await projects(lab)).checkout).toBeUndefined(); + await answer(lab, asked, "reject"); + expect((await projects(lab)).checkout).toBeUndefined(); + + await run(lab, { toolName: "createProject", args: { id: "notes", title: "Notes" } }, "start a notes project"); + const runtime = await lab.state.getRuntime(); + expect(await runtime.stores.suspensions.list({ status: "pending" })).toHaveLength(0); + expect((await projects(lab)).notes).toMatchObject({ repository: null }); + }, 120_000); + + it("shows a person the remote without a password it carries", async () => { + const lab = await open(); + const asked = await ask( + lab, + { toolName: "setRepository", args: { projectId: "storefront", repository: "https://bot:s3cret-token@github.com/acme/storefront.git" } }, + "use the token remote", + ); + expect(asked.suspension.message).not.toContain("s3cret-token"); + expect(JSON.stringify(asked.suspension.data)).not.toContain("s3cret-token"); + await answer(lab, asked, "reject"); + }, 120_000); +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 344dd7a41f..56826da225 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -688,6 +688,9 @@ importers: '@flow-state-dev/workforce': specifier: workspace:* version: link:../packages/workforce + '@flow-state-dev/workspace': + specifier: workspace:* + version: link:../packages/workspace '@openai/codex-sdk': specifier: 0.152.1 version: 0.152.1 From 8cb2ab529669ca45005d84d658605f2b1c84c191 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 22:53:43 +0000 Subject: [PATCH 25/28] feat(shift-manager): a project's Brief names its repository (FIX-1762) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Brief tab shows the repository the project's coding work runs in, or "No repository · runs on project files". A legacy row reads as none. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5 --- apps/docs/docs/shift-manager/overview.md | 2 +- labs/shift-manager/README.md | 2 +- labs/shift-manager/src/lib/reads.ts | 7 ++++ labs/shift-manager/src/surfaces/Project.tsx | 39 +++++++++++++++------ labs/shift-manager/test/projects.test.tsx | 24 +++++++++++++ 5 files changed, 62 insertions(+), 12 deletions(-) diff --git a/apps/docs/docs/shift-manager/overview.md b/apps/docs/docs/shift-manager/overview.md index 65c1dcd4db..5286830936 100644 --- a/apps/docs/docs/shift-manager/overview.md +++ b/apps/docs/docs/shift-manager/overview.md @@ -56,7 +56,7 @@ These are Shift Manager's own screens and words. Where one maps onto a Workforce | **Tasks** | Every row on every board that isn't done, grouped by state, worker or workstream. Queued rows are behind a toggle. | | **Roster** | Every worker, grouped as on shift (running a task), on call (waiting on you), or off shift. | | **A workstream** | A declared [mailbox](../workforce/mailboxes.md) and the boards it holds, the same workstream a [project](../workforce/projects.md) groups. Tabs: Stream (the transcript, which you can post to), Board, Brief (the mailbox's charter) and Results. | -| **A project** | Groups workstreams and has one room its members share. Tabs: Stream (the room), Board, Workstreams and Brief. See [Projects](../workforce/projects.md) and [A room or a mailbox](../workforce/projects.md#a-room-or-a-mailbox). | +| **A project** | Groups workstreams and has one room its members share. Tabs: Stream (the room), Board, Workstreams and Brief, which also names the project's repository, or says its coding work runs on the project's files. See [Projects](../workforce/projects.md) and [A room or a mailbox](../workforce/projects.md#a-room-or-a-mailbox). | | **A task** | One worker's run, live, with Interrupt to stop it. *Open trace* opens the run's session in the DevTool (see [Opening a session from a link](../devtool/overview.md#opening-a-session-from-a-link)). | The sidebar lists the projects with their workstreams under PROJECTS, then the teams under TEAMS. Workstreams that no project lists sit under **No project**. Jump to (⌘K) finds workstreams, workers, tasks and the Lab's readable documents. diff --git a/labs/shift-manager/README.md b/labs/shift-manager/README.md index 1048e048a3..120597d13d 100644 --- a/labs/shift-manager/README.md +++ b/labs/shift-manager/README.md @@ -193,7 +193,7 @@ A Lab with no chief of staff needs nothing in its config. Every screen works, an - **Tasks.** Every row on every attached board that isn't done, grouped by state, worker or workstream. Each row shows its id and, while it runs, how long it has been running. Queued tasks, blocked ones included, stay hidden until you turn on the Queued toggle, which shows how many there are. - **Roster.** Every worker in the Lab, grouped by whether it's on shift, on call or off shift. Pick a team at the top to see only its workers. See [Roster](#roster). - **PROJECTS.** Each of the Lab's projects by title, with the workstreams its record lists beneath it. A project with no workstreams is still listed. Workstreams no project lists sit under **No project**, which shows only when there is one. Clicking the PROJECTS heading opens No project. -- **A project.** Four tabs. **Stream** is the project's room: one conversation its members share with the project's seats. You read and post through your own talk session on the project. A member who has none gets Join, and someone who isn't a member is told the room is for its members and sees none of it. The room opens at its newest lines, and **Load earlier** reads the page before them. Every read is a small recorded request on your talk session, so the room reads only at set times: when you open it, when the window gets focus, when you come back to the tab, and after you post. Each of those starts a short run of reads, about a second apart while lines are arriving and further apart as it goes quiet. After about 45 quiet seconds the room stops reading. That is how the seats' answers to your post show up. A room left open and idle doesn't fetch anything new. Other members' lines appear the next time you open the room, focus the window, come back to the tab, or post. **Board** draws a lane for each of its workstreams that holds a board. **Workstreams** lists the workstreams the project holds, and **Brief** is the project's brief. No project has no room and no brief, and says so. +- **A project.** Four tabs. **Stream** is the project's room: one conversation its members share with the project's seats. You read and post through your own talk session on the project. A member who has none gets Join, and someone who isn't a member is told the room is for its members and sees none of it. The room opens at its newest lines, and **Load earlier** reads the page before them. Every read is a small recorded request on your talk session, so the room reads only at set times: when you open it, when the window gets focus, when you come back to the tab, and after you post. Each of those starts a short run of reads, about a second apart while lines are arriving and further apart as it goes quiet. After about 45 quiet seconds the room stops reading. That is how the seats' answers to your post show up. A room left open and idle doesn't fetch anything new. Other members' lines appear the next time you open the room, focus the window, come back to the tab, or post. **Board** draws a lane for each of its workstreams that holds a board. **Workstreams** lists the workstreams the project holds, and **Brief** is the project's brief, under the repository its coding work runs in, or *No repository · runs on project files*. No project has no room and no brief, and says so. - **A workstream.** One mailbox and the boards attached to it. It has four tabs: Stream (the transcript and the composer), Board (five columns: QUEUED, RUNNING, IN REVIEW, NEEDS YOU, DONE; a done task is one line, its id and title), Brief (the mailbox's charter) and Results. A member's ask shows up in the transcript at the time it was raised, marked NEEDS YOU. Answering it there clears it from Inbox. The right panel lists the mailbox's members with their status, and its rows by column. - **A task.** One task's run, live, with Interrupt. See [A task](#a-task). diff --git a/labs/shift-manager/src/lib/reads.ts b/labs/shift-manager/src/lib/reads.ts index a1c4e2fe66..c73a23408b 100644 --- a/labs/shift-manager/src/lib/reads.ts +++ b/labs/shift-manager/src/lib/reads.ts @@ -130,6 +130,12 @@ export type Project = { members: string[]; /** The mailbox ids the project holds, as the row lists them. */ workstreams: string[]; + /** + * The git remote the project's code lives in, or `null` when it has none + * (its coding work runs on its files). A row written before the field + * existed reads as none. + */ + repository: string | null; /** Each member's talk session, at most one per person. */ sessions: ProjectSession[]; }; @@ -431,6 +437,7 @@ export function toProject(row: unknown): Project | undefined { ownerUserId, members: strings(field(row, "members")), workstreams: strings(field(row, "workstreams")), + repository: text(field(row, "repository")), sessions: Array.isArray(sessions) ? sessions.flatMap((link) => { const sessionId = text(field(link, "sessionId")); diff --git a/labs/shift-manager/src/surfaces/Project.tsx b/labs/shift-manager/src/surfaces/Project.tsx index 56a0c93ddf..fb18bd116e 100644 --- a/labs/shift-manager/src/surfaces/Project.tsx +++ b/labs/shift-manager/src/surfaces/Project.tsx @@ -13,7 +13,8 @@ * - **Workstreams** lists the workstreams the project's row names, each * linking to its own level. One whose mailbox has left the tree is shown as * gone, with no link. - * - **Brief** is the row's brief. + * - **Brief** is the row's brief, under the repository its code lives in, or + * a line saying it has none and its coding work runs on its files. * * No project holds the workstreams no project lists (D3): its Board and * Workstreams list them, and it has no room and no brief. @@ -115,15 +116,18 @@ export function ProjectView({ tab === "stream" ? ( ) : tab === "brief" ? ( - group.project.brief === null ? ( - - This project was created without a brief. - - ) : ( -
- {group.project.brief} -
- ) +
+ + {group.project.brief === null ? ( + + This project was created without a brief. + + ) : ( +
+ {group.project.brief} +
+ )} +
) : tab === "board" ? ( ) : ( @@ -162,6 +166,21 @@ export function ProjectView({ ); } +/** The project's repository on its Brief, or that it has none and runs on its files. */ +function Repository({ repository }: { repository: string | null }) { + return ( +

+ {repository === null ? ( + "No repository · runs on project files" + ) : ( + <> + Repository {repository} + + )} +

+ ); +} + /** Each listed workstream, linking to it; one that left the tree, as gone (BR-27). */ function WorkstreamList({ listed }: { listed: readonly ListedWorkstream[] }) { if (listed.length === 0) { diff --git a/labs/shift-manager/test/projects.test.tsx b/labs/shift-manager/test/projects.test.tsx index 6354eba6a4..bf43f057cd 100644 --- a/labs/shift-manager/test/projects.test.tsx +++ b/labs/shift-manager/test/projects.test.tsx @@ -245,6 +245,22 @@ describe("a project's tabs (BR-25 to BR-29)", () => { expect(listed).toEqual((await storedRow(baseUrl, "desk")).workstreams); }); + it("Brief names the repository a project's code lives in, or says it runs on its files", async () => { + const remote = "https://github.com/acme/desk.git"; + const { baseUrl } = await lab([ + { id: "desk", title: "The desk", brief: "Keep the request desk moving.", members: [OTHER], workstreams: ["ops.desk"], repository: remote }, + { id: "empty", title: "Nothing yet", members: [OTHER] }, + ]); + openApp(baseUrl, "/p/desk/brief"); + expect((await screen.findByTestId("project-repository")).textContent).toBe(`Repository ${(await storedRow(baseUrl, "desk")).repository}`); + expect(screen.getByTestId("project-brief").textContent).toBe("Keep the request desk moving."); + cleanup(); + + openApp(baseUrl, "/p/empty/brief"); + expect((await screen.findByTestId("project-repository")).textContent).toBe("No repository · runs on project files"); + await screen.findByTestId("project-brief-none"); + }); + it("a project with no workstreams and no brief names each empty tab", async () => { const { baseUrl } = await lab(); openApp(baseUrl, "/p/empty/board"); @@ -615,6 +631,7 @@ describe("grouping is the snapshot's (V4)", () => { ownerUserId: "alice", members: ["alice"], workstreams: [], + repository: null, sessions: [], ...over, }); @@ -627,6 +644,13 @@ describe("grouping is the snapshot's (V4)", () => { expect(toProject({ ...row, brief: 7 })?.brief).toBeNull(); }); + it("a row's repository: a remote reads as written; a row from before the field, or null, is none", () => { + const row = { id: "p", title: "P", ownerUserId: ASK_LAB_USER_ID }; + expect(toProject({ ...row, repository: "git@github.com:acme/p.git" })?.repository).toBe("git@github.com:acme/p.git"); + expect(toProject(row)?.repository).toBeNull(); + expect(toProject({ ...row, repository: null })?.repository).toBeNull(); + }); + it("projectsOf groups a cross-team project, keeps a gone id as gone, and makes no read", () => { const spy = vi.spyOn(globalThis, "fetch"); const view = projectsOf(snapshot([project({ id: "s", workstreams: ["eng.a", "ops.b", "ops.gone"] })])); From 8e3503a3b1430cea40044d1ede6a9fdd4b80cd79 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 22:59:14 +0000 Subject: [PATCH 26/28] test(devforce-lab): goal check, it codes in the project's repository (FIX-1762) Three legs on the DevTeam lab: a project with a repository runs on a branch of it with its kept files beside the checkout; a project without one runs on its files and the next run sees them; a remote the host does not allow is refused by name before anything is cloned. Controls fixed-source and no-sync-back. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5 --- .../fixtures/input.json | 7 + .../goal.md | 67 ++++ .../run.mts | 316 ++++++++++++++++++ goals/devforce-lab/lab/README.md | 3 +- 4 files changed, 392 insertions(+), 1 deletion(-) create mode 100644 goals/devforce-lab/it-codes-in-the-projects-repository/fixtures/input.json create mode 100644 goals/devforce-lab/it-codes-in-the-projects-repository/goal.md create mode 100644 goals/devforce-lab/it-codes-in-the-projects-repository/run.mts diff --git a/goals/devforce-lab/it-codes-in-the-projects-repository/fixtures/input.json b/goals/devforce-lab/it-codes-in-the-projects-repository/fixtures/input.json new file mode 100644 index 0000000000..a50195472c --- /dev/null +++ b/goals/devforce-lab/it-codes-in-the-projects-repository/fixtures/input.json @@ -0,0 +1,7 @@ +{ + "marker": { "path": "MARKER-A.txt" }, + "note": { "path": "notes/storefront-plan.md", "body": "What the storefront run learned, kept beside its checkout.\n" }, + "code": { "path": "src/greeting.js", "body": "export const greeting = \"hello from the storefront run\";\n" }, + "sandboxFile": { "path": "app/index.html", "body": "

A prototype from scratch

\n" }, + "disallowedRemote": "https://git.example.com/acme/platform.git" +} diff --git a/goals/devforce-lab/it-codes-in-the-projects-repository/goal.md b/goals/devforce-lab/it-codes-in-the-projects-repository/goal.md new file mode 100644 index 0000000000..f4e538d61d --- /dev/null +++ b/goals/devforce-lab/it-codes-in-the-projects-repository/goal.md @@ -0,0 +1,67 @@ +# devforce-lab › it codes in the project's repository + +**Issue:** FIX-1762 + +**Outcome:** In the DevTeam lab, a coding run works where its project says. A project that names a +repository gets a fresh branch of that repository, with the project's files in `project/` beside +the checkout and never inside it. A project with no repository runs on its files alone, and each +run starts from what the last one saved. A remote the host does not allow is refused by name before +anything is cloned or run. Whatever a run keeps is saved back to the project. + +Before this, every run in the lab was cut from one fixed scratch repository, whatever project held +the board, and nothing a run wrote outside git survived it. + +**Input:** `fixtures/input.json`: the marker file's path, the note the storefront run keeps in +`project/`, the code it commits, the file the sandbox run writes, and a remote the host does not +allow. It is **held-out**: the stub reads every path and body from the row it is handed, so a +fixture with other paths, nested directories or another disallowed remote passes a correct +implementation (one was run; see the verdict log). + +**Signal:** three legs, on one lab opened as the DevTeam profile opens it, with three projects +(storefront with a bare `file://` repository holding marker A, sandbox with none, platform). Which +project holds `eng.feature` is moved between legs with the project writes, as a person would. + +- **a** storefront: its run's branch holds marker A and the run's commit (`a:ran`, `a:marker`, + `a:commit`); the note is in neither the branch nor `git status` (`a:note-not-in-git`) and is in + `project-files/storefront/` (`a:note-saved`); nothing from the checkout reached the project's + files (`a:checkout-not-in-files`). +- **b** sandbox: the first run starts in an empty `workspace/` (`b:first-ran`, + `b:first-run-empty`); its file is in `project-files/sandbox/` (`b:file-saved`); the second run + starts with it (`b:second-ran`, `b:second-run-sees-file`); a run in platform starts with nothing + (`b:other-project-ran`, `b:other-project-sees-nothing`). +- **c** platform names the disallowed remote: the row is cancelled before its harness runs + (`c:not-run`), with a refusal naming the remote and `remote-not-allowed` (`c:refused-by-name`), + and the host's clones hold only storefront's (`c:nothing-cloned`). + +**Anti-game:** a hollow pass is a run whose files came from somewhere other than the project. So +every leg is read off where the work landed, never off what the lab says it did: git on the bare +remote's clone and the run's branch, the run's own directory, and the organization's storage read +through `lab.stored`. The stub records the directory it was started in and what was in it before it +wrote anything. Rows are filed through the EM worker and run by its drain, as in the other checks. + +**Controls:** `GOAL_CONTROL=list` prints them. + +| Control | Perturbs | Goes red on | +|---|---|---| +| `fixed-source` | the manager on the lab's one fixed scratch repository, as before | `a:marker` (and every leg that needs a project's source) | +| `no-sync-back` | the host saves nothing back | `b:second-run-sees-file` (and `a:note-saved`, `b:file-saved`) | + +**Model:** n/a (model-free by design; the harness is the lab's scripted stub). + +**Run:** `pnpm tsx goals/devforce-lab/it-codes-in-the-projects-repository/run.mts` + +Needs `git` and a writable temp directory. No network, no model credential. + +## What this establishes, and what it does not + +It establishes that the lab's coder, built on `localWorkspaceHost` with `projectWorkspace` as its +source, takes its repository or its files from the project holding the board, saves what the run +keeps back to that project, and refuses a remote the host does not allow before anything runs. It +does **not** establish that a real coding agent uses `project/` well, nor that a remote over the +network clones: every remote here is a `file://` bare repository. + +## Verdict log +| Date | Commit | Model | Verdict | Notes | +|------|--------|-------|---------|-------| +| 2026-10-04 | 8edde510c+wip (#2744 head merged with #2738 head) | n/a | PASS | All three legs green, about 4 s. `fixed-source` FAILs on `a:marker` "does not hold MARKER-A.txt with marker A: it was not cut from storefront's repository", and on the legs that need a project's source. `no-sync-back` FAILs on exactly `a:note-saved`, `b:file-saved` and `b:second-run-sees-file` "the second run started with [], not the first run's app/index.html". Same tree: `it-keeps…`, `it-waits…` and `it-wakes…` PASS. | +| 2026-10-04 | dfc3b2a4f+wip | n/a | PASS | Held-out run with a second fixture: nested paths and an ssh `git@` remote as the disallowed one. PASS once `c:refused-by-name` matched the remote's host and path, since the host leaves the login out of what it shows. The fixture was restored after. | diff --git a/goals/devforce-lab/it-codes-in-the-projects-repository/run.mts b/goals/devforce-lab/it-codes-in-the-projects-repository/run.mts new file mode 100644 index 0000000000..5e75c92adf --- /dev/null +++ b/goals/devforce-lab/it-codes-in-the-projects-repository/run.mts @@ -0,0 +1,316 @@ +/** + * Goal check — a coding run works in its project's repository, or on its + * project's files, and what it keeps is saved to the project. + * + * The DevTeam lab, opened as its profile is served: the coder kind's manager + * runs on a workspace host whose source is `projectWorkspace` on the feature + * mailbox's board, and the host may reach `file://` remotes only. The harness + * is the lab's scripted stub; what is graded is where a run's files came from + * and where they went, read off git, the run's directory and the + * organization's storage. Rows are filed through the EM seat and run by its + * drain, exactly as the other checks run them. Which project holds the board's + * workstream is moved between legs with the project writes, as a person would. + * + * Legs: + * + * a storefront names a bare repository holding marker A. Its run's branch + * holds marker A and the run's commit; the note the run wrote in + * `project/` is in `project-files/storefront/` and in neither the + * branch nor `git status`; nothing from the checkout reached the files. + * b sandbox names no repository. Its first run starts in an empty + * `workspace/`; the file it writes is in `project-files/sandbox/`; its + * second run's `workspace/` holds that file; a run in platform does not. + * c platform names a remote the host does not allow. The row is refused + * naming the remote, the harness never runs, and nothing is cloned. + * + * Controls: + * + * fixed-source the manager on the lab's one fixed repository, as before. + * Must FAIL at `a:marker`. + * no-sync-back the host saves nothing back. Must FAIL at + * `b:second-run-sees-file`. + * + * `GOAL_CONTROL=list` prints them. + * + * Run: pnpm tsx goals/devforce-lab/it-codes-in-the-projects-repository/run.mts + */ +import { execFileSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { inMemoryStores } from "@flow-state-dev/engine"; +import { harnessTaskId } from "@flow-state-dev/harness-manager/checkout"; +import type { Task } from "@flow-state-dev/orchestration/tasks"; +import { hashContent } from "@flow-state-dev/workspace"; +import { loadFixture, runGoal, silentLogger } from "../../lib/index.mts"; +import { harnessStub, type StubRun } from "../lab/harness-stub.mts"; +import { openLab, type Lab, type OpenLabOptions } from "../lab/host.mts"; +import { createNotifyLog } from "../lab/notify.mts"; +import { PHASE } from "../lab/phase.mts"; +import { BASE_REF, commitAll, createBareRemote, createScratchRepo } from "../lab/scratch-repo.mts"; + +const CONTROL = process.env.GOAL_CONTROL ?? ""; +const CONTROLS = ["fixed-source", "no-sync-back"] as const; +if (CONTROL === "list") { + console.log(`controls: ${CONTROLS.join(", ")}`); + process.exit(0); +} +if (CONTROL !== "" && !(CONTROLS as readonly string[]).includes(CONTROL)) { + console.error(`unknown GOAL_CONTROL "${CONTROL}"; known: ${CONTROLS.join(", ")}`); + process.exit(2); +} + +interface Fixture { + marker: { path: string }; + note: { path: string; body: string }; + code: { path: string; body: string }; + sandboxFile: { path: string; body: string }; + disallowedRemote: string; +} +const fixture = loadFixture(import.meta.url); + +/** The seat the board's `coder` assignee is addressed to, and the seat that files and drains. */ +const CODER_SEAT = "eng.coder"; +const EM_SEAT = "eng.em"; +/** The rows, one per run. The issue slug is what the stub reads off the prompt. */ +const ISSUE = { + storefront: "storefront-note", + sandboxFirst: "sandbox-first", + sandboxSecond: "sandbox-second", + platform: "platform-check", + refused: "platform-remote", +} as const; +const SETTLE_BUDGET_MS = 60_000; +const SETTLED = new Set(["completed", "errored", "failed", "cancelled"]); +const sleep = (ms: number): Promise => new Promise((resolve) => setTimeout(resolve, ms)); + +/** What one run was handed: where it worked, and every file there (path → contents) when it started. */ +interface SeenRun { + cwd: string; + started: Record; +} +const seen = new Map(); + +/** Every file under `dir`, recursively, as relative path → contents. Git's and the manager's own directories are not the run's files. */ +function filesIn(dir: string, prefix = ""): Record { + const out: Record = {}; + if (!existsSync(dir)) return out; + for (const entry of readdirSync(dir)) { + if (prefix === "" && (entry === ".git" || entry === ".fsdev")) continue; + const full = join(dir, entry); + const rel = prefix === "" ? entry : `${prefix}/${entry}`; + if (statSync(full).isDirectory()) Object.assign(out, filesIn(full, rel)); + else out[rel] = readFileSync(full, "utf8"); + } + return out; +} + +function write(path: string, body: string): void { + mkdirSync(dirname(path), { recursive: true }); + writeFileSync(path, body); +} + +/** + * What each run does. It works where the manager put it and names no folder + * of its own: a repository run writes code in its checkout and commits it, and + * a note in `project/` beside it; a run with no repository writes in its + * working directory. + */ +function duringRun(run: StubRun): void { + const issue = /^Row ([^,\s]+),/m.exec(run.prompt)?.[1] ?? ""; + seen.set(issue, { cwd: run.cwd, started: filesIn(run.cwd) }); + if (issue === ISSUE.storefront) { + write(join(run.cwd, fixture.code.path), fixture.code.body); + write(join(run.cwd, "..", "project", fixture.note.path), fixture.note.body); + commitAll(run.cwd, "storefront run: add the greeting"); + } else if (issue === ISSUE.sandboxFirst) { + write(join(run.cwd, fixture.sandboxFile.path), fixture.sandboxFile.body); + } else { + // Every other run leaves a file of its own, so it settles on its own work. + write(join(run.cwd, `${issue}.txt`), `${issue}\n`); + if (existsSync(join(run.cwd, ".git"))) commitAll(run.cwd, `${issue}: a file of its own`); + } +} + +function git(cwd: string, ...args: string[]): string { + return execFileSync("git", args, { cwd, stdio: "pipe", encoding: "utf8" }).trim(); +} + +/** File one row through the EM seat, then drain until it settles. */ +async function runRow(lab: Lab, issue: string): Promise { + const filed = await lab.file(EM_SEAT, { issue, goal: `Run ${issue} for the project that holds this workstream.`, maxAttempts: 1 }); + if (filed.error !== undefined) throw new Error(`filing ${issue} was refused — ${filed.error}`); + const taskId = harnessTaskId(issue, PHASE); + const deadline = Date.now() + SETTLE_BUDGET_MS; + let row: Task | undefined; + while (Date.now() < deadline) { + row = await lab.row(taskId); + if (row !== undefined && SETTLED.has(row.status)) return row; + if (row === undefined || row.status === "pending") await lab.drain(EM_SEAT); + await sleep(200); + } + return row; +} + +/** Hand the board's workstream to one project, as its members would. */ +async function moveWorkstream(lab: Lab, from: string, to: string): Promise { + for (const [projectId, workstreams] of [ + [from, []], + [to, ["eng.feature"]], + ] as const) { + const done = await lab.projectAct!("setWorkstreams", { projectId, workstreams }); + if (done.error !== undefined) throw new Error(`setWorkstreams ${projectId} was refused — ${done.error}`); + } +} + +/** The organization's stored project files, as `/` → content hash. */ +async function storedFiles(lab: Lab): Promise> { + const out: Record = {}; + for (const [key, state] of Object.entries(await lab.stored("org", ""))) { + const at = key.indexOf("project-files/"); + if (at < 0) continue; + out[key.slice(at + "project-files/".length)] = (state as { hash?: string | null }).hash ?? null; + } + return out; +} + +await runGoal(async () => { + const failures: string[] = []; + const evidence: string[] = []; + const note = (assertion: string, why: string): void => { + failures.push(`${CONTROL === "" ? "" : `[control ${CONTROL}] `}${assertion} — ${why}`); + }; + + // ---- the input: a bare repository holding marker A ---------------------- + const markerToken = `marker A ${globalThis.crypto.randomUUID()}\n`; + const remoteA = createBareRemote("projects-repo-a", { seed: { [fixture.marker.path]: markerToken } }); + const root = mkdtempSync(join(tmpdir(), "devforce-lab-projects-repo-places-")); + // The control: the lab's one fixed repository, which holds no marker. + const fixed = CONTROL === "fixed-source" ? createScratchRepo("projects-repo-fixed") : undefined; + const workspace: OpenLabOptions["workspace"] = + fixed === undefined ? { root, remotes: { allow: ["file"] } } : { root: fixed.root, sourceRepo: fixed.sourceRepo, baseRef: BASE_REF }; + + const stub = harnessStub({ duringRun }); + const lab = await openLab({ + stores: inMemoryStores(), + harness: stub.slot, + workspace, + coderSeatId: CODER_SEAT, + logger: silentLogger, + mailboxes: { addresses: { [EM_SEAT]: EM_SEAT }, log: createNotifyLog() }, + inventory: true, + projects: [ + { id: "storefront", title: "Storefront", workstreams: ["eng.feature"], repository: remoteA.url }, + { id: "sandbox", title: "Sandbox" }, + { id: "platform", title: "Platform" }, + ], + ...(CONTROL === "no-sync-back" ? { saveNothing: true } : {}), + }); + + try { + // ---- (a) storefront: its repository, its notes ------------------------ + const a = await runRow(lab, ISSUE.storefront); + const aRun = seen.get(ISSUE.storefront); + if (a?.status !== "completed" || aRun === undefined) { + note("a:ran", `the storefront row ended ${a?.status ?? "unfiled"} and the harness ${aRun === undefined ? "never ran" : "ran"}`); + } else { + const branch = git(aRun.cwd, "rev-parse", "--abbrev-ref", "HEAD"); + let markerOnBranch = ""; + try { + markerOnBranch = git(aRun.cwd, "show", `${branch}:${fixture.marker.path}`); + } catch { + // Absent from the branch. + } + if (`${markerOnBranch}\n` !== markerToken) { + note("a:marker", `branch "${branch}" does not hold ${fixture.marker.path} with marker A: it was not cut from storefront's repository`); + } + const subjects = git(aRun.cwd, "log", "--format=%s", branch); + const tracked = git(aRun.cwd, "ls-tree", "-r", "--name-only", branch).split("\n"); + if (!subjects.includes("storefront run: add the greeting") || !tracked.includes(fixture.code.path)) { + note("a:commit", `branch "${branch}" does not carry the run's commit of ${fixture.code.path}`); + } + const status = git(aRun.cwd, "status", "--porcelain", "--untracked-files=all"); + if (status !== "" || tracked.includes(fixture.note.path)) { + note("a:note-not-in-git", `the run's note shows in git (status: ${JSON.stringify(status)})`); + } + const stored = await storedFiles(lab); + if (stored[`storefront/${fixture.note.path}`] !== hashContent(fixture.note.body)) { + note("a:note-saved", `project-files/storefront/${fixture.note.path} holds ${JSON.stringify(stored[`storefront/${fixture.note.path}`] ?? "nothing")}, not the note the run wrote`); + } + const leaked = Object.keys(stored).filter((key) => key.endsWith(fixture.code.path)); + if (leaked.length > 0) note("a:checkout-not-in-files", `the checkout's ${fixture.code.path} reached the project's files: ${leaked.join(", ")}`); + if (failures.length === 0) { + evidence.push( + `a: branch "${branch}" holds marker A and "storefront run: add the greeting"; the note is in ` + + `project-files/storefront/${fixture.note.path} and git status is clean`, + ); + } + } + + // ---- (b) sandbox: no repository, the project's files ------------------ + await moveWorkstream(lab, "storefront", "sandbox"); + const b1 = await runRow(lab, ISSUE.sandboxFirst); + const b1Run = seen.get(ISSUE.sandboxFirst); + const before = failures.length; + if (b1?.status !== "completed" || b1Run === undefined) { + note("b:first-ran", `the first sandbox row ended ${b1?.status ?? "unfiled"}`); + } else if (Object.keys(b1Run.started).length !== 0) { + note("b:first-run-empty", `the first run started with ${Object.keys(b1Run.started).join(", ")}`); + } + const afterFirst = await storedFiles(lab); + if (afterFirst[`sandbox/${fixture.sandboxFile.path}`] !== hashContent(fixture.sandboxFile.body)) { + note("b:file-saved", `project-files/sandbox/${fixture.sandboxFile.path} holds ${JSON.stringify(afterFirst[`sandbox/${fixture.sandboxFile.path}`] ?? "nothing")}`); + } + const b2 = await runRow(lab, ISSUE.sandboxSecond); + const b2Run = seen.get(ISSUE.sandboxSecond); + if (b2Run === undefined) { + note("b:second-ran", `the second sandbox row ended ${b2?.status ?? "unfiled"} before its harness ran`); + } else if (b2Run.started[fixture.sandboxFile.path] !== fixture.sandboxFile.body) { + note("b:second-run-sees-file", `the second run started with [${Object.keys(b2Run.started).join(", ")}], not the first run's ${fixture.sandboxFile.path}`); + } + await moveWorkstream(lab, "sandbox", "platform"); + await runRow(lab, ISSUE.platform); + const pRun = seen.get(ISSUE.platform); + if (pRun === undefined) { + note("b:other-project-ran", "the platform row's harness never ran"); + } else if (Object.keys(pRun.started).length !== 0) { + note("b:other-project-sees-nothing", `a run in platform started with ${Object.keys(pRun.started).join(", ")}`); + } + if (failures.length === before) { + evidence.push( + `b: the first sandbox run started in an empty ${b1Run!.cwd.split("/").slice(-1)[0]}/, its ` + + `${fixture.sandboxFile.path} is in project-files/sandbox/, the second run started with it, and a ` + + `platform run started empty`, + ); + } + + // ---- (c) a remote the host does not allow ----------------------------- + const set = await lab.projectAct!("setRepository", { projectId: "platform", repository: fixture.disallowedRemote }); + if (set.error !== undefined) throw new Error(`setRepository was refused — ${set.error}`); + const beforeC = failures.length; + const clonesBefore = existsSync(join(root, ".clones")) ? readdirSync(join(root, ".clones")).filter((e) => e.endsWith(".git")) : []; + const c = await runRow(lab, ISSUE.refused); + const reason = JSON.stringify(c ?? {}); + if (seen.has(ISSUE.refused)) note("c:not-run", "the harness ran for a remote the host does not allow"); + // Named by host and path: a host shows a remote without its login, so `git@` may be left out. + const remote = new URL(fixture.disallowedRemote); + const named = reason.includes(remote.hostname) && reason.includes(remote.pathname); + if (c?.status !== "cancelled" || !named || !reason.includes("remote-not-allowed")) { + note("c:refused-by-name", `the row ended ${c?.status ?? "unfiled"} without a refusal naming ${fixture.disallowedRemote}`); + } + const clonesAfter = existsSync(join(root, ".clones")) ? readdirSync(join(root, ".clones")).filter((e) => e.endsWith(".git")) : []; + const newClones = clonesAfter.filter((e) => !clonesBefore.includes(e)); + if (newClones.length > 0) note("c:nothing-cloned", `the host cloned ${newClones.join(", ")}`); + const refusal = (c as { error?: unknown; reason?: unknown } | undefined) ?? {}; + if (failures.length === beforeC) { + evidence.push( + `c: the row was cancelled before its harness ran (${String(refusal.error ?? refusal.reason ?? "").slice(0, 160)}), ` + + `and ${root}/.clones holds only [${clonesAfter.join(", ")}]`, + ); + } + + return { failures, evidence: evidence.join("; ") }; + } finally { + await lab.dispose(); + } +}); diff --git a/goals/devforce-lab/lab/README.md b/goals/devforce-lab/lab/README.md index e0b7bbbcfc..2aa3eb65da 100644 --- a/goals/devforce-lab/lab/README.md +++ b/goals/devforce-lab/lab/README.md @@ -12,7 +12,7 @@ declared seat wakes a **different** declared seat, in its own flow instance, int a supervised coding run whose prompt was built out of that seat's own files. A third seat, declared on the same kind, is never reached. -Five checks drive it. The first two differ by **one expression** — the harness +Six checks drive it. The first two differ by **one expression** — the harness slot; the third adds the two ends of the path neither of them reaches: | | | @@ -22,6 +22,7 @@ slot; the third adds the two ends of the path neither of them reaches: | [`../it-ships-an-artifact-a-person-can-open/`](../it-ships-an-artifact-a-person-can-open/) | The product check. A **post** is what starts the work, and the work is published to an address that outlives the run and judged against a condition the brief stated first. | | [`../it-keeps-its-rows-on-the-mailboxes-board/`](../it-keeps-its-rows-on-the-mailboxes-board/) | The board check. The feature mailbox holds the board its rows sit on, and a posted line ends as one completed row read back through the mailbox, the HTTP door and the organization's storage. No model. | | [`../it-waits-for-a-person-before-it-files/`](../it-waits-for-a-person-before-it-files/) | The approval check. With the ask turned on, the EM seat asks a person before it files a feature. Approve files the row and the coder starts; Deny files nothing. No model, and the answer goes through the session's own resume. | +| [`../it-codes-in-the-projects-repository/`](../it-codes-in-the-projects-repository/) | The project check. The coder runs on a workspace host whose source is the project holding the board's workstream: a project with a repository gets a branch of it, one without runs on its files, a remote the host does not allow is refused by name, and what a run keeps is saved to the project. No model. | It is **evidence, not an application**. Nobody opens it and clicks through it; you re-run it a year from now and compare against the verdict logs in the two From d0070bf67450a38d6f3b75e39e09170639a1c201 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 4 Oct 2026 22:59:25 +0000 Subject: [PATCH 27/28] docs(workforce): coding work in a project (FIX-1762) Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01P9UuEKLJUWaKiSrYWCJbt5 --- .../docs/orchestration/harness-manager.md | 2 +- apps/docs/docs/workforce/projects.md | 32 +++++++++++++++++++ packages/harness-manager/README.md | 12 +++++++ 3 files changed, 45 insertions(+), 1 deletion(-) diff --git a/apps/docs/docs/orchestration/harness-manager.md b/apps/docs/docs/orchestration/harness-manager.md index d8c2c6c711..c73d4f1a02 100644 --- a/apps/docs/docs/orchestration/harness-manager.md +++ b/apps/docs/docs/orchestration/harness-manager.md @@ -230,7 +230,7 @@ record instead of deriving them again. - **One host's storage.** Checkouts and their leases are on a local filesystem, so a retry inherits the last attempt's work because that work is on disk. On a multi-host deployment the recorded checkout names nothing on the machine that picks the retry up. - **No retention policy.** Run records and question rows grow without bound. Fine for a board driving a few tasks; a long-lived one needs pruning, which is not built. - **A harness that can't resume can't be sent a message.** A run on Claude Code's cloud dispatch, which never names a coding session, is refused with *this run's harness can't continue with a message*. -- **Git worktrees for a repository.** A run on a repository works in a `git worktree` of it. Where the repository comes from is up to the workspace host you pass as `workspace`; see the package README's "Running a project's work". +- **Git worktrees for a repository.** A run on a repository works in a `git worktree` of it. Where the repository comes from is up to the workspace host you pass as `workspace`; see the package README's "Running a project's work". For a mailbox board a project holds, Workforce's `projectWorkspace` is that source: see [A project's code and files](../workforce/projects.md#coding-work-in-a-project). ## Related pages diff --git a/apps/docs/docs/workforce/projects.md b/apps/docs/docs/workforce/projects.md index 672c3a12af..f7f16cfc2e 100644 --- a/apps/docs/docs/workforce/projects.md +++ b/apps/docs/docs/workforce/projects.md @@ -183,6 +183,36 @@ An SSH login name isn't a credential, so `git@github.com:acme/storefront.git` an Stored rows aren't re-parsed when they're read, so a row saved without a `repository` key reads without one. Treat a missing value as `null`, or read rows through `projectRowSchema.parse(row)`, which fills it in. +### Coding work in a project + +When a coding worker picks up work from one of the project's workstreams, it works in a fresh branch of the project's repository, as long as the host running the worker allows that remote. Nobody names a folder. Changing the repository applies to new work. Work already started stays where it began: on the repository it began with, or, if the project had none then, on the project's files. + +A project with no repository still runs coding work. The first run starts from an empty set of files, and everything it writes is saved to the [project's files](#the-projects-own-files). The next run starts from what the last one left. If two runs change the same file, the changes are merged; a real conflict is reported on the run instead of overwriting anyone's work. A run isn't marked done until what it wrote is saved: if the last save fails, the attempt fails and the retry saves it. + +To get this, build the coding worker's [harness manager](../orchestration/harness-manager.md) on a workspace host (from `@flow-state-dev/workspace`) whose source is `projectWorkspace`, given the same mailbox board the manager works: + +```ts +import { harnessManager } from "@flow-state-dev/harness-manager"; +import { localWorkspaceHost } from "@flow-state-dev/workspace"; +import { mailboxBoard, projectWorkspace, projectWorkspaceCapability } from "@flow-state-dev/workforce"; + +const work = mailboxBoard("eng.feature", "work"); + +harnessManager({ + boardCollectionId: work.id, + boardCollection: work, + workspace: localWorkspaceHost({ + root: "/var/fsd/runs", + remotes: { allow: ["github.com"] }, + source: projectWorkspace({ board: work }), + }), + uses: [projectWorkspaceCapability], + // ... +}); +``` + +`projectWorkspace` finds the project that holds the board's workstream and reads its row, nothing else. It refuses a run before any file is read when the person the run belongs to isn't one of the project's members (`not-a-member`), or when no project holds the workstream (`no-project`). The host refuses a remote its `remotes.allow` doesn't list, naming it, before anything is cloned; list `"file"` to allow `file://` remotes. A refused run isn't retried. + ### The project's own files Notes, memory and anything else kept for a project live in the organization's `project-files` collection, under the project's id: `project-files//`. Declare it with `defineProjectFilesCollection()`. Like `defineProjectsCollection()`, every call returns the same declaration. It's org-scoped, shared across flows, and loaded only when read. @@ -206,6 +236,8 @@ It lists paths and sizes, not file contents. A block's output is recorded in the It returns that project's files, never another project's. A non-member is refused with `not-a-member`, and an unknown id with `no-such-project`. The collection has no browser read: a request for it through the collection route gets a 403. +In a project with a repository, a coding run finds the project's files in `project/`, next to its checkout and never inside it, so they don't show up in `git status`. Whatever the run leaves there is saved back to the project. + ## The room and talk sessions A project's room is stored on the organization's side, one row per line. Nobody reaches it directly. Each member gets their own **talk session**: a session on the mailbox kind that knows which project it's about. Every room call goes through one. diff --git a/packages/harness-manager/README.md b/packages/harness-manager/README.md index e82bd87a1f..20b647243c 100644 --- a/packages/harness-manager/README.md +++ b/packages/harness-manager/README.md @@ -55,6 +55,18 @@ harnessManager({ }); ``` +For a mailbox board a project holds, `@flow-state-dev/workforce` provides the source: `projectWorkspace({ board: work })` answers with the repository of the project that holds the board's workstream, with the project's files beside the checkout, or the project's files alone when it has none. It reads its collections through `projectWorkspaceCapability`, which goes on the manager's `uses`: + +```ts +import { projectWorkspace, projectWorkspaceCapability } from "@flow-state-dev/workforce"; + +harnessManager({ + // ... + workspace: localWorkspaceHost({ root, remotes: { allow: ["github.com"] }, source: projectWorkspace({ board: work }) }), + uses: [projectWorkspaceCapability], +}); +``` + The source answers per run, from the block context, and it is asked when a run is first set up. The repository and base branch it named are recorded on the run record (`remote`, `baseRef`). A retry uses the recorded ones, so changing where a source points applies to new rows and never moves a run already under way. A run that started with no repository is recorded as one (`filesOnly`), so it stays on its kept files even if its project gains a repository later. When the run has files kept beside its checkout, the manager saves them at the end of each turn, when the run asks a question, and when the harness fails. The run record's `lastSave` shows the result: the time, any files left alone because someone else changed them too, and an error if the save failed. A failed save does not fail the run, and the next save tries again. The exception is a run that would complete: completing is its last save, so a run whose phase is done but whose files could not be saved fails that attempt instead, and the retry saves them. From 7f923d0420837b89a50beac68271b27971e1c50d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 4 Oct 2026 23:08:38 +0000 Subject: [PATCH 28/28] refactor(workspace): show a repository with redactRemote The lab's withoutCredentials re-parsed a remote the workspace package already redacts. Inbox calls that function. Co-authored-by: Jake Hoffner --- .changeset/export-redact-remote.md | 5 +++++ goals/devforce-lab/lab/host.mts | 17 ++--------------- packages/workspace/src/index.ts | 1 + 3 files changed, 8 insertions(+), 15 deletions(-) create mode 100644 .changeset/export-redact-remote.md diff --git a/.changeset/export-redact-remote.md b/.changeset/export-redact-remote.md new file mode 100644 index 0000000000..0387839ced --- /dev/null +++ b/.changeset/export-redact-remote.md @@ -0,0 +1,5 @@ +--- +"@flow-state-dev/workspace": patch +--- + +`redactRemote` is exported so a caller can show a git remote with its userinfo removed (FIX-1762). diff --git a/goals/devforce-lab/lab/host.mts b/goals/devforce-lab/lab/host.mts index 0a4deda813..ff17cbb623 100644 --- a/goals/devforce-lab/lab/host.mts +++ b/goals/devforce-lab/lab/host.mts @@ -58,7 +58,7 @@ import { import { defineCapability, handler, sequencer } from "@flow-state-dev/core"; import type { BlockContext, FlowInstance } from "@flow-state-dev/core/types"; import type { WorkspaceConfig } from "@flow-state-dev/harness-manager"; -import { localWorkspaceHost, type WorkspaceHost } from "@flow-state-dev/workspace"; +import { localWorkspaceHost, redactRemote, type WorkspaceHost } from "@flow-state-dev/workspace"; import { z } from "zod"; import { AGENT_KIND, @@ -338,7 +338,7 @@ function askRepository(projectOf: (input: z.infer