@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/arc-agi/recipe.js

@@ -1,100 +0,0 @@
-import { z } from "zod";
-import { ARC_GAME_SOUL } from "./soul.js";
-import { ARC_CAPABILITY, arcDelegationGuidance } from "./main-agent.js";
-/** Semantic Subtask type the decomposer emits for a "play this game" request. */
-export const ARC_GAME_TYPE = "arc-game";
-/**
- * Recipe for playing an ARC-AGI-3 game. Names no model, so it runs on whatever
- * pair its host agent is configured with; what distinguishes it is its tool
- * family, its soul, its context discipline, and
- * a turn budget twice the baseline — a play is a long sequence of cheap decisions,
- * and 20 turns bought roughly ten game actions once inspection was paid for.
- *
- * It used to be "the long recipe", budgeted at 1,000 turns on the reasoning that
- * 25 turns per chunk made 40 durable chunks. That arithmetic assumed a turn under
- * ten seconds. A turn here is a reasoning model plus an ARC HTTP round trip, so
- * real runs took 70-100 chunks, blew the per-branch cap, and were *failed* after
- * hours of unattended play rather than being asked to report. The budget is now
- * time and turns, both enforced directly, and a play ends through the graceful
- * summary — a terminal report with the metrics footer.
- *
- * - `historyWindow` bounds context, and it is now the model's *only* memory: the
- *   workspace tools are gone (see below), so a plan that scrolls out of it is
- *   gone. Note it counts *assistant messages* — one per tool call, not one per
- *   game action — so a play spends it several times faster than the number
- *   suggests.
- * - `reportMetrics` appends the turns/model-calls/wall-clock footer the user
- *   asked to see.
- *
- * Tool family: `arc-game` alone (act/inspect against the ARC REST API, session
- * state kept in the workspace), code-validated by
- * `validateRecipe`/`buildRecipeTools`.
- *
- * It used to also carry `workspace`, on the theory that a small history window
- * needs a file store behind it. Two logged plays say otherwise: `ws_read` was
- * never called once, and the three `ws_write` calls between them were a
- * scratchpad for arithmetic — a use that costs a turn per note and now belongs in
- * `arc_act`'s `note` field, which costs none and stays in the model's own history.
- * The session file is unaffected: the family reaches the workspace through its
- * {@link file://../../agent/tools.ts ToolFamilyContext}, not through the tools the
- * model can see.
- */
-export const ARC_GAME_RECIPE = {
-    key: ARC_GAME_TYPE,
-    version: 1,
-    // A recipe states no model, and `ResolvedRecipe` has no field to state one
-    // with. Every recipe runs on the agent's own configured pair, which
-    // `validateRecipe` stamps onto the `ValidatedRecipe` a runner consumes.
-    soul: ARC_GAME_SOUL,
-    toolFamilies: ["arc-game"],
-    enabled: true,
-    // Twice the baseline turns, and the largest number that keeps
-    // `MAX_CHUNKS_PER_BRANCH` unreachable: a yielding chunk always advanced at least
-    // one turn, so a run takes at most `maxTurns` chunks and the cap is 40. Asserted
-    // in `test/agent/subtasks/subtask-types.spec.ts` — raising this past 39 is a
-    // platform change, not a recipe one.
-    //
-    // `maxWallMs` deliberately stays at the 30-minute baseline. Measured turns run
-    // ~15s but reach 165s, so time may well end a play before turn 39 does; both
-    // ceilings end it the same way, through the graceful summary, so the cost of
-    // guessing wrong here is a shorter play rather than lost work.
-    limits: { maxTurns: 39 },
-    // Counts assistant messages (tool calls), so an inspect + act cycle spends two
-    // or three of these per game action; 12 left the model unable to see more than a
-    // couple of moves back, which it answered by re-inspecting.
-    //
-    // Lowered from 32 because `elideToolOutputs` changed what a slot *costs*, not
-    // how many there are: a turn that has aged past the detail window now carries
-    // its reasoning and its `note` but not the board render that was nearly all of
-    // its tokens. 32 was the compensation for losing the workspace tools, and the
-    // thing it was compensating for — reach — is unaffected by the elision.
-    historyWindow: 24,
-    reportMetrics: true
-};
-/**
- * The arc-game type. Its one param is an id the model quotes back from a tool
- * result it already saw, so the contract is checkable before anything runs: a
- * play with no game cannot succeed, and refusing it here costs no model call.
- *
- * There is deliberately no `card_id`. Which scorecard a play runs on is not a
- * choice — the API auto-closes an idle card, so the live card is whichever one
- * was used recently — and the parent leases it per chunk (see
- * {@link file://./scorecard.ts}), handing it to the execution as runtime state.
- */
-export const ARC_GAME_SPEC = {
-    key: ARC_GAME_TYPE,
-    description: "Play one ARC-AGI-3 game.",
-    params: z.object({
-        game_id: z.string().min(1).describe("An exact game id from arc_list_games")
-    }),
-    paramsHelp: "requires param `game_id` (an exact id from `arc_list_games`)",
-    // Everything the main agent is told about ARC is declared here, never written
-    // inside a runtime — see {@link file://./main-agent.ts}. Both blocks live on
-    // the *type* rather than on the plugin, because a plugin that declares a
-    // subtask type has two places it could put a capability block and they are
-    // rendered by different call sites: setting both makes the main agent read the
-    // same advice twice per round, which is the exact drift these fields ended.
-    capability: ARC_CAPABILITY,
-    delegationGuidance: arcDelegationGuidance,
-    recipe: ARC_GAME_RECIPE
-};

package/dist/arc-agi/scorecard.d.ts

@@ -1,118 +0,0 @@
-import type { ArcClient } from "./client.js";
-import type { CookieJar, FrameResponse, Scorecard, ScorecardSummary } from "./types.js";
-/**
- * The `arc-game` recipe's scorecard policy: which card a play runs on, and what
- * that play scored.
- *
- * Neither is a model's decision any more. The ARC API auto-closes a card after
- * ~15 minutes idle, which makes the whole open/close lifecycle the *server's* —
- * so the only judgement left is arithmetic: a card used recently is still alive
- * and every concurrent play should share it; an older one is gone and a new card
- * has to be opened. That is {@link resolveScorecard}, run by the parent once per
- * durable chunk (a subagent facet has no DB, so it cannot own this).
- *
- * Because nothing closes a card, the score is *read* rather than returned:
- * `GET /api/scorecard/{card_id}` works on an open card, and
- * {@link gameScoreReport} appends the finished game's entry to its play's report.
- *
- * Handlers are exported separately from any tool wiring so they unit-test without
- * an LLM, and {@link ScorecardStore} is a narrow interface (`AgentDB.scorecards`
- * satisfies it structurally) so tests can pass an in-memory fake.
- */
-/**
- * How long a card stays reusable. Deliberately a minute short of the API's ~15
- * minute idle auto-close: the clock is bumped per durable chunk, and a chunk is
- * capped at `CHUNK_SOFT_MS` (4 minutes), so the margin only has to cover the gap
- * between two bumps — not a whole play.
- */
-export declare const SCORECARD_REUSE_MS: number;
-/** The slice of `AgentDB.scorecards` the scorecard policy needs. */
-export interface ScorecardStore {
-    findRecent(since: number): Scorecard | null;
-    get(cardId: string): Scorecard | null;
-    open(cardId: string, cookies: CookieJar): Scorecard;
-    setGuid(cardId: string, gameId: string, guid: string): void;
-    touch(cardId: string): void;
-}
-export interface ArcScorecardDeps {
-    store: ScorecardStore;
-    client: ArcClient;
-}
-/** The resolved card a play runs on: its id, and the jar the API pinned to it. */
-export interface ResolvedScorecard {
-    cardId: string;
-    cookies: CookieJar;
-}
-/**
- * Lease a scorecard for a play: reuse the most recently used live card, or open a
- * new one. Either way the card's clock is restarted, so a play that keeps calling
- * this (once per chunk) keeps its own card alive for as long as it runs.
- *
- * `now` is injected so the window is testable at its boundary.
- */
-export declare function resolveScorecard(deps: ArcScorecardDeps, now?: number): Promise<ResolvedScorecard>;
-/** A play a subagent can join: the card, and the ARC session handle on it. */
-export interface ResolvedPlay extends ResolvedScorecard {
-    /** The ARC play handle. Every ACTION is addressed to it. */
-    guid: string;
-    /**
-     * The opening frame — present **only** on the call that minted the guid, and
-     * absent on every later resolution of the same play. There is no ARC endpoint
-     * that reads a board back, so this is the one chance to hand one over; a
-     * subagent that joins later learns the board from its first ACTION instead.
-     */
-    frame?: FrameResponse;
-}
-/**
- * Resolve the play a Subtask runs: the leased card, plus the guid for this game
- * on it — reusing the recorded one, or RESETting **once** to mint it.
- *
- * This is the only RESET in the system. A guid is mintable only by RESET, and a
- * second RESET is a second run on the card: separately scored, with whatever the
- * first play reached left behind. Pinning one guid per (card, game) in the store
- * is what makes a re-dispatched Subtask, a lost workspace, or a later chunk
- * rejoin the play in progress instead of quietly starting another — so a
- * GAME_OVER stays the result this card recorded for this game.
- */
-export declare function resolvePlay(deps: ArcScorecardDeps, gameId: string, now?: number): Promise<ResolvedPlay>;
-/**
- * {@link resolvePlay} on a card the caller has **already** leased.
- *
- * Split out because resolving the card inside is a race the caller may have
- * gone to trouble to avoid: a host that collapses concurrent scorecard leases
- * onto one call (as the plugin does) would have that work bypassed entirely if
- * every play re-resolved its own card. Two plays for *different* games starting
- * together would then each find an empty ledger and each open a card, which is
- * exactly the shared-card behaviour the collapse exists to produce.
- */
-export declare function resolvePlayOn(deps: ArcScorecardDeps, card: ResolvedScorecard, gameId: string): Promise<ResolvedPlay>;
-/**
- * Exactly what a game's report may be built from — deliberately narrower than
- * {@link ScorecardSummary}, which also carries card-wide totals. Narrowing it
- * here makes quoting one of those totals as a game's own result a type error
- * rather than a judgement call, which is the mistake this guards.
- */
-export type GameScoreSource = Pick<ScorecardSummary, "card_id" | "environments">;
-/**
- * What one game scored on a card: its aggregate, then a line per play.
- *
- * Reads **only** the game's own `environments` entry. Every top-level field of
- * the response (`score`, `total_actions`, `total_levels_completed`, …) covers the
- * whole card, and since concurrent plays share a card by design, quoting one as
- * this game's result would be a straightforward mislabeling — verified against
- * the live API, where a card with two games reported both games' actions at the
- * top level.
- */
-export declare function renderGameScore(summary: GameScoreSource, gameId: string): string;
-/**
- * The finished play's score, as a line to append to its report — or null if it
- * cannot be read.
- *
- * Best-effort by contract: this runs *after* a play has already succeeded, so a
- * rate-limited or malformed score response must cost the run nothing. Every
- * failure is logged and swallowed.
- *
- * Reads with the card's stored jar rather than the play's: the play's jar drifted
- * across chunks, while the stored one is the session the API pinned the card to.
- */
-export declare function gameScoreReport(deps: ArcScorecardDeps, cardId: string, gameId: string): Promise<string | null>;

package/dist/arc-agi/scorecard.js

@@ -1,163 +0,0 @@
-import { z } from "zod";
-/**
- * The `arc-game` recipe's scorecard policy: which card a play runs on, and what
- * that play scored.
- *
- * Neither is a model's decision any more. The ARC API auto-closes a card after
- * ~15 minutes idle, which makes the whole open/close lifecycle the *server's* —
- * so the only judgement left is arithmetic: a card used recently is still alive
- * and every concurrent play should share it; an older one is gone and a new card
- * has to be opened. That is {@link resolveScorecard}, run by the parent once per
- * durable chunk (a subagent facet has no DB, so it cannot own this).
- *
- * Because nothing closes a card, the score is *read* rather than returned:
- * `GET /api/scorecard/{card_id}` works on an open card, and
- * {@link gameScoreReport} appends the finished game's entry to its play's report.
- *
- * Handlers are exported separately from any tool wiring so they unit-test without
- * an LLM, and {@link ScorecardStore} is a narrow interface (`AgentDB.scorecards`
- * satisfies it structurally) so tests can pass an in-memory fake.
- */
-/**
- * How long a card stays reusable. Deliberately a minute short of the API's ~15
- * minute idle auto-close: the clock is bumped per durable chunk, and a chunk is
- * capped at `CHUNK_SOFT_MS` (4 minutes), so the margin only has to cover the gap
- * between two bumps — not a whole play.
- */
-export const SCORECARD_REUSE_MS = 14 * 60_000;
-/**
- * Lease a scorecard for a play: reuse the most recently used live card, or open a
- * new one. Either way the card's clock is restarted, so a play that keeps calling
- * this (once per chunk) keeps its own card alive for as long as it runs.
- *
- * `now` is injected so the window is testable at its boundary.
- */
-export async function resolveScorecard(deps, now = Date.now()) {
-    const recent = deps.store.findRecent(now - SCORECARD_REUSE_MS);
-    if (recent) {
-        deps.store.touch(recent.cardId);
-        return { cardId: recent.cardId, cookies: recent.cookies };
-    }
-    const { cardId, cookies } = await deps.client.openScorecard({});
-    deps.store.open(cardId, cookies);
-    return { cardId, cookies };
-}
-/**
- * Resolve the play a Subtask runs: the leased card, plus the guid for this game
- * on it — reusing the recorded one, or RESETting **once** to mint it.
- *
- * This is the only RESET in the system. A guid is mintable only by RESET, and a
- * second RESET is a second run on the card: separately scored, with whatever the
- * first play reached left behind. Pinning one guid per (card, game) in the store
- * is what makes a re-dispatched Subtask, a lost workspace, or a later chunk
- * rejoin the play in progress instead of quietly starting another — so a
- * GAME_OVER stays the result this card recorded for this game.
- */
-export async function resolvePlay(deps, gameId, now = Date.now()) {
-    return resolvePlayOn(deps, await resolveScorecard(deps, now), gameId);
-}
-/**
- * {@link resolvePlay} on a card the caller has **already** leased.
- *
- * Split out because resolving the card inside is a race the caller may have
- * gone to trouble to avoid: a host that collapses concurrent scorecard leases
- * onto one call (as the plugin does) would have that work bypassed entirely if
- * every play re-resolved its own card. Two plays for *different* games starting
- * together would then each find an empty ledger and each open a card, which is
- * exactly the shared-card behaviour the collapse exists to produce.
- */
-export async function resolvePlayOn(deps, card, gameId) {
-    const { cardId, cookies } = card;
-    const recorded = deps.store.get(cardId)?.guids[gameId];
-    if (recorded !== undefined)
-        return { cardId, cookies, guid: recorded };
-    const { frame, cookies: next } = await deps.client.reset({ gameId, cardId }, cookies);
-    deps.store.setGuid(cardId, gameId, frame.guid);
-    // `setGuid` keeps the first guid written, so losing a race to a concurrent
-    // resolution means this RESET opened a play nobody will join. Hand back the
-    // guid that won — and not this frame, which belongs to the abandoned play.
-    const winner = deps.store.get(cardId)?.guids[gameId] ?? frame.guid;
-    return winner === frame.guid
-        ? { cardId, cookies: next, guid: frame.guid, frame }
-        : { cardId, cookies: next, guid: winner };
-}
-/**
- * Loose on purpose: a field the API adds tomorrow must not turn a real result
- * into a parse error. The fields asserted here are the ones
- * {@link renderGameScore} actually renders.
- */
-const runSchema = z.looseObject({
-    guid: z.string(),
-    actions: z.number(),
-    completed: z.boolean(),
-    levels_completed: z.number(),
-    resets: z.number(),
-    score: z.number(),
-    state: z.enum(["NOT_STARTED", "NOT_FINISHED", "WIN", "GAME_OVER"])
-});
-const environmentSchema = z.looseObject({
-    id: z.string(),
-    actions: z.number(),
-    completed: z.boolean(),
-    level_count: z.number(),
-    levels_completed: z.number(),
-    resets: z.number(),
-    score: z.number(),
-    runs: z.array(runSchema)
-});
-const summarySchema = z.looseObject({
-    card_id: z.string(),
-    environments: z.array(environmentSchema)
-});
-/**
- * What one game scored on a card: its aggregate, then a line per play.
- *
- * Reads **only** the game's own `environments` entry. Every top-level field of
- * the response (`score`, `total_actions`, `total_levels_completed`, …) covers the
- * whole card, and since concurrent plays share a card by design, quoting one as
- * this game's result would be a straightforward mislabeling — verified against
- * the live API, where a card with two games reported both games' actions at the
- * top level.
- */
-export function renderGameScore(summary, gameId) {
-    // Match by id rather than taking the sole entry on trust: a mislabeled result
-    // is worse than none.
-    const env = summary.environments.find((e) => e.id === gameId);
-    if (!env || env.runs.length === 0) {
-        return `Scorecard ${summary.card_id} recorded no plays of ${gameId}.`;
-    }
-    const header = `Score for ${gameId} on scorecard ${summary.card_id}: ` +
-        `${env.score} — ${env.levels_completed}/${env.level_count} levels, ` +
-        `${env.actions} actions across ${env.runs.length} play(s)` +
-        (env.completed ? " (completed)" : "") +
-        ".";
-    const plays = env.runs.map((run, index) => `- play ${index + 1}: ${run.state}, ${run.levels_completed} level(s), ` +
-        `${run.actions} actions, score ${run.score}`);
-    return `${header}\n${plays.join("\n")}`;
-}
-/**
- * The finished play's score, as a line to append to its report — or null if it
- * cannot be read.
- *
- * Best-effort by contract: this runs *after* a play has already succeeded, so a
- * rate-limited or malformed score response must cost the run nothing. Every
- * failure is logged and swallowed.
- *
- * Reads with the card's stored jar rather than the play's: the play's jar drifted
- * across chunks, while the stored one is the session the API pinned the card to.
- */
-export async function gameScoreReport(deps, cardId, gameId) {
-    try {
-        const card = deps.store.get(cardId);
-        const { summary } = await deps.client.getScorecard(cardId, card?.cookies ?? {});
-        return renderGameScore(summarySchema.parse(summary), gameId);
-    }
-    catch (err) {
-        console.warn("[arc-game] scorecard read failed", {
-            cardId,
-            gameId,
-            err: String(err)
-        });
-        return null;
-    }
-}

package/dist/arc-agi/soul.d.ts

@@ -1,40 +0,0 @@
-/**
- * The soul (system prompt) for the ARC-AGI-3 game-playing recipe. The domain
- * mechanics (sessions, cookies, frame analysis) live entirely in the `arc-game`
- * tool family; this prompt only tells the model how to play.
- *
- * It plays on a scorecard the parent leased for it. The game is a declared
- * Subtask param and the card is resolved runtime state, so the tools close over
- * both and the model never names, chooses, or copies either id.
- *
- * Three sections here are written against specific, logged failures rather than
- * against a theory of good play, and each says so where it sits:
- *
- * - **Memory** used to be workspace discipline ("write your notes to a file").
- *   Two plays never read a note back, so the notes are gone and what replaces
- *   them is `arc_act`'s `note` field, which costs no turn.
- * - **Finishing** used to ask for the rules "in prose", and got a final report
- *   whose central claim its own last tool result contradicted. It now asks for
- *   provenance: observed, inferred, or untested.
- * - **Inherited knowledge** is new. A play handed a route from an earlier play
- *   executed it faithfully while the board disagreed, because nothing told it
- *   that what it was given was a guess about a level nobody had finished.
- * - **Reading a step's result** used to teach one phrase, `nothing moved`, as the
- *   whole vocabulary of a step that achieved nothing. That is a movement game's
- *   vocabulary: a click game moves nothing ever, and the play that found this out
- *   was told its every click had been "refused or blocked" while each was toggling
- *   a 36-cell block. The registers are now named separately here and rendered
- *   separately in {@link file://./analysis.ts}.
- * - **Where the views stand** was rewritten against measurements. It used to sell
- *   `shapes` as cheap and `grid` as the expensive last resort; three logged plays
- *   answered by calling `region` twelve times and `grid` not once, mapping a maze
- *   through 11×11 peepholes because the one line `shapes` gave them for the wall
- *   was its full-board bounding box. `shapes` now carries the terrain itself, and
- *   the full grid of a real board is 35 collapsed lines — so the ordering here is
- *   `shapes` for the map, `grid` for exact cells, `region` for fine detail only.
- *   The batching section gained the step that follows from it: a route is checked
- *   against those bands before it is sent. That check lives here rather than in
- *   the tool because it is a judgement about the game's rules — what blocks what —
- *   and a tool that made it would be guessing on the model's behalf.
- */
-export declare const ARC_GAME_SOUL: string;

package/dist/arc-agi/soul.js

@@ -1,90 +0,0 @@
-/**
- * The soul (system prompt) for the ARC-AGI-3 game-playing recipe. The domain
- * mechanics (sessions, cookies, frame analysis) live entirely in the `arc-game`
- * tool family; this prompt only tells the model how to play.
- *
- * It plays on a scorecard the parent leased for it. The game is a declared
- * Subtask param and the card is resolved runtime state, so the tools close over
- * both and the model never names, chooses, or copies either id.
- *
- * Three sections here are written against specific, logged failures rather than
- * against a theory of good play, and each says so where it sits:
- *
- * - **Memory** used to be workspace discipline ("write your notes to a file").
- *   Two plays never read a note back, so the notes are gone and what replaces
- *   them is `arc_act`'s `note` field, which costs no turn.
- * - **Finishing** used to ask for the rules "in prose", and got a final report
- *   whose central claim its own last tool result contradicted. It now asks for
- *   provenance: observed, inferred, or untested.
- * - **Inherited knowledge** is new. A play handed a route from an earlier play
- *   executed it faithfully while the board disagreed, because nothing told it
- *   that what it was given was a guess about a level nobody had finished.
- * - **Reading a step's result** used to teach one phrase, `nothing moved`, as the
- *   whole vocabulary of a step that achieved nothing. That is a movement game's
- *   vocabulary: a click game moves nothing ever, and the play that found this out
- *   was told its every click had been "refused or blocked" while each was toggling
- *   a 36-cell block. The registers are now named separately here and rendered
- *   separately in {@link file://./analysis.ts}.
- * - **Where the views stand** was rewritten against measurements. It used to sell
- *   `shapes` as cheap and `grid` as the expensive last resort; three logged plays
- *   answered by calling `region` twelve times and `grid` not once, mapping a maze
- *   through 11×11 peepholes because the one line `shapes` gave them for the wall
- *   was its full-board bounding box. `shapes` now carries the terrain itself, and
- *   the full grid of a real board is 35 collapsed lines — so the ordering here is
- *   `shapes` for the map, `grid` for exact cells, `region` for fine detail only.
- *   The batching section gained the step that follows from it: a route is checked
- *   against those bands before it is sent. That check lives here rather than in
- *   the tool because it is a judgement about the game's rules — what blocks what —
- *   and a tool that made it would be guessing on the model's behalf.
- */
-export const ARC_GAME_SOUL = [
-    "You are playing an ARC-AGI-3 game: a visual-reasoning puzzle on a 64×64 grid of colored cells. You discover the game's hidden rules by acting and observing, and progress through levels toward a win.",
-    "",
-    "# How to play",
-    "1. Your game is already running — there is nothing to start. Which game you play, and on which scorecard, were decided before you began. Start with `arc_inspect` (`shapes` view) to see where everything is, or go straight to `arc_act` if you already know what to try. Either way the reply tells you the current level, the game state, and which actions are legal right now (`available_actions`). If `arc_inspect` says no board has arrived yet, the play was opened before you joined it: your first `arc_act` step is also how the board reaches you, so spend it on a direction you wanted to try anyway rather than on a probe.",
-    "2. Call `arc_act` with the `steps` you want to take, in order. Actions: 1=up, 2=down, 3=left, 4=right, 5=interact/select, 6=click at an (x,y) coordinate (x and y are required for action 6 only), 7=undo.",
-    "3. `arc_act` reports each step separately, in the register that step calls for: which shapes moved, from where to where and how far; which changed color where they stood, appeared, or vanished; `0 cells changed (no effect at all)` when the game refused the action outright; and `nothing moved` when objects stayed put while a counter or a bar ticked, which in a game you steer is a wall. Read `no shape travelled, but the board changed` as what it says — that action did something, and what it did is on the same line. After a batch you also get the net travel per shape, counted in moves rather than cells, and how many steps changed nothing at all. Trust those lines over your own arithmetic: where the report says you are is where you are.",
-    "4. When you need to see the board itself, call `arc_inspect`. `shapes` is your map and the view to reach for: it lists every colored region with the rows and columns it occupies, and for the big sparse ones — walls, floors, frames, anything that is mostly holes — it gives the columns that color occupies in each band of rows, because a bounding box round a maze says nothing. `grid` is the whole board, one character per cell with a legend; it is not the expensive option it sounds like, since bands of identical rows collapse into one line, and it is the right call when you need exact cells. `region` is a labeled close-up around a point — use it to read fine detail, not to map a board a row band at a time. `histogram` is the color counts. Inspecting costs no game action, but it costs a turn out of your budget — and repeating a view of a board that has not changed tells you nothing, so the tool will say so instead of drawing it again. Inspect to answer a question you actually have; otherwise act.",
-    "",
-    "# Colors",
-    "Results name colors rather than numbering them. Some are deliberately close relatives: magenta and magenta-light, blue and blue-light, neutral and neutral-light. Treat those as distinct colors that a game may well use as a pair. `white` is the usual background. In the `grid` view each cell is one character and the legend tells you which color it stands for — the `b` in the grid and the `yellow` in a diff can be the same color.",
-    "A color that spreads thinly over a large area is described by the rows and columns it actually occupies rather than by one box: `too sparse for a box, so by row:` followed by a line per band of rows. Read those lines as the same kind of fact as a box, at the resolution you need to walk through it. The percentage in front of them is how much of that box the color really fills — a low one is your warning that the rest of the box is something else.",
-    "",
-    "# Batching actions",
-    "`steps` accepts up to 8 actions. Batch the whole path you mean to walk — a batch is one turn where eight single steps are eight, and turns are the budget you will actually run out of. What a batch reports back is per step, so you lose no information by sending several at once: you see which of them moved something and which did not.",
-    "- Send ONE step when you are still working out what an action even does, and the result will teach you. Send the whole route once you know the mechanics.",
-    "- A batch runs to the end whatever happens: a step that hits a wall does not stop the ones after it, and each of them still costs an action. So batch a route you have reason to believe in, and read the idle steps and the net travel afterwards to find out where your belief was wrong.",
-    "- Walk the route against the board before you send it. You know where you are and how far one action moves you, so every step of a planned batch lands on a row range and a column range — and the `shapes` view already told you, band by band, which color occupies those rows and columns. Check the destination of each step against that before you commit to it. Nothing will stop you sending a step into a wall, and the walls are not going to be mentioned unless you look them up.",
-    "- A batch does stop early if an action is not available or the play ends; steps it did not send are listed as `not sent`, so trust that list rather than assuming all your steps ran.",
-    "- Every step is a real move, and the game scores you against a human baseline number of actions. Actions spent on a guess that turns out wrong cost you score, whether you spent them one at a time or eight at once.",
-    "",
-    "# Strategy",
-    "- Start by exploring: try single actions and watch what changes, to learn the mechanics before committing to a plan.",
-    "- `available_actions` is the game's own declaration of what is legal — a keyboard-only game will never offer click, however long you wait. Do not spend actions probing for actions it has not offered; work with what it lists.",
-    "- Look for structure: repeated shapes, symmetry, color regions, objects that move or transform when you act. Watch what moves *besides* the thing you are steering — a shape that travels with you, against you, or only when you act is a mechanic, and every moved shape is named in the result.",
-    "- A step that did nothing is a real clue, not a failure: a wall, an edge, or a rule stopped that action. Two `nothing moved` or `0 cells changed` in the same direction means that direction is closed, and a third will be too. But judge that per game: in a game played by clicking, nothing was ever going to travel, so the useful distinction is between clicks that changed the board and clicks that changed not one cell.",
-    "- If `levels_completed` goes up, your approach is working — keep going. If nothing changes across several tries, change tactics.",
-    "- Undo (action 7) is cheap when a move looks like a mistake and undo is available.",
-    "- You get ONE play, and it is the play you were handed — not one you can open. There is no restart: a WIN or a GAME_OVER is final, and it is the result your scorecard records for this game. So treat every action as spent for good — think before you act rather than counting on another attempt, and when the play ends, report what happened instead of trying to undo it.",
-    "",
-    "# The scorecard is not yours",
-    "A scorecard was chosen for you, and you may be sharing it with other games being played right now. You have no tool to open, close, choose, or score a card — do not claim a score, and do not treat reaching WIN or GAME_OVER as something you must clean up. Your game's score is read from the card and appended to your report after you finish.",
-    "",
-    "# What you were told, and what you have seen",
-    "Your task may hand you knowledge from an earlier play: a route, a map, what the colors mean. Treat it as a well-informed guess, not as fact. It came from a play that did not finish this level — that is why you are here — and levels get harder by adding elements nobody has seen yet, so a route that worked before can be wrong in ways whoever wrote it could not know. Check it against your own first result before you spend a batch on it, and when it turns out wrong, say so in your report: that correction is worth more to the next play than the route was.",
-    "Your own results outrank everything else. If the board contradicts what you were told, or contradicts what you worked out three turns ago, the board is right.",
-    "",
-    "# Memory discipline (important)",
-    "You do NOT keep your full history in view — only your most recent turns, and you have no file store: there is nowhere to write a note but into the play itself. Use `arc_act`'s `note` field for that. It costs no turn and no action, it rides along with a move you were making anyway, and it stays in your history where you can read it back. Put in it what you would otherwise forget: the rule you just confirmed, the route you are walking and which step of it you are on, what you have already ruled out.",
-    "You also get your bearings back for free: after any gap in your turns, your next tool result opens by restating where you are — level, state, legal actions, and where every shape sits. So never spend a turn on `arc_inspect` just to re-orient after losing track. Inspect when you want a view you do not have — a close-up, the color counts, the full grid.",
-    "",
-    "# Finishing",
-    "Your work ends when you have nothing useful left to try, or when your budget is exhausted. Your final report is the only thing that survives this play, and the next one will be planned from it — so write it as a handover, in plain text, with these parts:",
-    "- **Outcome**: which game, the final state (report a GAME_OVER plainly — it is a real outcome, not a failure to hide), and how many levels you completed.",
-    '- **Confirmed mechanics**: one line each, with the observation that confirmed it — "`right` moved the orange 5×5 five columns; walls report `nothing moved`". Only things a tool result actually showed you.',
-    "- **Still unknown**: what you suspect but never tested, named as untested. A hypothesis you ran out of turns before checking belongs here, never among the mechanics.",
-    "- **Where things are**: the geography of the level you reached, taken from your most recent view of it and not from memory.",
-    "- **What to try next**, and what not to repeat.",
-    "Two rules for the whole report. Give positions only from your latest view of the board — not from where you believed you were — and if you are stating something you inferred rather than watched happen, say that you inferred it. A confident wrong fact costs the next play more than an admitted gap does.",
-    "Runtime metrics (turns taken, model calls, wall-clock time) and your game's score are appended automatically — do not invent either, and do not report a scorecard score yourself."
-].join("\n");