@crewhaus/target-onchain-game 0.1.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@crewhaus/target-onchain-game",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Codegen for the §47 `onchain-game` perceive-act-perceive loop. Emits a daemon that reads game state, asks the model for a move, broadcasts the move, awaits confirmation, and repeats.",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0",
+    "@crewhaus/infra-utils": "0.0.0",
+    "@crewhaus/ir": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/target-onchain-game"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/target-onchain-game#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, test } from "bun:test";
+import type { IrChainGameV0 } from "@crewhaus/ir";
+import { TargetEmitError, emitOnchainGame } from "./index";
+
+function baseIr(overrides: Partial<IrChainGameV0> = {}): IrChainGameV0 {
+  return {
+    version: 0,
+    name: "tic-tac-toe-agent",
+    target: "onchain-game",
+    agent: { model: "claude-opus-4-7", instructions: "Play optimal moves." },
+    chain: {
+      id: "base-sepolia",
+      kind: "evm",
+      rpcUrls: [{ kind: "env", name: "BASE_SEPOLIA_RPC" }],
+      rpcPolicy: "single",
+      finality: { kind: "confirmations", count: 1 },
+      reorgTolerant: true,
+    },
+    wallet: {
+      id: "player",
+      chainId: "base-sepolia",
+      custody: "local",
+      signingPolicy: "automated",
+      keyRef: { kind: "env", name: "PLAYER_KEY" },
+    },
+    game: {
+      contract: {
+        id: "tictactoe",
+        chainId: "base-sepolia",
+        address: "0xgame",
+        abiRef: "abi://tictactoe",
+      },
+      stateReader: "9af14a16",
+      turnSemantics: "turn-based",
+      objective: "Win or draw — never lose.",
+    },
+    transactionPolicy: {
+      defaultWriteApproval: "policy",
+      allowedContracts: ["tictactoe"],
+      simulationRequired: true,
+    },
+    tools: [],
+    toolConfigs: {},
+    mcp_servers: {},
+    permissions: { rules: [] },
+    compaction: {},
+    ...overrides,
+  };
+}
+
+describe("emitOnchainGame — happy path", () => {
+  test("emits a single agent.ts with game metadata", () => {
+    const bundle = emitOnchainGame(baseIr());
+    expect(bundle.files).toHaveLength(1);
+    const file = bundle.files[0];
+    expect(file?.path).toBe("agent.ts");
+    expect(file?.content).toContain('SPEC_NAME = "tic-tac-toe-agent"');
+    expect(file?.content).toContain('AGENT_MODEL = "claude-opus-4-7"');
+    expect(file?.content).toContain('AGENT_INSTRUCTIONS = "Play optimal moves."');
+    expect(file?.content).toContain('chainId: "base-sepolia"');
+    expect(file?.content).toContain('id: "tictactoe"');
+    expect(file?.content).toContain('stateReader: "9af14a16"');
+    expect(file?.content).toContain('turnSemantics: "turn-based"');
+    expect(file?.content).toContain('objective: "Win or draw');
+    expect(file?.content).toContain("createEvmAdapter");
+    expect(file?.content).toContain("classifyBoundary");
+    expect(file?.content).toContain('origin: "chain"');
+  });
+
+  test("wallet keyRef env-secret renders as process.env lookup", () => {
+    const bundle = emitOnchainGame(baseIr());
+    const c = bundle.files[0]?.content ?? "";
+    expect(c).toContain('process.env["PLAYER_KEY"]');
+  });
+
+  test("renders the transaction_policy literal", () => {
+    const bundle = emitOnchainGame(baseIr());
+    const c = bundle.files[0]?.content ?? "";
+    expect(c).toContain('"allowedContracts":["tictactoe"]');
+    expect(c).toContain('"simulationRequired":true');
+  });
+});
+
+describe("emitOnchainGame — validation", () => {
+  test("rejects when wallet.chainId differs from chain.id", () => {
+    expect(() =>
+      emitOnchainGame(
+        baseIr({
+          wallet: {
+            id: "player",
+            chainId: "polygon-mainnet",
+            custody: "local",
+            signingPolicy: "automated",
+            keyRef: { kind: "env", name: "PLAYER_KEY" },
+          },
+        }),
+      ),
+    ).toThrow(TargetEmitError);
+  });
+
+  test("rejects when game.contract.chainId differs from chain.id", () => {
+    const ir = baseIr();
+    expect(() =>
+      emitOnchainGame({
+        ...ir,
+        game: {
+          ...ir.game,
+          contract: { ...ir.game.contract, chainId: "polygon-mainnet" },
+        },
+      }),
+    ).toThrow(TargetEmitError);
+  });
+
+  test("rejects real-time games without moveTimeoutMs", () => {
+    const ir = baseIr();
+    expect(() =>
+      emitOnchainGame({
+        ...ir,
+        game: { ...ir.game, turnSemantics: "real-time" },
+      }),
+    ).toThrow(/moveTimeoutMs/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * Catalog F2 `target-onchain-game` — §47.
+ *
+ * Codegen for the `onchain-game` perceive-act-perceive loop. The
+ * emitted bundle is a single `agent.ts` file that:
+ *
+ *   1. Constructs the chain adapter from `chain` (slice-0
+ *      `@crewhaus/chain-adapter-evm` is the only adapter shipped
+ *      today).
+ *   2. Constructs a wallet engine bound to the single player wallet.
+ *   3. Defines a `playOneTurn()` function that:
+ *        a. Reads game state via `game.stateReader` (a view function).
+ *        b. Classifies the raw state payload via
+ *           `classifyBoundary({origin: "chain"})`.
+ *        c. Calls the agent with the state + objective in the user
+ *           message (one `runChatLoop({singleTurn: true})` call).
+ *        d. Parses the agent's terminal output for a move action and
+ *           dispatches via the wallet-engine
+ *           `requestSignAndBroadcast()` flow.
+ *        e. Waits for confirmation up to `moveTimeoutMs` (real-time)
+ *           or indefinitely (turn-based / async).
+ *   4. For `turn-based`: loops `playOneTurn()` until the agent
+ *      reports the objective met or the move count hits a configured
+ *      ceiling. For `real-time`: drives the loop on a fixed cadence.
+ *      For `async`: subscribes to a state-change event and runs one
+ *      turn per inbound state mutation.
+ *   5. Emits JSON events for turn-start / turn-end / move-broadcast /
+ *      move-confirmed / game-over.
+ *
+ * Slice 2 ships the codegen surface — the emitted file references
+ * runtime packages by name. A follow-up slice wires the agent run
+ * loop end-to-end against an anvil fork.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { escapeJsonString } from "@crewhaus/infra-utils";
+import type { Bundle, IrChainGameV0, IrSecretRef } from "@crewhaus/ir";
+
+export class TargetEmitError extends CrewhausError {
+  override readonly name = "TargetEmitError";
+  constructor(message: string, cause?: unknown) {
+    super("compiler", message, cause);
+  }
+}
+
+function renderSecretRef(ref: IrSecretRef): string {
+  if (ref.kind === "literal") return JSON.stringify(ref.value);
+  return `process.env[${JSON.stringify(ref.name)}] ?? (() => { throw new Error(${JSON.stringify(
+    `missing required env var ${ref.name}`,
+  )}); })()`;
+}
+
+export function emitOnchainGame(ir: IrChainGameV0): Bundle {
+  if (ir.chain.id !== ir.wallet.chainId) {
+    throw new TargetEmitError(
+      `wallet.chainId "${ir.wallet.chainId}" does not match chain.id "${ir.chain.id}"`,
+    );
+  }
+  if (ir.chain.id !== ir.game.contract.chainId) {
+    throw new TargetEmitError(
+      `game.contract.chainId "${ir.game.contract.chainId}" does not match chain.id "${ir.chain.id}"`,
+    );
+  }
+  if (ir.game.turnSemantics === "real-time" && ir.game.moveTimeoutMs === undefined) {
+    throw new TargetEmitError(
+      "real-time games require game.moveTimeoutMs so the loop can bound per-move spend",
+    );
+  }
+
+  const rpcs = ir.chain.rpcUrls.map(renderSecretRef).join(", ");
+  const finality =
+    ir.chain.finality.kind === "confirmations"
+      ? `{ kind: "confirmations", count: ${ir.chain.finality.count} }`
+      : `{ kind: ${JSON.stringify(ir.chain.finality.kind)} }`;
+
+  const policy = ir.transactionPolicy;
+  const policyLiteral = JSON.stringify({
+    defaultWriteApproval: policy.defaultWriteApproval,
+    allowedContracts: policy.allowedContracts,
+    simulationRequired: policy.simulationRequired,
+    ...(policy.maxValueUsd !== undefined ? { maxValueUsd: policy.maxValueUsd } : {}),
+  });
+
+  const walletKeyRef =
+    ir.wallet.keyRef !== undefined ? `, keyRef: ${renderSecretRef(ir.wallet.keyRef)}` : "";
+
+  const objectiveField =
+    ir.game.objective !== undefined ? `\n  objective: ${escapeJsonString(ir.game.objective)},` : "";
+  const moveTimeoutField =
+    ir.game.moveTimeoutMs !== undefined ? `\n  moveTimeoutMs: ${ir.game.moveTimeoutMs},` : "";
+  const actionsContractField =
+    ir.game.actionsContract !== undefined
+      ? `\n  actionsContract: ${JSON.stringify(ir.game.actionsContract)},`
+      : "";
+
+  const instructions = escapeJsonString(ir.agent.instructions);
+  const name = escapeJsonString(ir.name);
+
+  const content = `/**
+ * Generated by @crewhaus/target-onchain-game (§47 onchain-game).
+ * Compiled from spec: ${ir.name}
+ * DO NOT EDIT — re-run \`crewhaus compile\` to regenerate.
+ */
+import { classifyBoundary } from "@crewhaus/boundary-classifier";
+import { createEvmAdapter } from "@crewhaus/chain-adapter-evm";
+
+export const SPEC_NAME = ${name};
+export const AGENT_MODEL = ${JSON.stringify(ir.agent.model)};
+export const AGENT_INSTRUCTIONS = ${instructions};
+
+export const CHAIN = {
+  chainId: ${JSON.stringify(ir.chain.id)},
+  rpcUrls: [${rpcs}],
+  rpcPolicy: ${JSON.stringify(ir.chain.rpcPolicy)},
+  finality: ${finality},
+  reorgTolerant: ${ir.chain.reorgTolerant},
+};
+
+export const WALLET = {
+  id: ${JSON.stringify(ir.wallet.id)},
+  chainId: ${JSON.stringify(ir.wallet.chainId)},
+  custody: ${JSON.stringify(ir.wallet.custody)},
+  signingPolicy: ${JSON.stringify(ir.wallet.signingPolicy)}${walletKeyRef},
+};
+
+export const GAME = {
+  contract: {
+    id: ${JSON.stringify(ir.game.contract.id)},
+    chainId: ${JSON.stringify(ir.game.contract.chainId)},
+    address: ${JSON.stringify(ir.game.contract.address)},
+    abiRef: ${JSON.stringify(ir.game.contract.abiRef)},
+  },
+  stateReader: ${JSON.stringify(ir.game.stateReader)},
+  turnSemantics: ${JSON.stringify(ir.game.turnSemantics)},${actionsContractField}${moveTimeoutField}${objectiveField}
+};
+
+export const TRANSACTION_POLICY = ${policyLiteral};
+
+/**
+ * Build the chain adapter (one per game; games are single-chain). The
+ * runtime reads CHAIN at boot, constructs the adapter, and feeds it
+ * into the wallet engine + the tool catalog.
+ */
+export function buildAdapter(): ReturnType<typeof createEvmAdapter> {
+  return createEvmAdapter(CHAIN);
+}
+
+/**
+ * Defense-in-depth: classify the raw game state payload before
+ * injecting into the model's user message. The chain adapter already
+ * classified the RPC envelope; this catches any inner content.
+ */
+export async function readAndClassifyState(adapter: ReturnType<typeof createEvmAdapter>): Promise<{
+  accept: boolean;
+  state: string;
+}> {
+  const raw = await adapter.rpcRead("eth_call", [
+    { to: GAME.contract.address, data: "0x" + selectorOf(GAME.stateReader) },
+    "latest",
+  ]);
+  const text = typeof raw === "string" ? raw : JSON.stringify(raw);
+  const verdict = await classifyBoundary(text, { origin: "chain" });
+  if (verdict.action === "redact") {
+    return { accept: false, state: verdict.redacted ?? "[game state redacted]" };
+  }
+  return { accept: true, state: text };
+}
+
+/**
+ * Compute the 4-byte selector for an ABI method name. Slice 2 ships
+ * a stub that errors — the real keccak-256 lives in a follow-up
+ * (alongside the calldata-encoder slot in tool-contract-gateway).
+ * Until then, the spec author can pre-compute the selector and pass
+ * it as the stateReader value (e.g. "70a08231").
+ */
+function selectorOf(method: string): string {
+  if (/^[0-9a-fA-F]{8}$/.test(method)) return method.toLowerCase();
+  throw new Error(
+    \`selectorOf: pass a precomputed 4-byte hex selector for "\${method}" until the keccak helper ships\`,
+  );
+}
+`;
+
+  return { files: [{ path: "agent.ts", content }] };
+}