@dynamicagents/plugins 0.12.0 → 0.14.0

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

@@ -1,211 +0,0 @@
-/**
- * ARC-AGI-3 REST API + session types. The API plays a visual-reasoning game on a
- * 64×64 grid of color values 0–15; see https://docs.arcprize.org.
- *
- * Two lifecycles meet here, and neither belongs to a model:
- *
- * - The **scorecard** is a container that aggregates many plays. The API opens
- *   one on request and auto-closes it after ~15 minutes idle, so nothing here
- *   ever closes one: the parent leases the most recently used card and records it
- *   in its DO SQLite (`db.scorecards`) purely to know how fresh it is.
- * - A **play** is one RESET→ACTION* run inside a scorecard, driven by a subagent.
- *   All state that must survive across durable chunks (cookies, guid, frames,
- *   metrics) lives in the workspace as {@link ArcSession}, written by the tool
- *   family. A subagent is handed a resolved card; it never opens or chooses one.
- */
-/** Game lifecycle state as the API reports it. */
-export type GameState = "NOT_STARTED" | "NOT_FINISHED" | "WIN" | "GAME_OVER";
-/** Base URL of the ARC-AGI-3 API. */
-export declare const ARC_BASE_URL = "https://three.arcprize.org";
-/**
- * One game as `GET /api/games` lists it. Ids look like `ls20-016295f7601e`.
- * `tags` describes how it is played (`click`, `keyboard`, `keyboard_click`) and
- * `baseline_actions` is the per-level human baseline — both are shown to the
- * main agent so it can brief a play sensibly.
- */
-export interface GameInfo {
-    game_id: string;
-    title?: string;
-    tags?: string[];
-    baseline_actions?: number[];
-}
-/** A frame response from RESET / ACTION*. `frame` is one or more 64×64 grids. */
-export interface FrameResponse {
-    game_id: string;
-    guid: string;
-    frame: number[][][];
-    state: GameState;
-    levels_completed: number;
-    win_levels?: number;
-    available_actions: number[];
-    score?: number;
-}
-/** One RESET→terminal run of a game, as the scorecard reports it. */
-export interface ScorecardRun {
-    guid: string;
-    actions: number;
-    completed: boolean;
-    levels_completed: number;
-    resets: number;
-    score: number;
-    state: GameState;
-    /** Actions spent on each level of this run. */
-    level_actions?: number[];
-    /** The human baseline each level is scored against. */
-    level_baseline_actions?: number[];
-    level_scores?: number[];
-}
-/**
- * One game's aggregate within a scorecard — every run played against it.
- *
- * This is the **only** game-scoped part of the response: every top-level field of
- * {@link ScorecardSummary} covers the whole card. Since several games share one
- * card by design, reporting a card-level total as a game's own is a real
- * mislabeling — so the renderer reads nothing but this entry.
- */
-export interface ScorecardEnvironment {
-    id: string;
-    actions: number;
-    completed: boolean;
-    level_count: number;
-    levels_completed: number;
-    resets: number;
-    score: number;
-    runs: ScorecardRun[];
-}
-/** Per-tag rollup (`click`, `keyboard`, …) across the scorecard's games. */
-export interface ScorecardTagScore {
-    id: string;
-    actions: number;
-    levels_completed: number;
-    number_of_environments: number;
-    number_of_levels: number;
-    score: number;
-}
-/**
- * A whole scorecard as `GET /api/scorecard/{card_id}` reports it: one
- * `environments` entry per game played, one `runs` entry per RESET within it.
- *
- * This is a **read**, not a terminal event — it works while the card is still
- * open, which is what lets a result be reported without anything ever closing a
- * card. (It is the same shape the retired close call returned, which is why it
- * carries a real per-game `score`.)
- *
- * The narrower `GET /api/scorecard/{card_id}/{game_id}` is deliberately *not*
- * used: it reports no score at all, and its top-level totals are card-wide
- * despite the game filter — verified against the live API.
- */
-export interface ScorecardSummary {
-    card_id: string;
-    score: number;
-    total_actions: number;
-    total_environments: number;
-    total_environments_completed: number;
-    total_levels: number;
-    total_levels_completed: number;
-    environments: ScorecardEnvironment[];
-    tags?: string[];
-    tags_scores?: ScorecardTagScore[];
-}
-/**
- * One scorecard as the agent's DO SQLite records it (see `db/schema.ts`).
- *
- * There is no status: the API auto-closes an idle card, so liveness is inferred
- * from {@link lastUsedAt} rather than tracked. A card is a lease, not an object
- * with a lifecycle.
- */
-export interface Scorecard {
-    cardId: string;
-    /**
-     * The jar `POST /api/scorecard/open` returned. The API pins the card to that
-     * session — every later RESET, ACTION, and scorecard read must echo these
-     * cookies, from whichever agent makes the call — so it is stored with the card,
-     * not held by whoever happened to open it.
-     */
-    cookies: CookieJar;
-    /**
-     * `{ [gameId]: guid }` — the play this card has already opened per game, so a
-     * game resolving onto it a second time rejoins that play instead of RESETting
-     * a new one. See `resolvePlay` in `recipes/arc-game/scorecard.ts`.
-     */
-    guids: Record<string, string>;
-    openedAt: number;
-    /** Last time a play resolved onto this card; the reuse clock. */
-    lastUsedAt: number;
-}
-/** Session-affinity cookie jar (AWSALB*), echoed on every request of a session. */
-export type CookieJar = Record<string, string>;
-/**
- * Durable play session, persisted to the workspace at {@link ARC_SESSION_PATH}.
- * The single grid we render/diff is the LAST grid of the frame array (the current
- * board).
- *
- * One session file is one play, and one execution gets exactly one: the RESET
- * that creates this file is implicit and fires once, so reaching WIN or GAME_OVER
- * is a terminal result to report on this card, not a state the model can reset
- * out of. Its presence on disk is what makes that guarantee — every later tool
- * call loads it instead of starting.
- */
-export interface ArcSession {
-    /**
-     * The scorecard this play belongs to, recorded from the lease the parent
-     * resolved at the opening RESET. Kept rather than re-read each chunk: if the
-     * lease rolls over onto a new card mid-execution, this play's runs still belong
-     * to the card that recorded them.
-     */
-    cardId: string;
-    gameId: string;
-    guid: string;
-    cookies: CookieJar;
-    winLevels: number;
-    levelsCompleted: number;
-    state: GameState;
-    availableActions: number[];
-    /** Count of actions actually sent to the API (game moves) in this play. */
-    actionsSent: number;
-    /** Levels at which we have emitted a level-up progress note. */
-    levelsReported: number[];
-    /**
-     * The current board as bare hex rows (`serializeGrid`), not `number[][]`.
-     *
-     * The workspace pretty-prints its JSON, so a nested numeric array serializes to
-     * one integer per line — ~38 KB for a 64×64 board. Since the session is written
-     * twice per action (write-ahead intent, then the recorded result) and one
-     * `arc_act` call may carry several actions, that adds up to hundreds of KB of
-     * SQLite per tool call. Hex rows are ~4 KB.
-     */
-    lastGridHex: string | null;
-    /** Write-ahead intent: set before an action is sent, cleared after it returns. */
-    pendingAction: {
-        action: number;
-        x?: number;
-        y?: number;
-    } | null;
-}
-/** Workspace path for the durable ARC session. */
-export declare const ARC_SESSION_PATH = "arc/session.json";
-/**
- * This plugin's slice of a Subtask's runtime bag — what the parent resolves for
- * an execution and no model could supply.
- *
- * Core's `SubtaskRuntime` is an open `Record<string, unknown>`, and this slice is
- * why: declared in core's own delegation types instead, core would import a
- * domain's vocabulary and every unrelated agent would carry it in its bundle.
- * The plugin that writes this slice is the plugin that reads it, so narrow it
- * with `runtimeAs<ArcRuntime>` at the boundary and keep the cast's blast radius
- * to this one module.
- */
-export type ArcRuntime = {
-    /** The scorecard leased for this chunk. */
-    cardId?: string;
-    /** The session jar the ARC API pinned that card to. */
-    cookies?: CookieJar;
-    /** The play to join. Mintable only by RESET, which only the parent performs. */
-    guid?: string;
-    /**
-     * The opening frame — present **only** on the chunk that minted the guid.
-     * There is no ARC endpoint that reads a board back, so this is the one chance
-     * to hand one over; a later chunk learns the board from its first ACTION.
-     */
-    frame?: FrameResponse;
-};

package/dist/arc-agi/types.js

@@ -1,19 +0,0 @@
-/**
- * ARC-AGI-3 REST API + session types. The API plays a visual-reasoning game on a
- * 64×64 grid of color values 0–15; see https://docs.arcprize.org.
- *
- * Two lifecycles meet here, and neither belongs to a model:
- *
- * - The **scorecard** is a container that aggregates many plays. The API opens
- *   one on request and auto-closes it after ~15 minutes idle, so nothing here
- *   ever closes one: the parent leases the most recently used card and records it
- *   in its DO SQLite (`db.scorecards`) purely to know how fresh it is.
- * - A **play** is one RESET→ACTION* run inside a scorecard, driven by a subagent.
- *   All state that must survive across durable chunks (cookies, guid, frames,
- *   metrics) lives in the workspace as {@link ArcSession}, written by the tool
- *   family. A subagent is handed a resolved card; it never opens or chooses one.
- */
-/** Base URL of the ARC-AGI-3 API. */
-export const ARC_BASE_URL = "https://three.arcprize.org";
-/** Workspace path for the durable ARC session. */
-export const ARC_SESSION_PATH = "arc/session.json";

package/dist/claude-code/recipe.d.ts

@@ -1,53 +0,0 @@
-import type { ResolvedRecipe, SubtaskTypeSpec } from "@dynamicagents/core";
-/** The Subtask type a "make this change" request decomposes into. */
-export declare const CLAUDE_CODE_TYPE = "claude-code";
-/**
- * The key this plugin writes the workspace name under, for the facet to read
- * back off `SubtaskRuntime`.
- *
- * **Deliberately a second declaration of `/computer`'s `WORKSPACE_RUNTIME_KEY`,
- * not an import of it.** Importing one string constant across the subpath
- * boundary would merge two realms `verify:exports` keeps apart, and pull the
- * whole computer plugin into the graph of every agent that installs this one.
- *
- * The two must stay equal, because a host that installs both on its subagent
- * gets them working off one runtime value — so `index.spec.ts` imports both and
- * asserts it, which is where a cross-realm import costs nothing.
- */
-export declare const WORKSPACE_RUNTIME_KEY = "workspaceName";
-/**
- * The recipe a Claude Code session runs under — and most of it is inert, which
- * is worth saying plainly rather than letting a reader assume otherwise.
- *
- * Every other recipe in this package configures core's resumable model/tool
- * loop: `soul` is the system prompt, `toolFamilies` names what the model may
- * call, `historyWindow` bounds its context. **None of that applies here.** The
- * host's subagent overrides `executeChunk` and never calls `runResumableChunk`
- * at all — the loop, the tools, the context management and the system prompt are
- * Claude Code's, inside the container.
- *
- * So the fields below exist because {@link ResolvedRecipe} requires them and
- * `validateRecipe` checks them on the parent, not because anything reads them at
- * runtime. They are set to the most honest values available:
- *
- * - `toolFamilies: []` — this plugin registers none. Claude Code brings its own
- *   tools and they are not core's to name.
- * - `soul` — required and never defaulted, so it says what this recipe *is*.
- *   Nothing sends it to a model.
- * - `limits.maxTurns` — the budget core would meter if it were driving. It is
- *   not, so what actually bounds a session is `timeoutMs`, enforced by the
- *   container runtime. Set to 1 to say so: one Dynamic Agents "turn" is one
- *   whole Claude Code session.
- */
-export declare const CLAUDE_CODE_RECIPE: ResolvedRecipe;
-/**
- * What the main agent is told it can hand off.
- *
- * Sized deliberately. An invocation carries an 18.7-27k token cached prefix
- * before it does anything — a ten-call burst billed twenty raw input tokens
- * against 187,130 cache reads — so a session has to be worth starting. The
- * guidance says that in the terms the delegating model can act on: one coherent
- * change, not one file edit.
- */
-export declare const CLAUDE_CODE_CAPABILITY: string;
-export declare const CLAUDE_CODE_SPEC: SubtaskTypeSpec;

package/dist/claude-code/recipe.js

@@ -1,100 +0,0 @@
-/** The Subtask type a "make this change" request decomposes into. */
-export const CLAUDE_CODE_TYPE = "claude-code";
-/**
- * The key this plugin writes the workspace name under, for the facet to read
- * back off `SubtaskRuntime`.
- *
- * **Deliberately a second declaration of `/computer`'s `WORKSPACE_RUNTIME_KEY`,
- * not an import of it.** Importing one string constant across the subpath
- * boundary would merge two realms `verify:exports` keeps apart, and pull the
- * whole computer plugin into the graph of every agent that installs this one.
- *
- * The two must stay equal, because a host that installs both on its subagent
- * gets them working off one runtime value — so `index.spec.ts` imports both and
- * asserts it, which is where a cross-realm import costs nothing.
- */
-export const WORKSPACE_RUNTIME_KEY = "workspaceName";
-/**
- * The recipe a Claude Code session runs under — and most of it is inert, which
- * is worth saying plainly rather than letting a reader assume otherwise.
- *
- * Every other recipe in this package configures core's resumable model/tool
- * loop: `soul` is the system prompt, `toolFamilies` names what the model may
- * call, `historyWindow` bounds its context. **None of that applies here.** The
- * host's subagent overrides `executeChunk` and never calls `runResumableChunk`
- * at all — the loop, the tools, the context management and the system prompt are
- * Claude Code's, inside the container.
- *
- * So the fields below exist because {@link ResolvedRecipe} requires them and
- * `validateRecipe` checks them on the parent, not because anything reads them at
- * runtime. They are set to the most honest values available:
- *
- * - `toolFamilies: []` — this plugin registers none. Claude Code brings its own
- *   tools and they are not core's to name.
- * - `soul` — required and never defaulted, so it says what this recipe *is*.
- *   Nothing sends it to a model.
- * - `limits.maxTurns` — the budget core would meter if it were driving. It is
- *   not, so what actually bounds a session is `timeoutMs`, enforced by the
- *   container runtime. Set to 1 to say so: one Dynamic Agents "turn" is one
- *   whole Claude Code session.
- */
-export const CLAUDE_CODE_RECIPE = {
-    key: CLAUDE_CODE_TYPE,
-    version: 1,
-    soul: [
-        "This recipe does not drive a model loop.",
-        "",
-        "A subtask of this type runs the Claude Code CLI inside the agent's",
-        "workspace container, against the durable working tree. The system prompt, the",
-        "tool loop and the context management all belong to that process. Nothing",
-        "reads this text — it exists because a recipe must declare a soul, and a",
-        "placeholder that looked like a prompt would invite someone to tune it."
-    ].join("\n"),
-    toolFamilies: [],
-    enabled: true,
-    limits: { maxTurns: 1 },
-    historyWindow: 1,
-    reportMetrics: false
-};
-/**
- * What the main agent is told it can hand off.
- *
- * Sized deliberately. An invocation carries an 18.7-27k token cached prefix
- * before it does anything — a ten-call burst billed twenty raw input tokens
- * against 187,130 cache reads — so a session has to be worth starting. The
- * guidance says that in the terms the delegating model can act on: one coherent
- * change, not one file edit.
- */
-export const CLAUDE_CODE_CAPABILITY = [
-    "## Writing code",
-    "",
-    "You can hand a coding task to a Claude Code session running in your",
-    "workspace container, in whatever you have open there — a repository you",
-    "checked out, or a scratchpad. It has its own tools — it reads, edits, runs the",
-    "test suite and iterates — and it reports back what it did.",
-    "",
-    "Give it **one coherent change**, described the way you would describe it to",
-    "an engineer: what should be true when it is done, and how to tell. It is",
-    "expensive to start and cheap to let run, so 'add the endpoint, its tests and",
-    "wire it up' is one subtask, not three. A session that is only asked to edit",
-    "a single line costs about what a substantial one costs.",
-    "",
-    "It cannot ask you anything mid-run. Anything it would need to ask, decide",
-    "first — or ask the user yourself before delegating."
-].join("\n");
-export const CLAUDE_CODE_SPEC = {
-    key: CLAUDE_CODE_TYPE,
-    description: "Run a coding task in the workspace with a Claude Code session — a checked-out repository, or a scratchpad.",
-    /**
-     * No params, and that is a decision rather than an omission.
-     *
-     * *Which* repository is not the delegating model's to choose: the workspace is
-     * one Durable Object, one container and one checkout, keyed by caller and
-     * repository, and the parent already tracks which one is active. Letting a
-     * model name a repository here would let it name somebody else's — the same
-     * reasoning that keeps `workspaceName` out of model input in `/computer`.
-     */
-    params: null,
-    capability: CLAUDE_CODE_CAPABILITY,
-    recipe: CLAUDE_CODE_RECIPE
-};

package/dist/computer/read.d.ts

@@ -1,133 +0,0 @@
-import type { WorkspaceClient } from "@cloudflare/computer";
-/**
- * Reading the workspace without pulling more of it across the boundary than the
- * model will be shown.
- *
- * The obvious version of each function here reads everything and throws most of
- * it away, which is the wrong shape against a Durable Object's 128 MB. So the
- * budget is applied at the source, and the offsets handed back are the *source's*
- * rather than the rendered subset's — which is what makes the next page exact
- * instead of a guess.
- */
-/**
- * Read a file without pulling more of it across the boundary than the model will
- * be shown.
- *
- * `readFile(path, "utf8")` materialises the whole file in the isolate before
- * `truncateOutput` throws most of it away. Harmless on a source file, and the
- * wrong shape against a Durable Object's 128 MB — `sb_read` is one model decision
- * away from a lockfile, a bundle or a captured build log. The read is
- * range-addressable, so the budget is enforced at the source.
- *
- * Two reads rather than one, because the budget is spent from both ends for the
- * reason {@link truncateOutput} documents — the first error is at the top of a
- * file and the summary is at the bottom.
- *
- * ## The one place the budget is spent in bytes
- *
- * `maxChars` is a character ceiling everywhere else — see
- * {@link ComputerConfig.maxOutputChars} — and here it is spent against
- * `byteOffset`/`byteLength`, which are the only units the transport has, and the
- * only ones that bound what crosses it. Safe in the direction that matters: a
- * UTF-8 byte is never more than one UTF-16 code unit, so *N* bytes decode to at
- * most *N* characters. Reading the character budget as bytes therefore always
- * honours the ceiling, and errs low on a file that is mostly non-ASCII — a CJK
- * source file is cut at about a third of the characters it could have shown. The
- * alternative is a second round trip on every read, to recover a bound the
- * marker already announces.
- *
- * ## Why `stat` first
- *
- * Sizing off the returned string instead would be wrong in a way that hides
- * itself. `byteLength` counts bytes and `String.length` counts UTF-16 code units,
- * so a file of two-byte characters comes back *under* a character budget while
- * still being over the byte budget — and the read would look complete with half
- * the file missing and no marker saying so. One extra round trip buys the
- * distinction.
- *
- * A slice boundary can land mid-codepoint, which the decoder resolves to a single
- * replacement character. That is one glyph of noise at a cut that already
- * announces itself as a cut.
- */
-export declare function readBounded(fs: WorkspaceClient["fs"], path: string, maxChars: number): Promise<string>;
-/**
- * A byte window the model asked for, with its coordinates stated.
- *
- * No middle-out here, deliberately: {@link readBounded} guesses at what matters when
- * nobody said, but an explicit `offset` *is* the model saying. Trimming the middle
- * of a region it chose would defeat the request and, worse, make the next offset
- * unknowable.
- *
- * The window line is what makes paging work at all — the model needs to know where
- * it landed and how much is left to compute the next `offset`.
- */
-export declare function readWindow(fs: WorkspaceClient["fs"], path: string, offset: number, length: number, maxChars: number): Promise<string>;
-/**
- * Fetch a page, drop what is off-limits, and keep the source offsets that make the
- * *next* page exact.
- *
- * The subtle part is why `rawIndex` exists at all. `offset` counts items at the
- * source; the caller renders a filtered, budget-trimmed subset of them. So the
- * obvious `nextOffset = offset + shown` is wrong — it silently skips or repeats
- * whenever anything was dropped, which is precisely when a skipped directory is
- * involved. Keeping each survivor's source index means the next page starts exactly
- * after the last one the model actually saw.
- *
- * Retries because a skipped directory can outnumber a whole page on its own — a
- * dependency tree runs to tens of thousands of files — so one fetch can come back
- * entirely excluded. `maxRounds` is the caller's: a retry re-reads and re-scans
- * every file the last one looked at. For a walk the store can prune instead, see
- * `sb_ls`, which passes exclusions to `find` and needs none of this.
- *
- * Deliberately no slicing to `want`: the caller needs the extra item to know a next
- * page exists, and its index to say where.
- */
-export declare function collectVisible<T>(fetch: (offset: number, limit: number) => Promise<T[]>, pathOf: (item: T) => string, skip: (path: string) => boolean, want: number, offset: number, maxRounds: number): Promise<{
-    items: T[];
-    /** Source offset of `items[i]`. */
-    rawIndex: number[];
-    /** Source offset just past everything examined. */
-    rawEnd: number;
-    /** The source ran out; there is no next page. */
-    exhausted: boolean;
-    /** Rounds ran out while excluded paths still dominated. */
-    crowded: boolean;
-}>;
-/** What a page of a collected listing owes the caller once it knows how much fit. */
-interface VisiblePage {
-    rawIndex: number[];
-    rawEnd: number;
-    exhausted: boolean;
-    crowded: boolean;
-}
-/**
- * The "there is more, here is where" line, with an offset that is actually correct.
- *
- * `rawIndex[shown]` rather than `offset + shown`: the first item the model did *not*
- * see, at its source coordinate. Anything else drifts by however many entries the
- * skip filter removed, and drifts silently — the next page would repeat or skip
- * with nothing to indicate it had.
- *
- * Narrowing is still offered, and still first-class, because it is cheaper than
- * paging: `offset` does not skip the walk, it only discards its early results. It is
- * offered as the better option rather than the only one, which is the thing the
- * previous wording got wrong — "narrow it" is no answer at all when the model wants
- * the next page of a list it is working through.
- */
-export declare function listingNote(page: VisiblePage, shown: number, noun: string, narrower: string): string;
-/**
- * Does this path exist?
- *
- * `getWorkspace()` types `fs` as the in-process `WorkspaceFilesystem`, but the
- * value on the far side of a Durable Object boundary is a
- * `WorkspaceFilesystemStub`, which carries a few methods the local class does
- * not — `exists` among them. So the fast path is asked for rather than cast to,
- * and `stat` is the fallback for a host that hands back a local workspace.
- *
- * The fallback treats *any* `stat` failure as absence, which is the honest
- * reading for a tool whose entire answer is a boolean: there is no error channel
- * to distinguish "missing" from "unreadable", and the caller's next move — look
- * somewhere else — is the same either way.
- */
-export declare function pathExists(fs: WorkspaceClient["fs"], path: string): Promise<boolean>;
-export {};