Next

.actrc

@@ -0,0 +1,2 @@
+-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
+--container-architecture linux/amd64

.github/workflows/ci.yml

@@ -4,9 +4,8 @@ on:
   push:
     branches: [main, master]
   pull_request:
-    paths:
-      - "typescript/**"
-      - ".github/workflows/ci.yml"
+  merge_group:
+    branches: [main, master, next]
   workflow_dispatch:
 
 jobs:
@@ -25,12 +24,12 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 10.7.0
           run_install: false
 
       - name: Install dependencies in project
         working-directory: ./typescript
-        run: pnpm install --no-frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Run linter
         working-directory: ./typescript

.github/workflows/onchain-actions.yml

@@ -26,12 +26,12 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10
+          version: 10.7.0
           run_install: false
 
       - name: Install dependencies in project
         working-directory: ./typescript
-        run: pnpm install --no-frozen-lockfile
+        run: pnpm install --frozen-lockfile
 
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1

docs/merge-queue-runbook.md

@@ -0,0 +1,43 @@
+# Merge Queue Runbook
+
+## Purpose
+
+This runbook prevents PR-head vs merge-ref drift by enforcing CI in merge context and serializing merges through GitHub merge queue.
+
+## Required repository settings
+
+- `CI` workflow includes `merge_group` trigger.
+- Branch rulesets for `next` and default branch require:
+  - Strict required status checks (`build`).
+  - Merge queue enabled.
+
+## Daily workflow
+
+1. Open PR as usual and wait for required checks.
+2. Resolve review feedback and re-run checks.
+3. Use merge queue instead of direct merge.
+4. Let queue revalidate in merge context before final merge.
+
+## When to run a local merge-ref check (optional)
+
+Run local parity checks when a PR is high-risk or multiple related PRs are landing together.
+
+Recommended quick check:
+
+```bash
+act merge_group -W .github/workflows/ci.yml -n
+```
+
+If you suspect integration conflicts, run a local merge-ref simulation and verify lint/build:
+
+```bash
+git fetch origin pull/<PR_NUMBER>/head:pr-head pull/<PR_NUMBER>/merge:pr-merge
+git diff pr-head..pr-merge -- <path/to/suspect/file>
+pnpm -C typescript lint
+pnpm -C typescript build
+```
+
+## Operational notes
+
+- Keep admin bypasses rare; bypassing queue weakens merge guarantees.
+- If queue latency grows, tune merge queue batch settings before disabling protection.

typescript/clients/web-ag-ui/apps/agent-clmm/package.json

@@ -12,7 +12,7 @@
     "test": "pnpm test:unit && pnpm test:int && pnpm test:e2e",
     "test:unit": "vitest run --config vitest.config.unit.ts",
     "test:int": "bash -lc 'ENV_FILE=.env.test; [ -f \"$ENV_FILE\" ] || ENV_FILE=.env.test.example; exec tsx --env-file=\"$ENV_FILE\" ./node_modules/vitest/vitest.mjs run --config vitest.config.int.ts \"$@\"' --",
-    "test:e2e": "bash -lc 'ENV_FILE=.env.test; [ -f \"$ENV_FILE\" ] || ENV_FILE=.env.test.example; exec tsx --env-file=\"$ENV_FILE\" ./node_modules/vitest/vitest.mjs run --config vitest.config.e2e.ts --no-file-parallelism --maxConcurrency=1 \"$@\"' --",
+    "test:e2e": "bash -lc 'ENV_FILE=.env.test; [ -f \"$ENV_FILE\" ] || ENV_FILE=.env.test.example; CLMM_E2E=\"${CLMM_E2E:-true}\" LANGGRAPH_DEPLOYMENT_URL=\"${LANGGRAPH_DEPLOYMENT_URL:-http://localhost:8124}\" exec tsx --env-file=\"$ENV_FILE\" ./node_modules/vitest/vitest.mjs run --config vitest.config.e2e.ts --no-file-parallelism --maxConcurrency=1 \"$@\"' --",
     "test:watch": "vitest watch",
     "test:ci": "pnpm test:unit && pnpm test:int",
     "lint": "eslint \"src\" \"tests\" --ext .ts",

typescript/clients/web-ag-ui/apps/agent-clmm/src/agent.ts

@@ -31,16 +31,28 @@ import { extractCommand, resolveCommandTarget, runCommandNode } from './workflow
 import { runCycleCommandNode } from './workflow/nodes/runCycleCommand.js';
 import { summarizeNode } from './workflow/nodes/summarize.js';
 import { syncStateNode } from './workflow/nodes/syncState.js';
+import { resolveNextOnboardingNode } from './workflow/onboardingRouting.js';
 import { saveBootstrapContext } from './workflow/store.js';
 
 /**
  * Routes after bootstrap based on the original command.
  * - sync: go to syncState (just return state after bootstrap)
- * - hire/cycle: continue to listPools for full setup flow
+ * - hire/cycle: resume from the next missing onboarding requirement
  */
-function resolvePostBootstrap(state: ClmmState): 'listPools' | 'syncState' {
+function resolvePostBootstrap(
+  state: ClmmState,
+):
+  | 'listPools'
+  | 'collectOperatorInput'
+  | 'collectFundingTokenInput'
+  | 'collectDelegations'
+  | 'prepareOperator'
+  | 'syncState' {
   const command = extractCommand(state.messages) ?? state.view.command;
-  return command === 'sync' ? 'syncState' : 'listPools';
+  if (command === 'sync') {
+    return 'syncState';
+  }
+  return resolveNextOnboardingNode(state);
 }
 
 const store = new InMemoryStore();

typescript/clients/web-ag-ui/apps/agent-clmm/src/domain/types.ts

@@ -58,7 +58,13 @@ const EmberPoolTokenSchema = z.object({
   symbol: z.string(),
   decimals: z.number().int().nonnegative(),
   isNative: z.boolean().optional(),
-  iconUri: z.string().optional(),
+  // Ember occasionally returns `null` for iconUri; normalize to `undefined` so
+  // pool listing doesn't fail due to a missing icon.
+  iconUri: z
+    .string()
+    .nullable()
+    .optional()
+    .transform((value) => value ?? undefined),
   isVetted: z.boolean().optional(),
 });
 

typescript/clients/web-ag-ui/apps/agent-clmm/src/domain/types.unit.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { PoolListResponseSchema } from './types.js';
+
+describe('PoolListResponseSchema', () => {
+  it('accepts null token iconUri from Ember API and normalizes to undefined', () => {
+    const parsed = PoolListResponseSchema.parse({
+      liquidityPools: [
+        {
+          identifier: { chainId: '42161', address: '0xpool' },
+          tokens: [
+            {
+              tokenUid: { chainId: '42161', address: '0xtoken0' },
+              name: 'Token0',
+              symbol: 'T0',
+              decimals: 18,
+              iconUri: null,
+            },
+            {
+              tokenUid: { chainId: '42161', address: '0xtoken1' },
+              name: 'Token1',
+              symbol: 'T1',
+              decimals: 18,
+            },
+          ],
+          currentPrice: '1',
+          providerId: 'camelot',
+          poolName: 'T0/T1',
+        },
+      ],
+    });
+
+    expect(parsed.liquidityPools[0]?.tokens[0]?.iconUri).toBeUndefined();
+  });
+});
+

typescript/clients/web-ag-ui/apps/agent-clmm/src/workflow/context.ts

@@ -64,7 +64,7 @@ export type ClmmActivity = {
   events: ClmmEvent[];
 };
 
-export type ClmmTransaction = {
+export type AgentTransaction = {
   cycle: number;
   action: string;
   txHash?: string;
@@ -221,7 +221,7 @@ type ClmmViewState = {
   profile: ClmmProfile;
   activity: ClmmActivity;
   metrics: ClmmMetrics;
-  transactionHistory: ClmmTransaction[];
+  transactionHistory: AgentTransaction[];
   accounting: ClmmAccounting;
   delegationsBypassActive?: boolean;
 };

typescript/clients/web-ag-ui/apps/agent-clmm/src/workflow/historyStore.ts

@@ -5,7 +5,7 @@ import type { NavSnapshot, FlowLogEvent } from '../accounting/types.js';
 import { resolveStoreHistoryLimit } from '../config/constants.js';
 import type { RebalanceTelemetry } from '../domain/types.js';
 
-import type { ClmmTransaction } from './context.js';
+import type { AgentTransaction } from './context.js';
 
 const STORE_HISTORY_LIMIT = resolveStoreHistoryLimit();
 
@@ -88,7 +88,7 @@ export async function appendTelemetryHistory(params: {
 
 export async function appendTransactionHistory(params: {
   threadId?: string;
-  transactions: ClmmTransaction[];
+  transactions: AgentTransaction[];
   store?: BaseStore;
 }): Promise<void> {
   await appendHistory({

typescript/clients/web-ag-ui/apps/agent-clmm/src/workflow/nodes/bootstrap.ts

@@ -1,5 +1,5 @@
 import { copilotkitEmitState } from '@copilotkit/sdk-js/langgraph';
-import { Command } from '@langchain/langgraph';
+import type { Command } from '@langchain/langgraph';
 
 import { resolvePollIntervalMs, resolveStreamLimit } from '../../config/constants.js';
 import { logInfo, type ClmmEvent, type ClmmState, type ClmmUpdate } from '../context.js';
@@ -15,10 +15,9 @@ export const bootstrapNode = async (
 
   if (state.private.bootstrapped) {
     logInfo('Skipping bootstrap; state already initialized for thread', { threadId });
-    return new Command({
-      update: {},
-      goto: 'listPools',
-    });
+    // Return a no-op update so the graph's post-bootstrap conditional routing
+    // decides the next node from current state.
+    return {};
   }
 
   // Note: We don't store client instances in state because LangGraph's checkpointer

typescript/clients/web-ag-ui/apps/agent-clmm/src/workflow/nodes/bootstrap.unit.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import type { ClmmState } from '../context.js';
+
+import { bootstrapNode } from './bootstrap.js';
+
+describe('bootstrapNode', () => {
+  it('returns a no-op update when the thread is already bootstrapped', async () => {
+    const state = {
+      private: {
+        bootstrapped: true,
+      },
+    } as unknown as ClmmState;
+
+    const result = await bootstrapNode(state, {
+      configurable: { thread_id: 'thread-1' },
+    } as never);
+
+    expect(result).toEqual({});
+  });
+});