@dxos/plugin-debug 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/src/samples/stockfish/run.test.ts

@@ -0,0 +1,193 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import { AssistantTestLayer } from '@dxos/agent-runtime/testing';
+import { Provider } from '@dxos/ai';
+import { LanguageModelFixture } from '@dxos/ai/testing';
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { AiContext } from '@dxos/assistant';
+import * as ChatContextSkill from '@dxos/assistant-toolkit/ChatContextSkill';
+import * as SkillManagerSkill from '@dxos/assistant-toolkit/SkillManagerSkill';
+import * as Chat from '@dxos/assistant/Chat';
+import { SpaceProperties } from '@dxos/client-protocol';
+import * as AgentService from '@dxos/compute/AgentService';
+import * as Project from '@dxos/compute/Project';
+import * as Skill from '@dxos/compute/Skill';
+import { Database, Feed, Obj, Query, Ref } from '@dxos/echo';
+import * as EffectEx from '@dxos/effect/EffectEx';
+import { TestHelpers } from '@dxos/effect/testing';
+import { invariant } from '@dxos/invariant';
+import { DXN, EntityId } from '@dxos/keys';
+import * as ProjectOperationHandlerSet from '@dxos/plugin-projects/ProjectOperationHandlerSet';
+import * as ProjectSkill from '@dxos/plugin-projects/ProjectSkill';
+import * as SandboxSkill from '@dxos/plugin-sandbox/SandboxSkill';
+import * as SpaceOperationHandlerSet from '@dxos/plugin-space/SpaceOperationHandlerSet';
+import * as TasksOperationHandlerSet from '@dxos/plugin-tasks/TasksOperationHandlerSet';
+import { Text } from '@dxos/schema';
+import { Message, Task } from '@dxos/types';
+
+import * as StockfishSpace from './StockfishSpace.ts';
+
+/**
+ * The first turn of the chess-MCP template, driven live.
+ *
+ * The template is a plan meant to be RUN, and `sample.test.ts` only asserts the shape it ships in.
+ * This covers the step after that: the space is instantiated, a chat is opened over its project
+ * with the skills the plan names, and a real DeepSeek model is asked to pick the work up. What it
+ * proves is the wiring a first run depends on — the template's instructions and skill reach the
+ * session, the task ledger's verbs resolve, and the model can move the root task off `todo` — none
+ * of which the archive test can see.
+ *
+ * Manual by tag, for two reasons: it spends a real model call, and the sandbox service the later
+ * stages need is unreliable enough that a scheduled run would fail on it rather than on this.
+ * Which is also why it stops here: picking up the root task needs no container.
+ *
+ * Run with, and re-record the conversation with, respectively:
+ *   DX_RUN_MANUAL_TESTS=1 moon run plugin-debug:test -- src/sample/stockfish/run.test.ts
+ *   DX_UPDATE_MODEL_FIXTURES=1 DX_RUN_MANUAL_TESTS=1 DEEPSEEK_API_KEY=... moon run \
+ *     plugin-debug:test -- src/sample/stockfish/run.test.ts
+ */
+
+// Stable entity ids, so the memoized conversation matches across runs: the space's own content is
+// already dated against the template's fixed reference.
+EntityId.dangerouslyDisableRandomness();
+
+/** The model the template's own first step tells the reader to select. */
+const MODEL = DXN.make('com.deepseek.model.deepseek-v4-pro.default');
+
+/**
+ * The skills a chat working this template is expected to carry, beyond the Development skill the
+ * space seeds and binds through its own instructions.
+ *
+ * `SandboxSkill` is here because the plan names it as where the code gets written; its tools only
+ * resolve once a run also registers `plugin-sandbox`'s handlers against a live sandbox service, and
+ * an unresolvable tool is dropped from the session toolkit rather than failing it. The DeepSeek
+ * harness skill is deliberately absent: it drives the coding agent inside the sandbox image, and
+ * the template's instructions forbid delegating this project to it — the harness driving this run
+ * is ours.
+ */
+const EXPECTED_SKILLS = [SkillManagerSkill.make(), ChatContextSkill.make(), ProjectSkill.make(), SandboxSkill.make()];
+
+const template = StockfishSpace.make();
+
+const TestLayer = AssistantTestLayer({
+  // Direct to the vendor rather than through EDGE, which the app routes this model over for auth
+  // and metering: that path needs a HALO identity and an `EdgeHttpClient`, and a headless test
+  // stack has neither. Memoized like any other preset, so a recorded run replays without a key.
+  aiServicePreset: 'deepseek',
+  model: MODEL,
+  provider: Provider.edge.id,
+  // Every verb the bound skills declare, so no tool the model reaches for fails to resolve.
+  operationHandlers: [
+    ProjectOperationHandlerSet.handlers,
+    TasksOperationHandlerSet.handlers,
+    SpaceOperationHandlerSet.handlers,
+    ChatContextSkill.Handlers,
+    SkillManagerSkill.Handlers,
+  ],
+  // The template's own schemas plus what a chat over it persists: `SpaceProperties` carries the
+  // root-collection annotation the sample builder writes.
+  types: [
+    ...template.schemas,
+    SpaceProperties,
+    Chat.Chat,
+    AiContext.Binding,
+    Feed.Feed,
+    Message.Message,
+    Text.Text,
+    Skill.Skill,
+  ],
+  skills: EXPECTED_SKILLS,
+  tracing: 'pretty',
+});
+
+/**
+ * Applies the template to the test database and opens a chat over the project it created, wired the
+ * way a project companion chat is: the project's own instructions (which carry the Development
+ * skill and the brief), and the expected skills bound onto the chat's feed.
+ */
+const instantiateTemplate = Effect.fnUntraced(function* () {
+  const properties = yield* Database.add(Obj.make(SpaceProperties, {}));
+  yield* Database.flush();
+  const { db } = yield* Database.Service;
+  yield* SampleSpace.applyTo(template, { db, properties });
+
+  const [project] = yield* Database.query(Query.type(Project.Project)).run;
+  invariant(project, 'Expected the template to create a project.');
+  invariant(project.instructions, 'Expected the project to carry instructions.');
+  const instructions = yield* Database.load(project.instructions);
+
+  const feed = yield* Database.add(Feed.make());
+  const chat = yield* Database.add(
+    Chat.make({ name: 'Chess MCP on Workers', feed: Ref.make(feed), instructions: Ref.make(instructions) }),
+  );
+  Chat.linkCompanion({ chat, subject: project });
+  Obj.setParent(feed, chat);
+
+  const runtime = yield* Effect.context<Database.Service>();
+  const binder = yield* EffectEx.acquireReleaseResource(() => new AiContext.Binder({ feed, runtime }));
+  yield* Effect.promise(() =>
+    binder.bind({
+      skills: EXPECTED_SKILLS.map((skill) => Ref.make(skill)),
+      objects: [Ref.make(project)],
+    }),
+  );
+  yield* Database.flush();
+
+  return { project, instructions, chat };
+});
+
+/** The one task with no parent: the plan's root. */
+const rootTask = Effect.gen(function* () {
+  const tasks = yield* Database.query(Query.type(Task.Task)).run;
+  const roots = tasks.filter((task) => Task.getParentTask(task) === undefined);
+  invariant(roots.length === 1, `Expected one root task, got ${roots.length}.`);
+  return roots[0];
+});
+
+describe('Chess MCP template, run live', { tags: ['manual'] }, () => {
+  it.effect(
+    'a DeepSeek chat over the instantiated template picks up the root task',
+    Effect.fnUntraced(
+      function* ({ expect }) {
+        const { instructions, chat } = yield* instantiateTemplate();
+
+        // Preconditions, so a failure below is the model's and not the seeding's: the Development
+        // skill reaches the session through the project's instructions (the only binding path), and
+        // the plan has not been started.
+        const bound = new Set<string>();
+        for (const skillRef of instructions.skills) {
+          bound.add(Skill.getKey(yield* Database.load(skillRef)));
+        }
+        expect(bound).toContain('org.dxos.skill.development');
+        const root = yield* rootTask;
+        expect(root.status).toBe('todo');
+
+        const session = yield* AgentService.getSession(chat);
+        yield* session.submitPrompt(
+          'Read the task list for this project, then pick up the work: set the root task to started ' +
+            'and tell me, in one sentence each, what the first stage is and which of its steps are ' +
+            'mine rather than yours. Do not start any stage yet.',
+        );
+        yield* session.waitForCompletion();
+
+        // The observable effect of picking the work up, read off the ledger rather than the reply.
+        expect(root.status).toBe('started');
+        // And nothing below it: the plan's stages are ordered, and a run that starts stage one in
+        // the same turn it reads the list has skipped the reader's two settings steps.
+        const started = (yield* Database.query(Query.type(Task.Task)).run).filter(
+          (task) => Task.getParentTask(task) !== undefined && task.status !== 'todo',
+        );
+        expect(started).toEqual([]);
+      },
+      Effect.provide(TestLayer),
+      TestHelpers.provideTestContext,
+    ),
+    // A live model with a task tree to read takes several tool round-trips; a replay does not.
+    { timeout: LanguageModelFixture.isUpdateEnabled() ? 300_000 : 60_000 },
+  );
+});

package/src/samples/stockfish/skill.ts

@@ -0,0 +1,154 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import * as Skill from '@dxos/compute/Skill';
+import * as Template from '@dxos/compute/Template';
+import { Database } from '@dxos/echo';
+import { Text } from '@dxos/schema';
+import { trim } from '@dxos/util';
+
+//
+// Durable working preferences, seeded as a space object so a project's instructions can bind them.
+//
+// Preferences, not mechanics: how work is tracked, where the code is written, and what counts as
+// evidence. The mechanics of the sandbox (creating one, exec, file transfer) belong to
+// `org.dxos.skill.sandbox` and are cross-referenced rather than restated — two copies of a
+// procedure diverge, and the copy the model reads is the stale one.
+//
+
+const INSTRUCTIONS = trim`
+  How multi-step development work is tracked and carried out here. These hold across a whole
+  session, not one task, so keep this skill enabled for the duration.
+
+  ## Tasks
+  - One task per unit of work, never per batch. A batched task hides which parts landed and which
+    were dropped.
+  - One or two lines per description. Detail belongs in the design document or the README.
+  - Work that ends in someone else's hands gets its own task, titled after the thing to act on and
+    assigned to them — never buried in the task that produced the work.
+  - Use the whole status range. \`blocked\` names what unblocks it; \`cancelled\` names why it was
+    dropped. Deleting a dropped item loses reasoning someone will otherwise re-derive later.
+  - Set status in the same turn the work completes, not in a batch at the end. The task list is how
+    the reader watches this run, so a status set late is a status that was wrong while it mattered.
+  - Respect \`dependsOn\`. A stage assumes the one before it deployed and was verified; starting one
+    early is how a failure gets attributed to the wrong change.
+  - Keep the outline scoped to the task in flight. Findings about another thread belong where that
+    thread lives.
+
+  ## Where the code is written
+  - **You write it.** The sandbox is a shell you drive: you create the files, run the build, and read
+    the failures. Creating a sandbox, running commands in it and moving files in and out are the
+    Sandbox skill's (\`org.dxos.skill.sandbox\`) — enable it rather than working from memory.
+  - **Do not hand the task to the harness in the image.** The sandbox image ships a coding agent of
+    its own, and \`org.dxos.skill.deepseek\` will run it. It is the wrong tool here: it starts with
+    none of this space's context — no brief, no task tree, no design document — and what it produces
+    lands on a container filesystem instead of in this project. Use it only if the reader asks for it
+    by name.
+  - **One sandbox for the whole project.** It keeps its filesystem, its installed toolchain and its
+    checkout between commands. A second one pays for all of that again and splits the tree in two.
+  - **The container is not durable.** Anything that has to survive it — the design, the deploy
+    output, the URLs — is filed as a project artifact in the same turn it is produced, not at the
+    end.
+
+  ## Deploying to Cloudflare
+  - **No account, first deploy.** \`wrangler deploy --temporary\` mints a temporary account and
+    prints a claim URL. The flag is not optional: plain \`wrangler deploy\` refuses in a
+    non-interactive shell and demands a token, and an authentication prompt is a dead end for a
+    session that cannot open a browser.
+  - **The claim URL is a bearer credential; the Worker URL is not.** Anyone holding the claim URL can
+    take ownership of the account, and a project artifact replicates in plaintext to everyone in the
+    space — so file the Worker URL and hand the claim URL straight to the reader, logging it nowhere.
+    Claiming needs a browser, so it is theirs to do; say that it expires with the Worker on it, which
+    invalidates every later stage rather than only the current one.
+  - **Deploy when the Worker changed, and verify every stage regardless.** A design stage has nothing
+    to deploy and a stage that only registers or publishes changes no Worker code — deploying there is
+    a no-op that reads as progress. Where you did deploy, a successful \`wrangler deploy\` is not
+    evidence that anything is serving; the response body is.
+  - **\`--temporary\` needs wrangler 4.102 or later, and that wrangler needs Node 22.** The sandbox
+    runs Node 20, and a plain \`npm install wrangler\` there resolves to the last version that fits
+    it, which has no \`--temporary\`. Install \`wrangler@latest\` explicitly and run its script under
+    a newer node without touching the image: \`npm install wrangler@latest\`, then
+    \`npx --yes node@22 node_modules/wrangler/bin/wrangler.js deploy --temporary\`.
+  - **Read the deploy output for what it warns about, not only its exit code.** Bundle size and a
+    missing binding are warnings on a deploy that succeeds and failures on the request that follows.
+  - **Bound work by work, not by wall-clock.** \`Date.now()\` does not advance during synchronous
+    compute in a Worker, so a time deadline never fires and every timing you report reads as zero.
+    Count iterations, nodes or bytes instead.
+
+  ## Models and credentials
+  - The chat runs DeepSeek V4 Pro through the DXOS edge. No Anthropic key is involved in this
+    project, and nothing here should ask for one.
+  - Bind credentials by REFERENCE with the variable name to read them as. Never paste a secret into
+    a prompt, a message or a shell command — a command line persists in the transcript and in the
+    container's history.
+  - A missing credential is a setup gap, not an error to stop on: name the connector the reader has
+    to connect, then wait. Do not retry in the same turn.
+
+  ## MCP servers
+  - A server is registered as an object in the space, with the transport as \`http\` — Streamable
+    HTTP. \`sse\` is the deprecated transport and is there for servers that have not migrated.
+  - Its key replicates in plaintext to everyone in the space. Register a key the server can rotate,
+    and never one that authorises anything beyond it.
+  - A chat that does not list a registered server's tools has failed to connect. That is a URL,
+    transport or handshake fault to diagnose — not a model that declined to use them.
+  - Prove the tool was actually called. An answer a model could have produced from its own knowledge
+    is not evidence the server is reachable; the tool call in the transcript is.
+
+  ## GitHub and publishing
+  - Publishing comes last, after the thing works. The two consent screens it needs are the only
+    steps that leave this space, and a first run that meets them mid-build stops there.
+  - An agent has no GitHub access of its own. Bind the space's token as \`GH_TOKEN\` before it is
+    needed, not after a 401.
+  - A connector token authorises access to repositories; it cannot CREATE one. Creating the
+    repository is the reader's task and it comes first — the token is then scoped to that repository
+    rather than to everything they own.
+  - Tokens rotate. A session that was pushing fine and now gets 401 or 403 holds a stale copy:
+    refresh the binding rather than restarting the session.
+
+  ## What counts as evidence
+  - Set the bar at execution, not compilation. "It builds" and "it parses" are not evidence: require
+    the thing to be RUN, and say what could not be exercised.
+  - A brief's premise is often wrong; expect it to be falsified. Ask what the real mechanism is
+    before changing the thing that looks like it, and re-ask when the previous answer was itself a
+    correction.
+  - When a measurement is corrected, sweep every conclusion that shared the flawed method. A bad
+    instrument invalidates results already banked; failing to propagate the fix backwards is the
+    expensive mistake.
+  - "Could not run it here" is an environment limit, not a behavioural difference. Only the second is
+    a stop; label the first untested rather than letting it read as a pass.
+  - The sandbox's own state contaminates results: tooling installed earlier makes a capability look
+    available when it is not. Verify a from-scratch claim in a clean container.
+  - A green build is not proof. Assignment and type erasure hide shape mismatches that fail only at
+    runtime — and a Worker's runtime is not node's, so a module that resolves locally can still be
+    missing at the edge.
+  - Distinguish cited from executed evidence. A comment describing a failure is a claim being
+    relayed, not a result; a load-bearing decision deserves a reproduction.
+  - Be terse about the plumbing. Creating a sandbox, installing a toolchain and each command that
+    found nothing are not worth narrating. What the reader wants is the outcome — the URL, the tool
+    response, the failure. Say something mid-flight only when they have to act.
+`;
+
+export type SkillResult = { skill: Skill.Skill };
+
+/** The development-preferences skill, as a space object a project's instructions can bind. */
+export const DevelopmentSkill: SampleSpace.Phase<SkillResult> = SampleSpace.phase('skill', {
+  schemas: [Skill.Skill, Text.Text],
+  run: () =>
+    Effect.gen(function* () {
+      const skill = yield* Database.add(
+        Skill.make({
+          key: 'org.dxos.skill.development',
+          name: 'Development',
+          description: 'How work is tracked, where the code is written, and what counts as evidence.',
+          instructions: Template.make({ source: INSTRUCTIONS }),
+          agentCanEnable: true,
+        }),
+      );
+
+      return { skill };
+    }),
+});

package/src/samples/stockfish/tasks.ts

@@ -0,0 +1,306 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+import { Database, Obj, Ref } from '@dxos/echo';
+import { EntityId } from '@dxos/echo/Key';
+import { Actor, Task, TaskSet } from '@dxos/types';
+
+import { daysAgo } from './util.ts';
+
+//
+// The plan, authored as a tree.
+//
+// The set lists its root tasks and each task lists its own sub-tasks (`Task.subtasks`), at unbounded
+// depth. The seeds are nested the same way, which keeps the shape of the work visible in the source
+// rather than reconstructable only by following refs.
+//
+// Everything is `todo`: this is a plan to run, not a project caught mid-flight. The one thing the
+// seeds do assert is ORDER — a stage assumes the one before it landed, so each depends on its
+// predecessor and a runner that skips ahead is visibly out of order rather than merely early.
+//
+// The ordering constraint that shaped the stages: nothing needing an account outside this space
+// happens until the app already works. Publishing is stage five for exactly that reason — a consent
+// screen in the middle of the build is where a first run stops.
+//
+
+type TaskSeed = {
+  readonly title: string;
+  readonly description?: string;
+  readonly estimate?: Task.Estimate;
+  /** Set where the step needs the reader's own hands — a consent screen, or a repository to own. */
+  readonly assignee?: Actor.Actor;
+  readonly subTasks?: ReadonlyArray<TaskSeed>;
+};
+
+/**
+ * The reader, as an assignee. A template cannot know who they are, so the actor carries the role and
+ * a label rather than a Person ref — enough for the row to say the step is not the agent's.
+ */
+const USER: Actor.Actor = { role: 'user', name: 'You' };
+
+const PLAN: TaskSeed = {
+  title: 'Ship a chess engine as an MCP server on Cloudflare Workers',
+  description:
+    'From the brief to a tool a chat in this space calls. Every stage is verified before the next one starts; the two that change Worker code deploy first.',
+  estimate: 'l',
+  subTasks: [
+    {
+      title: 'Design the tool surface and write it down',
+      description: 'A Markdown artifact on this project, with the diagrams a reviewer reads instead of the code.',
+      estimate: 's',
+      subTasks: [
+        {
+          title: 'Select DeepSeek V4 Pro as the chat model',
+          description:
+            'Yours to do: the model is a Composer setting, not something this space can carry. Assistant settings → model, or the selector in the chat itself. It runs through the DXOS edge, so no Anthropic key is involved anywhere in this project.',
+          estimate: 'xs',
+          assignee: USER,
+        },
+        {
+          title: 'Name the two tools and pin their schemas',
+          description:
+            'Evaluate a position, and name the best move from one. FEN in, and a bounded search budget as an argument — decide the unit and the ceiling now.',
+          estimate: 'xs',
+        },
+        {
+          title: 'Diagram the request path',
+          description:
+            'Chat → MCP client → Worker → engine, as a mermaid flowchart. Name what is bundled and what is fetched.',
+          estimate: 'xs',
+        },
+        {
+          title: 'Decide how the engine gets into the Worker',
+          description:
+            'A WebAssembly build bundled with the Worker, and what that costs against the bundle-size limit. State the fallback if it does not fit.',
+          estimate: 'xs',
+        },
+        {
+          title: 'File the design as a project artifact',
+          description: 'DESIGN.md, added to the project rather than left in the chat.',
+          estimate: 'xs',
+        },
+      ],
+    },
+    {
+      title: 'Deploy an empty Worker with no Cloudflare login',
+      description:
+        'Nothing application-shaped in this stage. The point is a URL that answers before any code exists, and an account claimed while it is cheap to lose. No login to DEPLOY; claiming it afterwards is the one browser step here.',
+      estimate: 'm',
+      subTasks: [
+        {
+          title: 'Create the sandbox and install the toolchain',
+          description:
+            'One sandbox for the whole project — it keeps its filesystem between commands, so a second one pays for node and wrangler again.',
+          estimate: 's',
+        },
+        {
+          title: 'Initialize the project with wrangler',
+          description: 'A TypeScript Worker returning one line of body. Anything more is a later stage.',
+          estimate: 'xs',
+        },
+        {
+          title: 'Deploy without authenticating to Cloudflare',
+          description:
+            '`wrangler deploy --temporary` mints a temporary account and prints a Worker URL and a claim URL; plain `wrangler deploy` refuses non-interactively and demands a token, so the flag is not optional. File the WORKER url on the project. The claim URL is a bearer credential — hand it straight to the reader and file it nowhere.',
+          estimate: 's',
+        },
+        {
+          title: 'Fetch the deployed URL and confirm the body',
+          description:
+            'Fetch it. A successful deploy command is not evidence that anything is serving. Do not claim the account yet — the next stage still redeploys this Worker.',
+          estimate: 'xs',
+        },
+      ],
+    },
+    {
+      title: 'Implement the MCP server and the engine',
+      description: 'The application stage, redeployed and checked over the wire at the end of it.',
+      estimate: 'l',
+      subTasks: [
+        {
+          title: 'Answer the MCP handshake over Streamable HTTP',
+          description:
+            'Initialize and `tools/list` on one endpoint, with the two tools advertised and nothing behind them yet.',
+          estimate: 'm',
+        },
+        {
+          title: 'Bundle the engine and run one search',
+          description:
+            'Prove a search returns inside the budget the design set, from a Worker rather than from node. Bound it by work done, not by wall-clock: `Date.now()` does not advance during synchronous compute in a Worker, so a time deadline never fires there and the call reports zero elapsed.',
+          estimate: 'm',
+        },
+        {
+          title: 'Implement both tools over the engine',
+          description: 'Reject an unparseable FEN as a tool error rather than letting the engine fail on it.',
+          estimate: 'm',
+        },
+        {
+          title: 'Redeploy and call `tools/list` and both tools over the wire',
+          description:
+            'Against the deployed URL, not a local dev server. Paste the responses into the project — that is the stage evidence. This is the last deploy, so claiming comes next.',
+          estimate: 's',
+        },
+        {
+          title: 'Claim the temporary Cloudflare account',
+          description:
+            'Yours to do: claiming signs the account into yours, which needs a browser the agent does not have. It comes AFTER the last redeploy — an agent with no login cannot update a claimed account, and `--temporary` would mint a second one under a different URL. Do it inside the hour; the account expires with the Worker on it.',
+          estimate: 'xs',
+          assignee: USER,
+        },
+      ],
+    },
+    {
+      title: 'Register the server and use it from the chess chat',
+      description: "The brief's definition of done, and the first point at which the thing is worth showing anyone.",
+      estimate: 'm',
+      subTasks: [
+        {
+          title: 'Add the deployed URL as an MCP server in this space',
+          description:
+            'Register the URL as it stands AFTER the claim — a `workers.dev` hostname is account-scoped, so confirm it by fetching before trusting it. Protocol `http` — Streamable HTTP, not the deprecated SSE transport. Its key is stored in plaintext and replicates to everyone in the space, so keep it to one the Worker can rotate.',
+          estimate: 's',
+        },
+        {
+          title: 'Enable the Chess plugin',
+          description:
+            'Yours to do: it is available but off by default, and without it the seeded game has no board to open — the last step of this stage needs one. Settings -> plugin registry.',
+          estimate: 'xs',
+          assignee: USER,
+        },
+        {
+          title: 'Confirm the tools reach the chat',
+          description:
+            'A chat that lists the two tools has connected; one that does not is a transport or URL fault, not a model that chose against them.',
+          estimate: 'xs',
+        },
+        {
+          title: 'Ask for the best move in the seeded game',
+          description:
+            'Open the game and ask. The answer has to arrive as a tool call in the transcript — a plausible move the model knew already is a failure of this step, not a pass.',
+          estimate: 's',
+        },
+      ],
+    },
+    {
+      title: 'Publish it to GitHub',
+      description:
+        'Last on purpose: the two consent screens below are the only steps that leave this space, and putting them here means a first run reaches a working engine before it meets one.',
+      estimate: 'm',
+      subTasks: [
+        {
+          title: 'Create an empty GitHub repository for the server',
+          description:
+            'Yours to do: a connector token authorises access to repositories, it cannot create one. Make it empty — this stage pushes the first commit — and note the owner/name.',
+          estimate: 'xs',
+          assignee: USER,
+        },
+        {
+          title: 'Connect the GitHub credential, scoped to that repository',
+          description:
+            'On the authorisation screen choose "Only select repositories" and pick the one above, with Contents set to read and write. A token scoped to everything is a token the agent did not need.',
+          estimate: 'xs',
+          assignee: USER,
+        },
+        {
+          title: 'Push the tree, with the deploy and MCP steps written down',
+          description:
+            'A README that gets a reader from a clone to a registered MCP server. The wrangler invocation and the URL to register are the two things they cannot guess.',
+          estimate: 's',
+        },
+      ],
+    },
+  ],
+};
+
+export type TasksResult = {
+  taskSet: TaskSet.TaskSet;
+  tasks: Task.Task[];
+  root: Task.Task;
+  /** The five stages, in order — the level the dependency chain is written across. */
+  stages: Task.Task[];
+};
+
+/**
+ * Depth-first flatten, recording each task's children so they can be filed under it once stored.
+ * The stages are collected on the way down, as the root's children.
+ */
+const buildTasks = (
+  seed: TaskSeed,
+): { tasks: Task.Task[]; stages: Task.Task[]; children: Map<Task.Task, Task.Task[]> } => {
+  const tasks: Task.Task[] = [];
+  const stages: Task.Task[] = [];
+  const children = new Map<Task.Task, Task.Task[]>();
+  const visit = (seed: TaskSeed, parent: Task.Task | undefined) => {
+    const task = Task.make({
+      title: seed.title,
+      status: 'todo',
+      description: seed.description,
+      estimate: seed.estimate,
+      assignee: seed.assignee,
+      // Task carries no due date; its dates are activity-log lines, so that is where they go.
+      history: [
+        {
+          id: EntityId.random(),
+          date: daysAgo(0),
+          event: 'created' as const,
+          description: 'Filed from the chess MCP template.',
+        },
+      ],
+    });
+    tasks.push(task);
+    if (parent) {
+      children.set(parent, [...(children.get(parent) ?? []), task]);
+    }
+    if (parent === tasks[0]) {
+      stages.push(task);
+    }
+    for (const child of seed.subTasks ?? []) {
+      visit(child, task);
+    }
+  };
+
+  visit(seed, undefined);
+  return { tasks, stages, children };
+};
+
+/** The plan: one root task, five stages under it, and the steps under those. */
+export const Tasks: SampleSpace.Phase<TasksResult> = SampleSpace.phase('tasks', {
+  schemas: [TaskSet.TaskSet, Task.Task],
+  run: () =>
+    Effect.gen(function* () {
+      const taskSet = yield* Database.add(
+        TaskSet.make({
+          name: 'Chess MCP on Workers',
+          description: 'Everything between the brief and a chat asking the engine for a move.',
+        }),
+      );
+
+      const { tasks, stages, children } = buildTasks(PLAN);
+      yield* SampleSpace.children(taskSet, [tasks[0]], (taskSet, refs) => {
+        taskSet.tasks = refs;
+      });
+      for (const [parent, subtasks] of children) {
+        yield* SampleSpace.children(parent, subtasks, (parent, refs) => {
+          parent.subtasks = refs;
+        });
+      }
+
+      // Each stage depends on the one before it: the stages are sequential by construction (an MCP
+      // server cannot be registered before it has a URL), and stating it is what makes a runner
+      // working out of order visible rather than merely early.
+      for (const [index, stage] of stages.entries()) {
+        if (index > 0) {
+          const previous = stages[index - 1];
+          Obj.update(stage, (stage) => {
+            stage.dependsOn = [Ref.make(previous)];
+          });
+        }
+      }
+
+      return { taskSet, tasks, root: tasks[0], stages };
+    }),
+});

package/src/samples/stockfish/util.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as SampleSpace from '@dxos/app-toolkit/SampleSpace';
+
+/** Stable reference date so regenerations are reproducible. Override with NOW=2026-05-20 env. */
+export const REFERENCE = process.env.NOW ? new Date(process.env.NOW) : new Date('2026-05-20T15:00:00Z');
+
+/**
+ * Bound to the same reference the definition declares, so the pure content builders can date their
+ * objects without every one of them being an effect.
+ */
+export const clock = SampleSpace.makeClock(REFERENCE);
+
+/** ISO timestamp that many days before {@link REFERENCE}, at an optional UTC hour of that day. */
+export const daysAgo = clock.daysAgo;