@animalabs/connectome-host 0.3.9 → 0.4.0

package/src/web/protocol.ts

@@ -280,6 +280,31 @@ export interface BranchChangedMessage {
   branch: { id: string; name: string };
 }
 
+/** One Chronicle branch with its lineage. `parentId`/`branchPoint` are
+ *  undefined for the root branch; together they place the fork in the
+ *  parent's sequence so the SPA can render a lineage tree. */
+export interface BranchRow {
+  id: string;
+  name: string;
+  /** Head sequence number of the branch. */
+  head: number;
+  parentId?: string;
+  /** Sequence in the PARENT at which this branch forked. */
+  branchPoint?: number;
+  /** Epoch millis creation time. */
+  created: number;
+}
+
+/** Full branch listing with lineage — response to `request-branches`, routed
+ *  only to the requesting client. The SPA refreshes it after every
+ *  `branch-changed` while its branch panel is open. */
+export interface BranchesListMessage {
+  type: 'branches-list';
+  branches: BranchRow[];
+  /** id of the branch the agent is currently on. */
+  currentId: string;
+}
+
 /** Sent when the active session changes. Clients should soft-reconnect. */
 export interface SessionChangedMessage {
   type: 'session-changed';
@@ -442,6 +467,7 @@ export type WebUiServerMessage =
   | UsageMessage
   | CallLedgerMessage
   | BranchChangedMessage
+  | BranchesListMessage
   | SessionChangedMessage
   | PeekMessage
   | InboundTriggerMessage
@@ -576,6 +602,13 @@ export interface RequestMcplMessage {
   type: 'request-mcpl';
 }
 
+/** Pull the Chronicle branch listing. Response is a `branches-list` envelope
+ *  routed only to the requesting client. Read-only; switching branches goes
+ *  through the `/checkout` command (full-auth clients only). */
+export interface RequestBranchesMessage {
+  type: 'request-branches';
+}
+
 /** Add or overwrite an MCPL server entry in mcpl-servers.json. Restart is
  *  required for the host to pick up the change; the response is a fresh
  *  `mcpl-list` so the SPA reflects the new state. */
@@ -669,6 +702,7 @@ export type WebUiClientMessage =
   | QuitConfirmMessage
   | RequestLessonsMessage
   | RequestMcplMessage
+  | RequestBranchesMessage
   | McplAddMessage
   | McplRemoveMessage
   | McplSetEnvMessage
@@ -696,6 +730,7 @@ export function isClientMessage(value: unknown): value is WebUiClientMessage {
     case 'ping':
     case 'interrupt':
     case 'request-mcpl':
+    case 'request-branches':
       return true;
     case 'user-message':
       return typeof v.content === 'string';

package/test/codex-subscription-adapter.test.ts

@@ -0,0 +1,226 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import type { ProviderRequest } from '@animalabs/membrane';
+import {
+  CodexSubscriptionAdapter,
+  type CodexAuthProvider,
+} from '../src/codex-subscription-adapter.js';
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+function request(extra: Record<string, unknown> = {}): ProviderRequest {
+  return {
+    model: 'gpt-5.4',
+    messages: [{ type: 'message', role: 'user', content: 'Hello' }],
+    maxTokens: 8192,
+    temperature: 0.2,
+    topP: 0.9,
+    topK: 20,
+    extra,
+  };
+}
+
+function completedResponse(): Response {
+  const item = {
+      type: 'message',
+      id: 'msg_test',
+      role: 'assistant',
+      content: [{ type: 'output_text', text: 'Hello back' }],
+  };
+  const events = [
+    { type: 'response.output_item.done', output_index: 0, item },
+    {
+      type: 'response.completed',
+      response: {
+        id: 'resp_test',
+        model: 'gpt-5.4',
+        status: 'completed',
+        output: [],
+        usage: { input_tokens: 1, output_tokens: 2, total_tokens: 3 },
+      },
+    },
+  ];
+  return new Response(events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join(''), {
+    headers: { 'Content-Type': 'text/event-stream' },
+  });
+}
+
+describe('CodexSubscriptionAdapter', () => {
+  test('uses the subscription endpoint and enables Fast mode per request', async () => {
+    const requests: Array<{ url: string; headers: Headers; body: Record<string, unknown> }> = [];
+    globalThis.fetch = async (input, init) => {
+      requests.push({
+        url: String(input),
+        headers: new Headers(init?.headers),
+        body: JSON.parse(String(init?.body)),
+      });
+      return completedResponse();
+    };
+    const auth: CodexAuthProvider = {
+      getAccessToken: async () => 'subscription-token',
+      getAccountId: () => 'account-test',
+    };
+    const adapter = new CodexSubscriptionAdapter({
+      authProvider: auth,
+      baseURL: 'https://example.test/backend-api/codex/',
+      fastMode: true,
+    });
+
+    const response = await adapter.complete(request({ max_output_tokens: 999 }));
+
+    expect(response.stopReason).toBe('end_turn');
+    expect((response.content as Array<{ text?: string }>)[0]?.text).toBe('Hello back');
+    expect(requests).toHaveLength(1);
+    expect(requests[0]?.url).toBe('https://example.test/backend-api/codex/responses');
+    expect(requests[0]?.headers.get('authorization')).toBe('Bearer subscription-token');
+    expect(requests[0]?.headers.get('chatgpt-account-id')).toBe('account-test');
+    expect(requests[0]?.body.service_tier).toBe('priority');
+    expect(requests[0]?.body.max_output_tokens).toBeUndefined();
+    expect(requests[0]?.body.temperature).toBeUndefined();
+    expect(requests[0]?.body.top_p).toBeUndefined();
+    expect(requests[0]?.body.input).toEqual([{
+      type: 'message',
+      role: 'user',
+      content: [{ type: 'input_text', text: 'Hello' }],
+    }]);
+  });
+
+  test('normalizes maintenance text, images, and tool blocks at the transport boundary', async () => {
+    let body: Record<string, any> = {};
+    globalThis.fetch = async (_input, init) => {
+      body = JSON.parse(String(init?.body));
+      return completedResponse();
+    };
+    const adapter = new CodexSubscriptionAdapter({
+      authProvider: { getAccessToken: async () => 'subscription-token' },
+      baseURL: 'https://example.test/codex',
+    });
+
+    await adapter.complete({
+      model: 'gpt-5.4',
+      messages: [
+        {
+          type: 'message', role: 'user', content: [
+            { type: 'text', text: 'inspect' },
+            { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'aGVsbG8=' } },
+          ],
+        },
+        {
+          type: 'message', role: 'assistant', content: [
+            { type: 'tool_use', id: 'call_1', name: 'lookup', input: { q: 'x' } },
+          ],
+        },
+        {
+          type: 'message', role: 'user', content: [
+            { type: 'tool_result', tool_use_id: 'call_1', content: 'found' },
+          ],
+        },
+      ] as any,
+      maxTokens: 1024,
+    });
+
+    expect(body.input).toEqual([
+      {
+        type: 'message', role: 'user', content: [
+          { type: 'input_text', text: 'inspect' },
+          { type: 'input_image', image_url: 'data:image/png;base64,aGVsbG8=' },
+        ],
+      },
+      { type: 'function_call', call_id: 'call_1', name: 'lookup', arguments: '{"q":"x"}' },
+      { type: 'function_call_output', call_id: 'call_1', output: 'found' },
+    ]);
+  });
+
+  test('turns Fast mode off without reconstructing the adapter', async () => {
+    const bodies: Record<string, unknown>[] = [];
+    globalThis.fetch = async (_input, init) => {
+      bodies.push(JSON.parse(String(init?.body)));
+      return completedResponse();
+    };
+    const adapter = new CodexSubscriptionAdapter({
+      authProvider: { getAccessToken: async () => 'subscription-token' },
+      baseURL: 'https://example.test/codex',
+      fastMode: true,
+    });
+
+    await adapter.complete(request());
+    adapter.setFastMode(false);
+    await adapter.complete(request({ service_tier: 'priority' }));
+
+    expect(bodies[0]?.service_tier).toBe('priority');
+    expect(bodies[1]?.service_tier).toBeUndefined();
+  });
+
+  test('refreshes the ChatGPT token once after a 401', async () => {
+    const refreshFlags: boolean[] = [];
+    let calls = 0;
+    globalThis.fetch = async () => {
+      calls += 1;
+      if (calls === 1) return new Response('expired', { status: 401 });
+      return completedResponse();
+    };
+    const adapter = new CodexSubscriptionAdapter({
+      authProvider: {
+        getAccessToken: async (forceRefresh = false) => {
+          refreshFlags.push(forceRefresh);
+          return forceRefresh ? 'fresh-token' : 'expired-token';
+        },
+      },
+      baseURL: 'https://example.test/codex',
+    });
+
+    await adapter.complete(request());
+
+    expect(calls).toBe(2);
+    expect(refreshFlags).toEqual([false, true]);
+  });
+
+  test('reconstructs tool calls when the terminal event has an empty output', async () => {
+    const item = {
+      type: 'function_call',
+      id: 'fc_test',
+      call_id: 'call_test',
+      name: 'lookup',
+      arguments: '{"query":"connectome"}',
+    };
+    globalThis.fetch = async () => new Response([
+      `data: ${JSON.stringify({ type: 'response.output_item.done', output_index: 0, item })}\n\n`,
+      `data: ${JSON.stringify({
+        type: 'response.completed',
+        response: {
+          model: 'gpt-5.4', status: 'completed', output: [],
+          usage: { input_tokens: 2, output_tokens: 3 },
+        },
+      })}\n\n`,
+    ].join(''), { headers: { 'Content-Type': 'text/event-stream' } });
+    const adapter = new CodexSubscriptionAdapter({
+      authProvider: { getAccessToken: async () => 'subscription-token' },
+      baseURL: 'https://example.test/codex',
+    });
+
+    const response = await adapter.complete(request());
+
+    expect(response.stopReason).toBe('tool_use');
+    expect(response.content).toEqual([expect.objectContaining({
+      type: 'tool_use', id: 'call_test', name: 'lookup', input: { query: 'connectome' },
+    })]);
+  });
+
+  test('surfaces nested SSE error details', async () => {
+    globalThis.fetch = async () => new Response(
+      'data: {"type":"error","error":{"type":"invalid_request_error","code":"context_length_exceeded","message":"input is too large"}}\n\n',
+      { headers: { 'Content-Type': 'text/event-stream' } },
+    );
+    const adapter = new CodexSubscriptionAdapter({
+      authProvider: { getAccessToken: async () => 'subscription-token' },
+      baseURL: 'https://example.test/codex',
+    });
+
+    await expect(adapter.complete(request())).rejects.toThrow(
+      /context_length_exceeded.*input is too large/,
+    );
+  });
+});

package/test/commands-checkpoint-restore.test.ts

@@ -0,0 +1,118 @@
+import { describe, test, expect } from 'bun:test';
+import { handleCommand, createBranchState } from '../src/commands.js';
+
+// Regression tests for /checkpoint + /restore POSITION semantics. The
+// original bug: checkpoints stored only a branch name, so /restore switched
+// to the branch HEAD — including everything after the checkpoint — rolling
+// back nothing, silently. These tests run over a stub ContextManager that
+// mimics Chronicle's contract: branchAt resolves ids against the CURRENT
+// branch's view of the log and throws for unreachable ids.
+
+interface StubMessage { id: string; participant: string; content: unknown[] }
+
+function makeStubWorld() {
+  const messagesByBranch = new Map<string, StubMessage[]>([['main', []]]);
+  let currentName = 'main';
+  let msgCounter = 0;
+
+  const cm = {
+    currentBranch: () => ({ id: currentName, name: currentName, head: messagesByBranch.get(currentName)!.length }),
+    listBranches: () => [...messagesByBranch.keys()].map(name => ({ id: name, name, head: messagesByBranch.get(name)!.length })),
+    queryMessages: (_q: unknown) => ({ messages: messagesByBranch.get(currentName)! }),
+    branchAt: (messageId: string, newName: string): string => {
+      const msgs = messagesByBranch.get(currentName)!;
+      const idx = msgs.findIndex(m => m.id === messageId);
+      if (idx === -1) throw new Error(`Message not found: ${messageId}`);
+      messagesByBranch.set(newName, msgs.slice(0, idx + 1));
+      return newName;
+    },
+    switchBranch: async (name: string): Promise<void> => {
+      if (!messagesByBranch.has(name)) throw new Error(`No such branch: ${name}`);
+      currentName = name;
+    },
+  };
+
+  const addMessage = (participant = 'user'): StubMessage => {
+    const msg: StubMessage = { id: `m${++msgCounter}`, participant, content: [] };
+    messagesByBranch.get(currentName)!.push(msg);
+    return msg;
+  };
+
+  const app = {
+    framework: {
+      getAgent: () => undefined,
+      getAllAgents: () => [{ getContextManager: () => cm }],
+      getAllModules: () => [],
+    },
+    branchState: createBranchState(),
+    userMessageCount: 0,
+  } as any;
+
+  return { cm, app, addMessage, branchCount: () => messagesByBranch.size, currentName: () => currentName };
+}
+
+describe('/checkpoint + /restore position semantics', () => {
+  test('checkpoint records the last message id, not just the branch', () => {
+    const { app, addMessage } = makeStubWorld();
+    addMessage();
+    const last = addMessage('agent');
+    handleCommand('/checkpoint cp', app);
+    const point = app.branchState.checkpoints.get('cp');
+    expect(point.branchName).toBe('main');
+    expect(point.messageId).toBe(last.id);
+  });
+
+  test('restore rolls back to the checkpoint position, not the branch head', async () => {
+    const { app, addMessage, currentName } = makeStubWorld();
+    addMessage();
+    const cpMsg = addMessage('agent');
+    handleCommand('/checkpoint cp', app);
+    addMessage();
+    addMessage('agent'); // work after the checkpoint that must be rolled back
+
+    const result = handleCommand('/restore cp', app);
+    const outcome = await result.asyncWork!;
+    expect(outcome.branchChanged).toBe(true);
+    expect(currentName().startsWith('restore-cp-')).toBe(true);
+
+    const { messages } = (app.framework.getAllAgents()[0].getContextManager() as any).queryMessages({});
+    expect(messages[messages.length - 1].id).toBe(cpMsg.id);
+  });
+
+  test('restoring while already at the checkpoint is a no-op — no branch minted', async () => {
+    const { app, addMessage, branchCount } = makeStubWorld();
+    addMessage();
+    addMessage('agent');
+    handleCommand('/checkpoint cp', app);
+    addMessage();
+
+    await handleCommand('/restore cp', app).asyncWork!;
+    const branchesAfterFirst = branchCount();
+
+    // Second restore at the same position: the guard must hold even though
+    // we're now on restore-cp-… rather than the original branch (the guard
+    // used to compare branch names and died after the first restore,
+    // minting a sibling branch per repeat).
+    const second = handleCommand('/restore cp', app);
+    expect(second.asyncWork).toBeUndefined();
+    expect(second.lines[0]!.text).toContain('Already at checkpoint');
+    expect(branchCount()).toBe(branchesAfterFirst);
+  });
+
+  test('unreachable checkpoint position degrades to the branch head with a note', async () => {
+    const { app, cm, addMessage, currentName } = makeStubWorld();
+    const early = addMessage();
+    addMessage('agent');
+    handleCommand('/checkpoint cp', app);
+
+    // Simulate /undo: branch truncated BEFORE the checkpoint message, so the
+    // checkpoint id is unreachable from the current branch's view.
+    const undoBranch = cm.branchAt(early.id, 'undo-1');
+    await cm.switchBranch(undoBranch);
+
+    const result = handleCommand('/restore cp', app);
+    const outcome = await result.asyncWork!;
+    expect(currentName()).toBe('main');
+    expect(outcome.lines.some(l => l.text.includes('unreachable'))).toBe(true);
+  });
+});

package/test/fast-command.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from 'bun:test';
+import type { AgentFramework } from '@animalabs/agent-framework';
+import { handleCommand } from '../src/commands.js';
+
+function app(adapter?: { enabled: boolean }) : Parameters<typeof handleCommand>[1] {
+  return {
+    framework: {} as AgentFramework,
+    sessionManager: {} as never,
+    recipe: { name: 'test' } as never,
+    branchState: {} as never,
+    codexAdapter: adapter ? {
+      isFastMode: () => adapter.enabled,
+      setFastMode: (enabled) => { adapter.enabled = enabled; },
+    } : undefined,
+    switchSession: async () => {},
+  };
+}
+
+describe('/fast', () => {
+  test('reports that the command requires the Codex subscription provider', () => {
+    expect(handleCommand('/fast on', app()).lines[0]?.text).toMatch(/openai-codex/);
+  });
+
+  test('toggles and reports Fast mode', () => {
+    const state = { enabled: false };
+
+    expect(handleCommand('/fast', app(state)).lines[0]?.text).toMatch(/OFF/);
+    expect(handleCommand('/fast on', app(state)).lines[0]?.text).toMatch(/requested/);
+    expect(state.enabled).toBe(true);
+    expect(handleCommand('/fast status', app(state)).lines[0]?.text).toMatch(/ON/);
+    expect(handleCommand('/fast off', app(state)).lines[0]?.text).toMatch(/disabled/);
+    expect(state.enabled).toBe(false);
+  });
+
+  test('rejects unknown modes', () => {
+    expect(handleCommand('/fast turbo', app({ enabled: false })).lines[0]?.text)
+      .toBe('Usage: /fast [on|off|status]');
+  });
+});