@crowdedkingdoms/crowdyjs 11.1.0 → 12.0.0

package/MIGRATION.md

@@ -1,3 +1,110 @@
+# CrowdyJS v12 — Agentic Crowdy Studio contract (BREAKING)
+
+Version 12 establishes the greenfield public contracts
+`crowdy.studio-agent/1`, `crowdy.agent-tools/1`, and
+`crowdy.player-host/1`. The major bump reserves their authority, event,
+descriptor, and browser-control semantics before rollout; changing those
+semantics later requires another major contract version.
+
+New package subpaths:
+
+- `@crowdedkingdoms/crowdyjs/agent` — immutable descriptor registry, bounded
+  JSON-schema validator, stable errors, injectable durable transport,
+  ordered/reconnecting session controller, exact approvals, and execute-once
+  browser dispatch.
+- `@crowdedkingdoms/crowdyjs/player-host` — generic host capability,
+  observation, command, and result contracts plus the revocable Play lease
+  manager/gate.
+- `@crowdedkingdoms/crowdyjs/crowdy-studio` re-exports both surfaces and adds
+  the integrated Ask/Build/Play dock.
+
+The reconciled Game API SDL and generated agent operations are now committed.
+`client.crowdyStudioAgent` is a production `CrowdyAgentGraphQLTransport`
+implementing every `CrowdyStudioAgentTransportV1` query, Relay connection,
+mutation, heartbeat, and typed event subscription. Tests and non-GraphQL hosts
+may still inject the interface; do not add a generic raw-GraphQL callback.
+
+Creation now carries optional `providerDataConsent`; attach carries a stable
+`clientInstanceId` and consumes `replayAfterSeq`; the public transport
+`message` maps to Game API `content`; cancellation requires the exact run id;
+and nested browser results map to `AgentToolResultEnvelopeInput`. PLAY sends a
+two-second heartbeat only while attached, active, and visible, stopping and
+clearing local authority on pause, disconnect, stale epoch, kill, or destroy.
+Descriptor builds verify the full registry and canonical 28-tool Game API
+follow-up subset (14 mandatory game plus 14 Studio/diagnostic/runtime tools)
+against the copied digest fixture.
+
+Mode changes now consume the server-repinned registry/policy/context fields.
+BUILD mounts derive `projectId` from the selected saved Studio project after
+initialization; callers should no longer guess it. An existing session for a
+different project fails closed, and project switches require a new session
+until Game API adds an explicit set-project mutation.
+
+BUILD workspace leases renew every ten seconds through agent heartbeat and
+stop on human edit, project/context change, revocation, disconnect, or destroy.
+Backend-advertised draft/live/stop/invoke tools execute through the headless
+Studio controller, with exact approval for live work. Run events now preserve
+typed code/error details, aborted handlers clear local intent, and inner
+`OUTCOME_UNKNOWN` can no longer be wrapped as outer success.
+
+Runtime draft/live calls now require an exact full-project target plan. Live
+execution also binds the post-autosave revision, content/module hash, and
+pairing preference; mismatches fail before any compile/deploy. Invoke verifies
+the running DRAFT/LIVE environment and export, while stop remains an
+all-project safety action.
+
+Existing manual mounts continue to work:
+
+```ts
+await mountCrowdyStudio(host, existingOptions);
+```
+
+To enable the agent dock, inject the transport and either an existing session
+or create-session input:
+
+```ts
+await mountCrowdyStudio(host, {
+  ...existingOptions,
+  agent: {
+    transport: game.crowdyStudioAgent,
+    sessionId,
+    playerHost, // optional; required for generic Play tools
+  },
+});
+```
+
+`CrowdyStudioHandle` now exposes `agent` and `controlLeaseManager` (both `null`
+when agent mode is not configured). `CrowdyStudioController.testDraft()` and
+`deployLive()` now resolve typed `CrowdyStudioDeployResult` values; code that
+ignored their previous `void` result remains valid.
+
+Headless integrations should adopt:
+
+- `prepareForAgentWork()` before sending a turn;
+- `applyAtomicPatch()` / `synchronizeProject()` for complete revision-fenced
+  project updates;
+- `CrowdyStudioSynchronizationProvider` for durable checkpoint list, atomic
+  patch, and approved restore hooks;
+- `state.runtimeSync` instead of inferring saved-versus-running status from the
+  display phase.
+
+Game integrations implement `PlayerHostAdapterV1`, route commands through the
+same intent services as human input, and call
+`AgentControlLeaseManager.preempt(reason)` synchronously on human input,
+Escape, Stop, death, disconnect, or context/target changes. Do not adapt the
+agent through DOM events, raw UDP/GraphQL/CrowdyJS methods,
+`PlayerCodeBroker`, or client-mod `host_call`.
+
+The current Game API pilot advertises its canonical 28-tool follow-up subset,
+including all 14 mandatory game tools. CrowdyJS dispatches the game tools
+through `PlayerHostAdapterV1`;
+BWF Play still requires the concrete BWF adapter/shared-intent integration and
+matching host/app policy.
+
+The browser package contains no provider client or key. Provider routing,
+policy, budgets, durable approvals, and server tools remain Game API
+responsibilities.
+
 # CrowdyJS v11.1 — responsive Crowdy Studio embedding
 
 Crowdy Studio now sizes to its host instead of imposing a 680-pixel minimum

package/README.md

@@ -12,6 +12,21 @@ npm install @crowdedkingdoms/crowdyjs
 
 CrowdyJS v4 targets browsers by default and uses native `fetch`, `WebSocket`, `crypto`, `btoa`, and `atob`. Node tools can still use the SDK, but must provide browser-compatible globals when opening realtime connections.
 
+> **CrowdyJS v12 (breaking): Agentic Crowdy Studio.** v12 adds the accepted
+> `crowdy.studio-agent/1`, `crowdy.agent-tools/1`, and
+> `crowdy.player-host/1` browser contracts. Import the provider-neutral durable
+> client and immutable tool registry from
+> `@crowdedkingdoms/crowdyjs/agent`, and generic game observations/control from
+> `@crowdedkingdoms/crowdyjs/player-host`. Crowdy Studio can mount the
+> integrated Ask/Build/Play dock when given an injectable agent transport.
+> There is deliberately no OpenRouter key/client, raw GraphQL executor, DOM
+> driver, `fetch`, shell, unrestricted SDK bridge, or client-mod `host_call` in
+> these surfaces. The reconciled Game API SDL, generated operations, and
+> production `CrowdyAgentGraphQLTransport` are included and exposed as
+> `client.crowdyStudioAgent`; tests may still inject
+> `CrowdyStudioAgentTransportV1`. Existing manual Studio mounting remains
+> unchanged when `agent` is omitted.
+>
 > **Server compatibility (v8.13):** v8.13 adds the **flow-correlation surface**: `gameModel.flow({ appId, flowId })` stitches one flow correlation id into a single cross-engine timeline (model events + automation runs + compute module runs, each time-ascending), and the default event/run fragments now select the nullable `flowId` field on `GmEvent` / `GmAutomationRun` / `WasmModuleRun`. Both require the 2026-07-19 `cks-game-api` dev line (the `2026-07-19-compute-fleet-hardening` migration for the columns and the `gameModelFlow` query for the timeline); older servers reject the operations with a GraphQL validation error, and everything else keeps working. `gameModel.flow` requires the app-admin `manage_apps` permission (it is a diagnostics surface). v8.13 also extends the kit invoke helpers' gameplay-verdict mapping: the typed invoke-contract violation `computeInvoke` raises (`BAD_REQUEST` with an "Invoke params violate ..." message, game-api 2026-07-19+) now maps onto `{ success: false, errorMessage }` (`kitInvoke`) / `{ success: false, reason }` (engine invokes) instead of throwing — see the exported `isKitVerdictError` predicate.
 >
 > **Server compatibility:** v8.12's **container query predicates** (`where`/`limit`/`offset` on `gameModel.containers`), **automation compute actions** (`actionKind: 'compute_invoke'` with `computeModuleName`/`computeExport` on `gameModel.upsertAutomation`; `property_changed` events additionally carry `oldValue`/`newValue` to compute modules), **container-change push** (`gameModel.containerChanged` — metadata-only pull-on-push over graphql-transport-ws; on Node ≤ 21 pass `webSocketImpl`), and **invoke-trigger contracts** (`contractJson` on `compute.upsertTrigger`/`moduleTriggers`, validated server-side pre-sandbox) require the 2026-07 `cks-game-api` dev line with the `2026-07-19-automation-compute-action` migration; older servers reject the new arguments/fields (omit them and everything else keeps working). (npm 8.11.0 is a partial cut of this surface — prefer 8.12.0.) v8.12 also adds the `runOptimisticAction` kit helper (client-only: the packaged optimistic apply → referee invoke → confirm/rollback loop with actionId receipts). v5.2+ targets environments on release **v0.1.19 or later** (`cks-game-api >= v0.10.3`, `cks-management-api >= v0.1.70`). The destructive mutations send an `idempotencyKey` argument that older servers don't define. v6.1's `client.gameApps.deleteGrid` additionally requires release **v0.1.33+** (`cks-game-api >= v0.12.3`). The game-model **permission effects** fields (`permissionEffects` on `gameModel.upsertFunction`/`seed`, `permissionEffectsAppliedJson` on events) require a `cks-game-api` build with the `2026-07-17-model-permission-effects` migration (v0.13.11+); older servers reject queries/mutations that include them (omit the fields and everything else keeps working). The **permission-read** surface (the `has_grid_permission`/`grid_at`/`has_chunk_permission` expression builtins the kit's `chunkPermission` locks compile to, and selector `*PermissionWhere` predicates) additionally requires `cks-game-api` **v0.13.12+**. Older `cks-game-api` builds report game-model **invoke policy denials** as `FORBIDDEN` GraphQL errors instead of resolving with `success: false`; as of this version the kit's invoke helpers map that error onto the documented `{ success: false, errorMessage }` result, so kit callers behave identically against both server generations. v8.6's **`client.compute`** (Compute Modules — server-side Rust/WASM logic) requires a `cks-game-api` build with the compute surface (the `compute*` root fields, v0.13.13+ dev line); older servers reject these operations with a GraphQL validation error, and everything else keeps working. v8.9's **realtime + live-ops surfaces** (`kit.abilities`/`movement`/`territory`/`racing`/`liveops`/`moderation`/`telemetry`, the loot engine path, `client.compute.deployTemplate` + `kit.deploy({engines})`, and the type-94..98 event parsers) complete the 30-abstraction catalog; v8.8's **session-genre engine surfaces** (`kit.instances`/`director`/`matchmaking`/`minigames`, the engine paths on matches/decks/leaderboards, `economy.orderBook`, and the type-91/92/93 event parsers) talk to the Wave 2 engine templates; capability detection keeps model-only deployments on today's behavior. v8.7's **engine kit surfaces** (`kit.mobs`, `kit.pets`, `kit.combat.attackRouted`, `kit.worldsim.forecast`, and the `kit/wire` pose/lane registry) talk to compute-module game engines built on the Wave 0/1 `cks-game-api` dev line (`crowdy-game-kit` crates); capability detection makes them degrade gracefully — model-only deployments keep today's behavior.
@@ -144,6 +159,7 @@ If `managementUrl` is omitted, the SDK falls back to `httpUrl` for backwards-com
 | `client.compute` | **Compute Modules** — server-side Rust/WASM logic: author + deploy source (`upsertModule`, `deployVersion`, `waitForCompile`), triggers + policy, synchronous `invoke`, and monitoring (`moduleRuns`, `moduleStats`, `moduleLogs`, `appDiagnostics`). Modules run server-only; see [Compute Modules docs](https://docs.crowdedkingdoms.com/game-api/compute-modules). |
 | `client.playerCompute` | Player-authored SERVER/CLIENT Rust/WASM bound to player-owned grids: deploy source, activate/deactivate, list modules/versions, and delete self-authored modules. |
 | `client.crowdyStudio` | Cloud project, personal-library, and common-file APIs for Crowdy Studio: target-scoped files, metadata/module names, pairing preference, optimistic revisions, copy-by-value imports, and atomic metadata/file saves. Generated operations are pinned to the committed merged SDL. |
+| `client.crowdyStudioAgent` | Generated, app-token Game API transport for durable agent sessions, Relay history/session pages, descriptors/budgets, exact approvals, browser tool results, heartbeat, control mutations, and ordered event subscriptions. |
 | `client.playerModel` | Player-owned flexible model containers and grid-confined automations (`containers`, `createContainer`, `setProperty`, `automations`, `createAutomation`, …). |
 | `client.marketplace` | Player-code store/install/consent flows plus player-authorized grid claims: `claimGridOwnership` preserves the existing-grid policy flow, while `claimGridChunk` atomically creates and owns one chunk under `SELF_CLAIM` and `releaseClaimedGrid` releases an eligible owner-created claim. |
 | `client.udp` | UDP proxy subscriptions + spatial mutations (`sendActorUpdate`, `sendVoxelUpdate`, `sendAudioPacket`, `sendTextPacket`, `sendClientEvent`). |
@@ -248,6 +264,193 @@ presentation enum to Crowdy Studio's runtime-oriented project kind and
 `CrowdyStudioRevisionConflictError` with the latest cloud project when that
 follow-up read succeeds.
 
+### Agent SDK, transport, and integrated dock (v12)
+
+The v12 agent API remains provider-neutral, while CrowdyJS now ships generated
+operations plus the production `CrowdyAgentGraphQLTransport` exposed as
+`client.crowdyStudioAgent`:
+
+```ts
+import {
+  CROWDY_AGENT_TOOL_REGISTRY_V1,
+  CrowdyStudioAgentController,
+} from '@crowdedkingdoms/crowdyjs/agent';
+
+const agent = new CrowdyStudioAgentController({
+  transport: game.crowdyStudioAgent,
+  createSession: {
+    appId,
+    projectId,
+    gridId,
+    mode: 'BUILD',
+    providerDataConsent: true,
+    idempotencyKey: crypto.randomUUID(),
+  },
+  beforeAgentWork: () => studio.controller.prepareForAgentWork(),
+});
+await agent.initialize(); // attach epoch → durable replay/gap fill → live tail
+```
+
+`CROWDY_AGENT_TOOL_REGISTRY_V1` is an immutable, digest-pinned registry of the
+minimum Studio/project/workspace/library/template/diagnostics/runtime and
+generic game tools. Every descriptor has exact logical and provider wire names,
+semantic version, bounded input/output JSON schemas,
+`additionalProperties:false`, executor, mode, risk/effect/reversibility,
+scope, approval, idempotency, timeout, and redaction metadata. Input schemas
+reject caller-supplied identity, epoch, lease, approval, endpoint, token, and
+other authority fields. `CrowdyAgentToolRegistry.fromWireName` is exact and
+case-sensitive; browser dispatch is execute-once by `toolCallId`, and ambiguous
+effects become `OUTCOME_UNKNOWN` instead of being repeated.
+
+`CrowdyStudioAgentTransportV1` owns no credentials and exposes only typed
+durable orchestration operations: session/history/descriptor/budget queries;
+create/attach/mode/event-ack/message/approval/tool-result/lease/pause/resume/
+cancel/close mutations; and the ordered event subscription. A generated adapter
+maps these methods to the operation names in
+`CROWDY_AGENT_GRAPHQL_OPERATIONS_V1`:
+
+- `crowdyStudioAgentSession`, `crowdyStudioAgentSessions`,
+  `crowdyStudioAgentHistory`, `crowdyStudioAgentToolDescriptors`, and
+  `crowdyStudioAgentBudget`;
+- `crowdyStudioAgentCreateSession`, `AttachClient`, `SetMode`,
+  `AcknowledgeEvents`, `Heartbeat`, `SendMessage`, `ApproveTool`, `RejectTool`,
+  `ToolResult`, `GrantLease`, `RevokeLease`, `Pause`, `Resume`, `CancelRun`,
+  and `CloseSession` (all with the `crowdyStudioAgent` prefix);
+- `crowdyStudioAgentEvents(sessionId, afterSeq, clientEpoch)`.
+
+The controller applies only contiguous decimal-string sequences, deduplicates
+event IDs, fills gaps from durable history, acknowledges the highest
+contiguous cursor, fences old attach epochs, and explicitly reconnects without
+resuming a run or Play lease. Approval methods use the exact displayed argument
+hash. Human edit/game input calls local preemption before best-effort transport
+cleanup. Attach uses a stable `clientInstanceId` and the server
+`replayAfterSeq`; public message input maps to Game API `content`, cancellation
+always sends an explicit run id, and PLAY sends a two-second heartbeat only
+while attached, active, and visible. Heartbeat, kill, and stale-epoch failures
+immediately clear local authority.
+
+Mode changes adopt the complete server-repinned session (registry digest,
+provider/app policy revisions, and context version) before loading its new
+effective descriptors. The Studio mount resolves the selected saved project
+after `CrowdyStudioController.initialize()`, overrides caller guesses when
+creating a BUILD session, and rejects an existing session bound to another
+project. Because v1 has no set-project mutation, switching projects fences the
+agent and requires a new session/remount.
+
+An active BUILD workspace lease is renewed every ten seconds through the same
+authenticated heartbeat; the server returns its renewed 30-second expiry.
+Human edits, project/context changes, lease revocation, disconnect, and destroy
+stop renewal and abort browser handlers. Run events retain their stable
+`code`, `reason`, and typed safe `error`.
+
+The committed descriptor digest fixture is checked on every build against the
+canonical registry. Coordinated refreshes first run
+`npm run agent-descriptors:drift -- --source <game-api-fixture>`; builds then
+recompute the full and canonical 28-tool Game API subset digest (14 mandatory
+game plus 14 Studio/diagnostic/runtime tools) so the fixture cannot silently
+diverge.
+
+Mount the responsive agent dock by adding `agent`; omit it to retain the v11
+manual UI unchanged:
+
+```ts
+const studio = await mountCrowdyStudio(host, {
+  projectProvider: game.crowdyStudio,
+  playerCompute: game.playerCompute,
+  appId,
+  gridId,
+  agent: {
+    transport: game.crowdyStudioAgent,
+    sessionId,
+    playerHost: bwfPlayerHostAdapter,
+  },
+});
+
+studio.agent?.sendMessage('Explain the current diagnostics');
+studio.controlLeaseManager?.preempt('HUMAN_INPUT');
+```
+
+The dock provides human-owned Ask/Build/Play selection, chat streaming,
+plan/tool status, exact approval hashes, diff/checkpoint cards, budget, visible
+lease scope/expiry, Pause/Resume/Stop, and checkpoint-restore requests. It uses
+text nodes for all untrusted content, ARIA status/log/group labels, visible
+focus, keyboard submission, and a container-query layout that moves the agent
+dock below narrow embeds.
+
+The headless `CrowdyStudioController` now also exposes:
+
+- `prepareForAgentWork()` to flush autosave and fail closed on conflict/offline;
+- `applyAtomicPatch()` and `synchronizeProject()` for all-or-none multi-file
+  updates, human-edit preemption, and Monaco synchronization;
+- `refreshCheckpoints()` / `restoreCheckpoint()` through the optional
+  transport-neutral `CrowdyStudioSynchronizationProvider` (the provider is
+  required for agent writes/restores and must make checkpoint + revision
+  changes durable and atomic);
+- typed draft/live results plus `runtimeSync` (`RUNNING_SAVED`,
+  `RUNNING_STALE`, `STOPPED`, or `NEVER_RUN`).
+
+### PlayerHostAdapter and Blocks with Friends integration
+
+`@crowdedkingdoms/crowdyjs/player-host` exports
+`PlayerHostAdapterV1`, capability/observation/command/result types and schemas,
+`AgentControlLeaseManager`, and `createPlayerHostAgentTools`. A game adapter
+implements only:
+
+```ts
+interface PlayerHostAdapterV1 {
+  readonly contractVersion: 'crowdy.player-host/1';
+  capabilities(): Promise<PlayerHostCapabilitiesV1>;
+  observe(request: ObserveRequestV1): Promise<GameObservationV1>;
+  dispatch(command: GameCommandV1, gate: ValidatedGateV1):
+    Promise<GameCommandResultV1>;
+  clearAgentIntent(reason: CrowdyAgentPreemptionReason): void;
+}
+```
+
+For Blocks with Friends, implement this interface over the same typed intent
+methods used by `PlayerController`, `ActionService`, `InventoryService`,
+`FishingService`, `RideService`, and existing referee/model calls. Construct
+`createPlayerHostAgentTools(adapter)` and pass `adapter` as the mount's
+`playerHost`. The returned lease manager enforces TTL, scopes, client epoch,
+host/controlled-entity revision, observation freshness, modal/death state,
+per-command rate limits, approvals, and tool-call dedup. Call
+`leaseManager.preempt('HUMAN_INPUT')` synchronously on key/mouse/touch input,
+`ESCAPE` on Escape, and the corresponding reason on death, target/context
+change, disconnect, or Stop. `clearAgentIntent` must immediately zero movement,
+look, and pending action intent. BWF does not integrate through raw CrowdyJS,
+DOM input, UDP packets, `PlayerCodeBroker`, or client-mod host calls.
+
+BWF should pass only `game.crowdyStudioAgent` and its
+`BwfPlayerHostAdapter` to the Studio mount; the mount derives the selected
+project id. Its adapter must implement the exact 14 mandatory game surfaces,
+classify combat as conditional approval, return typed failed/denied/unknown
+outcomes, and make `clearAgentIntent` synchronously cancel shared movement and
+action intents when the dispatcher aborts.
+
+The reconciled Game API development pilot advertises the exact 28-tool
+follow-up subset, including all 14 mandatory game descriptors. CrowdyJS routes
+all game tools through
+`PlayerHostAdapterV1`, the scoped lease gate, conditional combat approval,
+safety stop, heartbeat fencing, and typed result continuation. BWF Play now
+remains blocked only on the concrete BWF adapter/shared-intent wiring and its
+host/app policy configuration.
+
+The same browser dispatcher routes backend-advertised `runtime.test_draft`,
+`runtime.deploy_live`, `runtime.invoke`, and `runtime.stop` through the
+headless Studio controller. Draft testing is routine BUILD work; live deploy
+and LIVE invoke require the exact approval grant; stop remains an idempotent
+safety action. Inner game `FAILED`, `DENIED`, or `OUTCOME_UNKNOWN` results are
+promoted to matching outer terminal tool results and are never reported as
+successful.
+
+Runtime execution is plan-bound: requested targets must exactly equal the
+selected project’s authoritative target set, so a full-stack project cannot run
+CLIENT after SERVER-only authorization. Live deploy additionally rechecks the
+saved revision, canonical project content hash (including module names/files),
+and pairing preference after autosave. Invoke checks the exact running
+DRAFT/LIVE environment and export; stop always stops the complete selected
+project as a safety action rather than interpreting a partial target.
+
 | `createWorldSession(client, appId, config)` (from `@crowdedkingdoms/crowdyjs/stores`) | World Stores: opt-in, SDK-managed game state — typed codecs (`structCodec` binary DSL), your own actor with a 5 Hz send loop (`session.self`), a remote-actor registry with lanes/history/staleness (`session.actors`), attributed send errors (`session.errors`), a chunk/voxel cache with realtime merge + worldgen write-back (`session.chunks`), channel/direct-message inboxes + a typed event router, host tracking, typed save/avatar state, and a game-model container mirror. Only configured stores exist (compile-time + runtime); unimported stores tree-shake away. |
 | `client.kit(appId)` | Game Kit: ready-made mappings of game concepts onto the game model — `kit.inventory`, `kit.objects` (lockable doors/chests with custom permissions), `kit.npcs`, `kit.plots` (buy/rent land with transactional, replication-enforced grid grants), and the genre layers `kit.economy` (wallets/shops/trades/market), `kit.progression` (xp/skills/achievements/rating), `kit.loot`, `kit.quests`, `kit.combat`, `kit.matches` (session lobbies/turns/scores with notify-to-pull channels), `kit.decks` (hidden hands), `kit.worldsim` (clock/nodes/crops/waves), `kit.social` (parties/guilds/chat over teams+channels), `kit.leaderboards`, `kit.features` (tier gates), and the engine-aware helpers `kit.mobs` (refereed attacks, defs/slots, contact-damage parsing), `kit.pets` (adopt/summon/dismiss/rename), `kit.instances` (private world slices, seeded runs), `kit.director` (encounter runs), `kit.matchmaking` (queues/proposals/rating), `kit.minigames` (invoke-loop wrapper), `kit.economy.orderBook` (escrowed bid/ask market), engine paths on `kit.matches`/`kit.decks`/`kit.leaderboards`, `kit.quests` tutorial sequencing, `kit.engines` (compute capability detection) with `kit/wire` (the engine pose codec, `engineLanes()`, and the 77/90/91/92/93 event parsers) — plus blueprint builders + `kit.deploy(...)` for the admin "load the rules" step. |
 

package/dist/crowdy-agent/browser-dispatcher.d.ts

@@ -0,0 +1,41 @@
+import type { CrowdyAgentMode, CrowdyAgentToolInvocationV1, CrowdyAgentToolResultV1 } from './types.js';
+import { CrowdyAgentToolRegistry } from './registry.js';
+export interface CrowdyAgentBrowserToolContextV1 {
+    readonly invocation: CrowdyAgentToolInvocationV1;
+    readonly signal: AbortSignal;
+}
+export type CrowdyAgentBrowserToolHandlerV1 = (argumentsValue: Readonly<Record<string, unknown>>, context: CrowdyAgentBrowserToolContextV1) => unknown | Promise<unknown>;
+export type CrowdyAgentBrowserToolHandlersV1 = Readonly<Record<string, CrowdyAgentBrowserToolHandlerV1>>;
+export interface CrowdyAgentBrowserDispatcherOptionsV1 {
+    readonly registry: CrowdyAgentToolRegistry;
+    readonly handlers: CrowdyAgentBrowserToolHandlersV1;
+    readonly getSessionId?: () => string | null;
+    readonly getClientEpoch: () => string | null;
+    readonly getContextVersion: () => string;
+    readonly getMode?: () => CrowdyAgentMode;
+    readonly now?: () => number;
+    readonly maxRememberedCalls?: number;
+}
+/**
+ * Exact browser tool router with execute-once semantics. It has no fallback
+ * executor: unknown names, raw SDK access, and missing handlers fail closed.
+ */
+export declare class CrowdyAgentBrowserToolDispatcher {
+    private readonly options;
+    private readonly records;
+    private readonly active;
+    private readonly now;
+    constructor(options: CrowdyAgentBrowserDispatcherOptionsV1);
+    dispatch(invocation: CrowdyAgentToolInvocationV1): Promise<CrowdyAgentToolResultV1>;
+    has(toolCallId: string): boolean;
+    /** Abort pending browser work during human or context preemption. */
+    cancelActive(): void;
+    /**
+     * Cache lifetime is the attached session. Call only after that session is
+     * closed or fenced; clearing during a live session could repeat an effect.
+     */
+    clearClosedSession(): void;
+    private execute;
+    private validateEnvelope;
+}
+//# sourceMappingURL=browser-dispatcher.d.ts.map

package/dist/crowdy-agent/browser-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-dispatcher.d.ts","sourceRoot":"","sources":["../../src/crowdy-agent/browser-dispatcher.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,eAAe,EACf,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,UAAU,EAAE,2BAA2B,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,MAAM,+BAA+B,GAAG,CAC5C,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACjD,OAAO,EAAE,+BAA+B,KACrC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CACrD,MAAM,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAChD,CAAC;AAEF,MAAM,WAAW,qCAAqC;IACpD,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,MAAM,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,eAAe,CAAC;IACzC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAOD;;;GAGG;AACH,qBAAa,gCAAgC;IAK/B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEN,OAAO,EAAE,qCAAqC;IAe3E,QAAQ,CACN,UAAU,EAAE,2BAA2B,GACtC,OAAO,CAAC,uBAAuB,CAAC;IA6CnC,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIhC,qEAAqE;IACrE,YAAY,IAAI,IAAI;IAIpB;;;OAGG;IACH,kBAAkB,IAAI,IAAI;YAKZ,OAAO;IA6IrB,OAAO,CAAC,gBAAgB;CAyFzB"}

package/dist/crowdy-agent/browser-dispatcher.js

@@ -0,0 +1,264 @@
+import { CrowdyAgentError, CrowdyAgentOutcomeUnknownError, toAgentError, } from './errors.js';
+import { canonicalJson, sha256Digest } from './schema.js';
+/**
+ * Exact browser tool router with execute-once semantics. It has no fallback
+ * executor: unknown names, raw SDK access, and missing handlers fail closed.
+ */
+export class CrowdyAgentBrowserToolDispatcher {
+    constructor(options) {
+        this.options = options;
+        this.records = new Map();
+        this.active = new Map();
+        this.now = options.now ?? Date.now;
+        for (const name of Object.keys(options.handlers)) {
+            const matches = options.registry
+                .list({ executor: 'BROWSER' })
+                .filter(({ descriptor }) => descriptor.name === name);
+            if (matches.length === 0) {
+                throw new CrowdyAgentError('AGENT_TOOL_UNKNOWN', `Browser handler ${name} is not an exact registered browser tool`);
+            }
+        }
+    }
+    dispatch(invocation) {
+        if (typeof invocation.toolCallId !== 'string' ||
+            invocation.toolCallId.length < 1 ||
+            invocation.toolCallId.length > 128) {
+            return this.execute(invocation);
+        }
+        try {
+            // Bound arguments before canonical fingerprinting or cache insertion.
+            this.options.registry.validateInput(invocation.name, invocation.version, invocation.arguments);
+        }
+        catch {
+            return this.execute(invocation);
+        }
+        const fingerprint = invocationFingerprint(invocation);
+        const previous = this.records.get(invocation.toolCallId);
+        if (previous) {
+            if (previous.fingerprint !== fingerprint) {
+                return Promise.reject(new CrowdyAgentError('AGENT_IDEMPOTENCY_CONFLICT', `Tool call ${invocation.toolCallId} was replayed with different arguments`));
+            }
+            return previous.promise;
+        }
+        const max = this.options.maxRememberedCalls ?? 2048;
+        if (this.records.size >= max) {
+            return Promise.reject(new CrowdyAgentError('AGENT_RATE_LIMITED', 'Browser execute-once cache is full; attach a fresh session before continuing'));
+        }
+        const promise = this.execute(invocation);
+        this.records.set(invocation.toolCallId, { fingerprint, promise });
+        return promise;
+    }
+    has(toolCallId) {
+        return this.records.has(toolCallId);
+    }
+    /** Abort pending browser work during human or context preemption. */
+    cancelActive() {
+        for (const controller of this.active.values())
+            controller.abort();
+    }
+    /**
+     * Cache lifetime is the attached session. Call only after that session is
+     * closed or fenced; clearing during a live session could repeat an effect.
+     */
+    clearClosedSession() {
+        this.cancelActive();
+        this.records.clear();
+    }
+    async execute(invocation) {
+        const startedMs = this.now();
+        const startedAt = new Date(startedMs).toISOString();
+        let entry;
+        let activeAbort = null;
+        try {
+            this.validateEnvelope(invocation, startedMs);
+            entry = this.options.registry.require(invocation.name, invocation.version);
+            if (entry.descriptor.executor !== 'BROWSER') {
+                throw new CrowdyAgentError('AGENT_TOOL_UNKNOWN', `${invocation.name} is not a browser-executed tool`);
+            }
+            if (entry.descriptorDigest !== invocation.descriptorDigest) {
+                throw new CrowdyAgentError('AGENT_CONTEXT_STALE', `${invocation.name} descriptor digest changed`);
+            }
+            if (this.options.getMode &&
+                !entry.descriptor.modes.includes(this.options.getMode())) {
+                throw new CrowdyAgentError('AGENT_SCOPE_DENIED', `${invocation.name} is unavailable in the selected mode`);
+            }
+            if (entry.descriptor.approval.policy === 'REQUIRED' &&
+                !invocation.approvalGrant) {
+                throw new CrowdyAgentError('AGENT_APPROVAL_REQUIRED', `${invocation.name} requires exact human approval`);
+            }
+            this.options.registry.validateInput(invocation.name, invocation.version, invocation.arguments);
+            if (!isRecord(invocation.arguments)) {
+                throw new CrowdyAgentError('AGENT_TOOL_INPUT_INVALID', 'Browser tool arguments must be an object');
+            }
+            const handler = this.options.handlers[invocation.name];
+            if (!handler) {
+                throw new CrowdyAgentError('AGENT_HOST_UNAVAILABLE', `No browser host implements ${invocation.name}`);
+            }
+            const deadlineMs = Date.parse(invocation.deadline);
+            const remaining = Math.min(entry.descriptor.timeoutMs, Math.max(0, deadlineMs - startedMs));
+            const abort = new AbortController();
+            activeAbort = abort;
+            this.active.set(invocation.toolCallId, abort);
+            const output = await runWithDeadline(Promise.resolve(handler(invocation.arguments, {
+                invocation,
+                signal: abort.signal,
+            })), remaining, abort);
+            if (abort.signal.aborted) {
+                throw new CrowdyAgentError('AGENT_CANCELLED', 'Browser tool was cancelled before its result was accepted');
+            }
+            if (invocation.contextVersion !== this.options.getContextVersion()) {
+                throw new CrowdyAgentError('AGENT_CONTEXT_STALE', 'Browser tool context changed before its result was accepted');
+            }
+            this.options.registry.validateOutput(invocation.name, invocation.version, output);
+            return {
+                protocolVersion: 'crowdy.tool-result/1',
+                toolCallId: invocation.toolCallId,
+                status: 'SUCCEEDED',
+                output,
+                observedContextVersion: this.options.getContextVersion(),
+                startedAt,
+                finishedAt: new Date(this.now()).toISOString(),
+            };
+        }
+        catch (error) {
+            const registered = this.options.registry.get(invocation.name, invocation.version);
+            const timedOut = error instanceof CrowdyAgentError && error.code === 'AGENT_TOOL_TIMEOUT';
+            const ambiguous = error instanceof CrowdyAgentOutcomeUnknownError ||
+                (timedOut &&
+                    registered !== undefined &&
+                    ['TOOL_CALL_ONCE', 'NON_RETRYABLE'].includes(registered.descriptor.idempotency.class));
+            return {
+                protocolVersion: 'crowdy.tool-result/1',
+                toolCallId: invocation.toolCallId,
+                status: ambiguous
+                    ? 'OUTCOME_UNKNOWN'
+                    : timedOut
+                        ? 'TIMED_OUT'
+                        : error instanceof CrowdyAgentError &&
+                            error.code === 'AGENT_CANCELLED'
+                            ? 'CANCELLED'
+                            : 'FAILED',
+                error: toAgentError(ambiguous
+                    ? new CrowdyAgentOutcomeUnknownError(error instanceof Error ? error.message : undefined)
+                    : error, timedOut ? 'AGENT_TOOL_TIMEOUT' : 'AGENT_TOOL_FAILED'),
+                observedContextVersion: this.options.getContextVersion(),
+                startedAt,
+                finishedAt: new Date(this.now()).toISOString(),
+            };
+        }
+        finally {
+            if (activeAbort)
+                this.active.delete(invocation.toolCallId);
+        }
+    }
+    validateEnvelope(invocation, now) {
+        if (invocation.protocolVersion !== 'crowdy.tool-call/1') {
+            throw new CrowdyAgentError('AGENT_TOOL_INPUT_INVALID', 'Unsupported browser tool-call protocol');
+        }
+        for (const [field, value, max] of [
+            ['sessionId', invocation.sessionId, 128],
+            ['runId', invocation.runId, 128],
+            ['toolCallId', invocation.toolCallId, 128],
+            ['contextVersion', invocation.contextVersion, 128],
+        ]) {
+            if (typeof value !== 'string' ||
+                value.length < 1 ||
+                value.length > max) {
+                throw new CrowdyAgentError('AGENT_TOOL_INPUT_INVALID', `${field} is outside protocol bounds`, { field });
+            }
+        }
+        const currentSessionId = this.options.getSessionId?.();
+        if (currentSessionId && invocation.sessionId !== currentSessionId) {
+            throw new CrowdyAgentError('AGENT_SESSION_NOT_FOUND', 'Browser tool dispatch belongs to a different session');
+        }
+        if (typeof invocation.descriptorDigest !== 'string' ||
+            typeof invocation.argumentHash !== 'string' ||
+            !/^sha256:[0-9a-f]{64}$/u.test(invocation.descriptorDigest) ||
+            !/^sha256:[0-9a-f]{64}$/u.test(invocation.argumentHash) ||
+            (invocation.approvalGrant !== undefined &&
+                (typeof invocation.approvalGrant !== 'string' ||
+                    invocation.approvalGrant.length < 1)) ||
+            (invocation.approvalGrant?.length ?? 0) > 512 ||
+            (invocation.idempotencyKey !== undefined &&
+                (typeof invocation.idempotencyKey !== 'string' ||
+                    invocation.idempotencyKey.length < 1)) ||
+            (invocation.idempotencyKey?.length ?? 0) > 240) {
+            throw new CrowdyAgentError('AGENT_TOOL_INPUT_INVALID', 'Browser tool dispatch contains invalid digest or capability metadata');
+        }
+        const currentEpoch = this.options.getClientEpoch();
+        if (!currentEpoch ||
+            !invocation.clientEpoch ||
+            invocation.clientEpoch !== currentEpoch) {
+            throw new CrowdyAgentError('AGENT_CLIENT_EPOCH_STALE', 'Browser tool dispatch belongs to a stale client epoch');
+        }
+        if (invocation.contextVersion !== this.options.getContextVersion()) {
+            throw new CrowdyAgentError('AGENT_CONTEXT_STALE', 'Browser tool dispatch belongs to a stale app, project, or game context');
+        }
+        if (typeof invocation.deadline !== 'string' ||
+            invocation.deadline.length < 20 ||
+            invocation.deadline.length > 40) {
+            throw new CrowdyAgentError('AGENT_TOOL_INPUT_INVALID', 'Browser tool deadline is invalid');
+        }
+        const deadline = Date.parse(invocation.deadline);
+        if (!Number.isFinite(deadline) || deadline <= now) {
+            throw new CrowdyAgentError('AGENT_TOOL_TIMEOUT', 'Browser tool deadline has expired');
+        }
+    }
+}
+function invocationFingerprint(invocation) {
+    return sha256Digest(canonicalJson({
+        protocolVersion: invocation.protocolVersion,
+        sessionId: invocation.sessionId,
+        runId: invocation.runId,
+        toolCallId: invocation.toolCallId,
+        name: invocation.name,
+        version: invocation.version,
+        descriptorDigest: invocation.descriptorDigest,
+        arguments: invocation.arguments,
+        argumentHash: invocation.argumentHash,
+        contextVersion: invocation.contextVersion,
+        ...(invocation.clientEpoch
+            ? { clientEpoch: invocation.clientEpoch }
+            : {}),
+        ...(invocation.leaseId ? { leaseId: invocation.leaseId } : {}),
+        ...(invocation.approvalGrant
+            ? { approvalGrant: invocation.approvalGrant }
+            : {}),
+        ...(invocation.idempotencyKey
+            ? { idempotencyKey: invocation.idempotencyKey }
+            : {}),
+    }));
+}
+function runWithDeadline(operation, timeoutMs, abort) {
+    if (timeoutMs <= 0) {
+        abort.abort();
+        return Promise.reject(new CrowdyAgentError('AGENT_TOOL_TIMEOUT', 'Browser tool deadline expired'));
+    }
+    return new Promise((resolve, reject) => {
+        let timedOut = false;
+        const onAbort = () => {
+            if (!timedOut) {
+                clearTimeout(timer);
+                reject(new CrowdyAgentError('AGENT_CANCELLED', 'Browser tool was cancelled by human or context preemption'));
+            }
+        };
+        abort.signal.addEventListener('abort', onAbort, { once: true });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            abort.abort();
+            reject(new CrowdyAgentError('AGENT_TOOL_TIMEOUT', `Browser tool exceeded its ${timeoutMs}ms deadline`));
+        }, timeoutMs);
+        operation.then((value) => {
+            clearTimeout(timer);
+            abort.signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            abort.signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}