@animalabs/connectome-host 0.3.5 → 0.3.8

package/.env.example

@@ -1,5 +1,11 @@
 ANTHROPIC_API_KEY=sk-ant-...
 # MODEL=claude-opus-4-6
+# Agent-visible wall clock (IANA zone; recipe agent.timezone takes precedence)
+# AGENT_TIMEZONE=America/Los_Angeles
+
+# For recipes with agent.provider="openai-responses":
+# OPENAI_API_KEY=sk-...
+# OPENAI_BASE_URL=https://api.openai.com/v1
 
 # --- Recipe ${VAR} substitutions ---------------------------------------
 # Recipes in recipes/ reference these via ${VAR}.  Unset = that branch of

package/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    name: Build & Test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      # Both platforms on purpose: a package-lock.json regenerated over an
+      # existing node_modules tree records only that machine's native binaries
+      # (esbuild/rollup/tailwind-oxide), so a lock made on macOS breaks Linux
+      # installs and vice versa. Each runner catches the lock the other's
+      # platform produced. macOS runs the install+build lock guard only;
+      # the full test suite runs on ubuntu.
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.14
+
+      - name: Install dependencies
+        run: npm install
+
+      # npm ci is the actual lockfile guard: `npm install` (npm >= 11)
+      # silently re-resolves platform packages missing from the lock, so a
+      # broken lock sails through it. npm ci installs the lock verbatim and
+      # the vite build then fails loudly on the missing rollup binary.
+      - name: Build web assets (strict lockfile)
+        run: npm run build:web:ci
+
+      - name: Test
+        if: matrix.os == 'ubuntu-latest'
+        run: npm test

package/.github/workflows/publish.yml

@@ -31,7 +31,7 @@ jobs:
         run: npm install
 
       - name: Build web assets
-        run: npm run build:web
+        run: npm run build:web:ci
 
       - name: Test
         run: npm test
@@ -64,7 +64,7 @@ jobs:
         run: npm install
 
       - name: Build web assets
-        run: npm run build:web
+        run: npm run build:web:ci
 
       - name: Publish
         run: npm publish --access public --provenance

package/README.md

@@ -27,6 +27,7 @@ A recipe is a JSON file that configures everything domain-specific:
   "agent": {
     "name": "researcher",
     "model": "claude-opus-4-6",
+    "timezone": "America/Los_Angeles",
     "systemPrompt": "You are a ...",
     "maxTokens": 16384,
     "strategy": {
@@ -55,6 +56,10 @@ A recipe is a JSON file that configures everything domain-specific:
 }
 ```
 
+`agent.timezone` is an IANA zone used only for times rendered to the agent.
+Chronicle and MCPL protocol timestamps remain epoch/UTC. If the recipe omits
+it, `AGENT_TIMEZONE` is used, then the process timezone.
+
 ### Recipe loading
 
 | Command | Behavior |

package/bun.lock

@@ -5,10 +5,10 @@
     "": {
       "name": "connectome-host",
       "dependencies": {
-        "@animalabs/agent-framework": "^0.6.0",
+        "@animalabs/agent-framework": "^0.6.7",
         "@animalabs/chronicle": "^0.2.0",
-        "@animalabs/context-manager": "^0.5.5",
-        "@animalabs/membrane": "^0.5.68",
+        "@animalabs/context-manager": "^0.5.12",
+        "@animalabs/membrane": "^0.5.71",
         "@opentui/core": "^0.1.82",
       },
       "devDependencies": {
@@ -19,13 +19,13 @@
     },
   },
   "packages": {
-    "@animalabs/agent-framework": ["@animalabs/agent-framework@0.6.0", "", { "dependencies": { "@animalabs/chronicle": "^0.2.0", "@animalabs/context-manager": "^0.5.5", "@animalabs/membrane": "^0.5.64", "chokidar": "^4.0.3", "discord.js": "^14.25.1", "ws": "^8.18.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js" } }, "sha512-LsR2eYveMkC+aZTq0a58bEYoi8+Iq3XQSrSCZ1fbcg+mf9YNOk8ooBRUl0VM03fyPymdOf/fkVx2tdMZM7HjSQ=="],
+    "@animalabs/agent-framework": ["@animalabs/agent-framework@0.6.7", "", { "dependencies": { "@animalabs/chronicle": "^0.2.2", "@animalabs/context-manager": "^0.5.12", "@animalabs/membrane": "^0.5.73", "chokidar": "^4.0.3", "discord.js": "^14.25.1", "ws": "^8.18.0" }, "bin": { "agent-framework-mcp": "dist/src/api/mcp-server.js", "agent-framework-recover": "dist/src/recovery/recover-cli.js" } }, "sha512-I6hOhmF75AQDeyd2r0JFaR2QHyEAXiVQlr5MgsriUTcFJbtZM7n+yd4aiWbqeXGDeEHjbEpkiifn7vMeOfIeog=="],
 
     "@animalabs/chronicle": ["@animalabs/chronicle@0.2.1", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.1", "@animalabs/chronicle-darwin-x64": "0.2.1", "@animalabs/chronicle-linux-arm64-gnu": "0.2.1", "@animalabs/chronicle-linux-x64-gnu": "0.2.1", "@animalabs/chronicle-win32-x64-msvc": "0.2.1" } }, "sha512-rDFc069yfi7BQUusgsXBwBdqljUWLByXSYaTF40AP+tonBh0No3eF9VzKTSy1I8DYg/jAUHIKtVdKDGsVMVubw=="],
 
-    "@animalabs/context-manager": ["@animalabs/context-manager@0.5.5", "", { "dependencies": { "@animalabs/chronicle": "^0.2.0", "@animalabs/membrane": "^0.5.64" } }, "sha512-KWTluwU5VIZKIPF/IdfUbkvPNZ5zMxSfZjaxZb81IXe+DBPmjHuUVNIqgXIQ2Mv1pCn1vCNqieZ/iSrc6dFH8w=="],
+    "@animalabs/context-manager": ["@animalabs/context-manager@0.5.12", "", { "dependencies": { "@animalabs/chronicle": "^0.2.6", "@animalabs/membrane": "^0.5.69" } }, "sha512-V/TTnIuvFtVYu+A9UTi7A0Q8gCuMTRUatt27JuC9nSDVIQ5L2sMlnsVGbIS8rqOkB8i9o5+Rq/itH5wZVQgaVA=="],
 
-    "@animalabs/membrane": ["@animalabs/membrane@0.5.68", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-MfSERy0ECxdBZ4NelHdZbqsP/ORWJsfeAI6vuyy6gP77aGcdJL8qf4XrUkOox5yZa5MqB50y0K58Ffv79jCnbg=="],
+    "@animalabs/membrane": ["@animalabs/membrane@0.5.71", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-Jos4Fh/kIbpOiJ43LKIFpmaCmWIzE6ly1x/4c5iHaMw8n6D8OJ2f4va7xo3vNdvfKWBbln4QghmNg4NWo3oFGA=="],
 
     "@anthropic-ai/sdk": ["@anthropic-ai/sdk@0.52.0", "", { "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-d4c+fg+xy9e46c8+YnrrgIQR45CZlAi7PwdzIfDXDM6ACxEZli1/fxhURsq30ZpMZy6LvSkr41jGq5aF5TD7rQ=="],
 
@@ -275,6 +275,14 @@
 
     "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
 
+    "@animalabs/agent-framework/@animalabs/chronicle": ["@animalabs/chronicle@0.2.6", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.6", "@animalabs/chronicle-darwin-x64": "0.2.6", "@animalabs/chronicle-linux-arm64-gnu": "0.2.6", "@animalabs/chronicle-linux-x64-gnu": "0.2.6", "@animalabs/chronicle-win32-x64-msvc": "0.2.6" } }, "sha512-+gbt2GR4SP8MnKxeqkJZf6oZn339fLiBtk6GHyBD/gHQ4e4eFqBpTaTd5eKycKBws0xWGcOqyiJFH4IdBkweUA=="],
+
+    "@animalabs/agent-framework/@animalabs/membrane": ["@animalabs/membrane@0.5.73", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-w1rt/JVOD6dWwEO54tfR0yrLzwwD45cpYJ9hWJhHxs8k9FvW1PgIIV1KmNFNbpY8MR9HC5g7Lqgvhzs3pDst+g=="],
+
+    "@animalabs/context-manager/@animalabs/chronicle": ["@animalabs/chronicle@0.2.6", "", { "optionalDependencies": { "@animalabs/chronicle-darwin-arm64": "0.2.6", "@animalabs/chronicle-darwin-x64": "0.2.6", "@animalabs/chronicle-linux-arm64-gnu": "0.2.6", "@animalabs/chronicle-linux-x64-gnu": "0.2.6", "@animalabs/chronicle-win32-x64-msvc": "0.2.6" } }, "sha512-+gbt2GR4SP8MnKxeqkJZf6oZn339fLiBtk6GHyBD/gHQ4e4eFqBpTaTd5eKycKBws0xWGcOqyiJFH4IdBkweUA=="],
+
+    "@animalabs/context-manager/@animalabs/membrane": ["@animalabs/membrane@0.5.73", "", { "dependencies": { "@anthropic-ai/sdk": "^0.52.0" } }, "sha512-w1rt/JVOD6dWwEO54tfR0yrLzwwD45cpYJ9hWJhHxs8k9FvW1PgIIV1KmNFNbpY8MR9HC5g7Lqgvhzs3pDst+g=="],
+
     "@discordjs/rest/@discordjs/collection": ["@discordjs/collection@2.1.1", "", {}, "sha512-LiSusze9Tc7qF03sLCujF5iZp7K+vRNEDBZ86FT9aQAv3vxMLihUvKvpsCWiQ2DJq1tVckopKm1rxomgNUc9hg=="],
 
     "@discordjs/rest/@sapphire/snowflake": ["@sapphire/snowflake@3.5.5", "", {}, "sha512-xzvBr1Q1c4lCe7i6sRnrofxeO1QTP/LKQ6A6qy0iB4x5yfiSfARMEQEghojzTNALDTcv8En04qYNIco9/K9eZQ=="],

package/docs/AGENT-ONBOARDING.md

@@ -239,11 +239,12 @@ ln -sfn ../../../connectome-local/context-manager/node_modules/@animalabs/chroni
   "agent": {
     "name": "<agent>",                      // = chronicle "self" participant
     "model": "<model-id>",                  // or gateway-prefixed, e.g. anthropic/claude-opus-4
+    "timezone": "America/Los_Angeles",      // agent-visible wall clock only; storage stays UTC
     "systemPrompt": "<persona / or minimal>",
     "maxTokens": 16384,                     // response cap
     "maxStreamTokens": 180000,              // recompile trigger; keep < model window
     "contextBudgetTokens": 160000,          // SEE §11.1 — MUST fit under (window - maxTokens)
-    "cacheTtl": "1h",                       // prompt-cache TTL; '1h' for residents replying slower than 5m (cache re-write premium dominates spend otherwise), omit/'5m' for rapid loops
+    "cacheTtl": "1h",                       // prompt-cache TTL; defaults to '1h', set '5m' explicitly for rapid sub-5m loops
     "strategy": {
       "type": "autobiographical",
       "headWindowTokens": 4000,
@@ -266,6 +267,10 @@ ln -sfn ../../../connectome-local/context-manager/node_modules/@animalabs/chroni
 }
 ```
 
+Use `"cacheTtl": "1h"` for Connectome deployments. This is also the runtime
+default when the field is omitted. Set `"5m"` only for intentionally rapid
+workloads whose cache is normally reused within five minutes.
+
 **`.env`** (`chmod 600`). Common vars:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animalabs/connectome-host",
-  "version": "0.3.5",
+  "version": "0.3.8",
   "description": "General-purpose agent TUI host with recipe-based configuration",
   "type": "module",
   "scripts": {
@@ -8,13 +8,15 @@
     "dev": "bun --watch src/index.ts",
     "test": "bun test",
     "build:web": "npm --prefix web install && npm --prefix web run build",
+    "build:web:ci": "npm ci --prefix web && npm --prefix web run build",
+    "relock:web": "rm -rf web/node_modules web/package-lock.json && npm --prefix web install",
     "postinstall": "test -d web && npm --prefix web install && npm --prefix web run build || true"
   },
   "dependencies": {
-    "@animalabs/agent-framework": "^0.6.0",
+    "@animalabs/agent-framework": "^0.6.7",
     "@animalabs/chronicle": "^0.2.0",
-    "@animalabs/context-manager": "^0.5.5",
-    "@animalabs/membrane": "^0.5.68",
+    "@animalabs/context-manager": "^0.5.12",
+    "@animalabs/membrane": "^0.5.71",
     "@opentui/core": "^0.1.82"
   },
   "devDependencies": {

package/scripts/import-codex-rollout.ts

@@ -0,0 +1,288 @@
+#!/usr/bin/env bun
+/** Import a Codex rollout JSONL as a KV-stable OpenAI Responses session. */
+
+import {
+  basename,
+  dirname,
+  join,
+  resolve,
+} from 'node:path';
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { JsStore } from '@animalabs/chronicle';
+import { ContextManager } from '@animalabs/context-manager';
+import type { ContentBlock } from '@animalabs/membrane';
+import { SessionManager } from '../src/session-manager.js';
+
+interface RolloutRecord {
+  timestamp?: string;
+  type?: string;
+  payload?: Record<string, unknown>;
+}
+
+interface NativeItem {
+  type?: string;
+  id?: string;
+  role?: string;
+  [key: string]: unknown;
+}
+
+interface EffectiveItem {
+  item: NativeItem;
+  timestamp?: string;
+  sourceLine: number;
+  restoredByCompaction: boolean;
+}
+
+function usage(): never {
+  console.error('Usage: bun scripts/import-codex-rollout.ts <rollout.jsonl> --out <instance-dir> [--agent <name>]');
+  process.exit(1);
+}
+
+function parseArgs(argv: string[]) {
+  const args = argv.slice(2);
+  if (!args[0] || args[0].startsWith('-')) usage();
+  const source = resolve(args[0]);
+  let outDir = '';
+  let agentName = 'Codex';
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--out') outDir = resolve(args[++i] ?? '');
+    else if (args[i] === '--agent') agentName = args[++i] ?? usage();
+    else usage();
+  }
+  if (!outDir) usage();
+  return { source, outDir, agentName };
+}
+
+/** Reconstruct the provider's current input window. A `compacted` record
+ * replaces all prior response-item history with its canonical
+ * `replacement_history`; later response items append normally. */
+export function reconstructEffectiveHistory(records: RolloutRecord[]): EffectiveItem[] {
+  let history: EffectiveItem[] = [];
+  for (const [index, record] of records.entries()) {
+    if (record.type === 'compacted') {
+      const replacement = record.payload?.replacement_history;
+      if (Array.isArray(replacement)) {
+        history = replacement.map(item => ({
+          item: item as NativeItem,
+          timestamp: record.timestamp,
+          sourceLine: index + 1,
+          restoredByCompaction: true,
+        }));
+      }
+      continue;
+    }
+    if (record.type === 'response_item' && record.payload) {
+      history.push({
+        item: record.payload as NativeItem,
+        timestamp: record.timestamp,
+        sourceLine: index + 1,
+        restoredByCompaction: false,
+      });
+    }
+  }
+  return history;
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map(part => {
+      if (!part || typeof part !== 'object') return '';
+      const value = part as Record<string, unknown>;
+      return typeof value.text === 'string' ? value.text
+        : typeof value.refusal === 'string' ? value.refusal
+        : '';
+    })
+    .filter(Boolean)
+    .join('\n');
+}
+
+/** A human-readable Chronicle projection. `rawItem` is the load-bearing field:
+ * the Responses formatter emits it verbatim and ignores the projection. */
+export function projectItem(item: NativeItem): ContentBlock[] {
+  const carrier = <T extends ContentBlock>(block: T): ContentBlock =>
+    ({ ...block, rawItem: item } as ContentBlock);
+
+  switch (item.type) {
+    case 'message':
+      return [carrier({ type: 'text', text: textFromContent(item.content) })];
+    case 'reasoning':
+      if (typeof item.encrypted_content === 'string') {
+        return [carrier({ type: 'redacted_thinking', data: item.encrypted_content })];
+      }
+      return [carrier({ type: 'thinking', thinking: textFromContent(item.summary) })];
+    case 'compaction':
+      return [carrier({
+        type: 'redacted_thinking',
+        data: typeof item.encrypted_content === 'string' ? item.encrypted_content : '',
+      })];
+    case 'function_call':
+      return [carrier({
+        type: 'tool_use',
+        id: String(item.call_id ?? item.id ?? ''),
+        name: String(item.name ?? ''),
+        input: (() => {
+          try { return JSON.parse(String(item.arguments ?? '{}')) as Record<string, unknown>; }
+          catch { return { _rawArguments: item.arguments }; }
+        })(),
+      })];
+    case 'function_call_output':
+      return [carrier({
+        type: 'tool_result',
+        toolUseId: String(item.call_id ?? ''),
+        content: typeof item.output === 'string' ? item.output : JSON.stringify(item.output ?? null),
+      })];
+    default:
+      // Custom tool calls/outputs and future item types stay opaque. The
+      // zero-width projection avoids injecting synthetic text into the model.
+      return [carrier({ type: 'text', text: '' })];
+  }
+}
+
+function participantFor(item: NativeItem, agentName: string): string {
+  if (item.type === 'message') return item.role === 'assistant' ? agentName : 'user';
+  if (item.type === 'reasoning' || item.type === 'compaction' ||
+      item.type === 'function_call' || item.type === 'custom_tool_call') return agentName;
+  return 'user';
+}
+
+function writeRecipe(instanceDir: string, agentName: string): string {
+  const recipeDir = join(instanceDir, 'recipes');
+  mkdirSync(recipeDir, { recursive: true });
+  const path = join(recipeDir, 'codex-rollout.json');
+  const recipe = {
+    name: `${agentName} rollout revival`,
+    description: 'Stateless OpenAI Responses continuation imported from a Codex rollout.',
+    version: '1',
+    agent: {
+      name: agentName,
+      provider: 'openai-responses',
+      model: 'gpt-5.6-sol',
+      systemPrompt: 'The native imported Responses history contains the authoritative developer and system instructions.',
+      maxTokens: 128000,
+      maxStreamTokens: 900000,
+      contextBudgetTokens: 1000000,
+      strategy: { type: 'passthrough' },
+      responses: {
+        reasoningEffort: 'high',
+        reasoningContext: 'all_turns',
+        compactThreshold: 850000,
+      },
+    },
+    modules: {
+      subagents: false,
+      lessons: false,
+      retrieval: false,
+      wake: false,
+    },
+  };
+  writeFileSync(path, JSON.stringify(recipe, null, 2) + '\n');
+  return path;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+  const raw = readFileSync(opts.source, 'utf8');
+  const records = raw.trim().split('\n').filter(Boolean).map((line, index) => {
+    try { return JSON.parse(line) as RolloutRecord; }
+    catch (error) { throw new Error(`Invalid JSON at ${opts.source}:${index + 1}: ${String(error)}`); }
+  });
+  const history = reconstructEffectiveHistory(records);
+  if (history.length === 0) throw new Error('Rollout contains no effective response items.');
+
+  const dataDir = join(opts.outDir, 'data');
+  const sourceDir = join(opts.outDir, 'source');
+  mkdirSync(sourceDir, { recursive: true });
+  const snapshotPath = join(sourceDir, basename(opts.source));
+  writeFileSync(snapshotPath, raw);
+
+  const sessionManager = new SessionManager(dataDir);
+  const session = sessionManager.createSession(`Codex ${basename(opts.source).replace(/^rollout-|\.jsonl$/g, '')}`);
+  const storePath = sessionManager.getStorePath(session.id);
+  const store = JsStore.openOrCreate({ path: storePath });
+  try {
+    const cm = await ContextManager.open({ store });
+    try {
+      for (const entry of history) {
+        cm.addMessage(
+          participantFor(entry.item, opts.agentName),
+          projectItem(entry.item),
+          {
+            sourceId: entry.item.id ?? `rollout-line-${entry.sourceLine}`,
+            codexRollout: {
+              sourceLine: entry.sourceLine,
+              sourceTimestamp: entry.timestamp,
+              restoredByCompaction: entry.restoredByCompaction,
+              nativeType: entry.item.type,
+            },
+          },
+        );
+      }
+    } finally {
+      await cm.close?.();
+    }
+  } finally {
+    store.close?.();
+  }
+
+  const meta = records.find(record => record.type === 'session_meta')?.payload ?? {};
+  const turnContexts = records.filter(record => record.type === 'turn_context');
+  const latestTurn = turnContexts.at(-1)?.payload ?? {};
+  const compacted = records.filter(record => record.type === 'compacted');
+  const sidecarPath = join(dirname(storePath), `${session.id}.import-source.json`);
+  writeFileSync(sidecarPath, JSON.stringify({
+    source: opts.source,
+    snapshot: snapshotPath,
+    agentName: opts.agentName,
+    importedAt: new Date().toISOString(),
+    originalRecordCount: records.length,
+    importedMessageCount: history.length,
+    effectiveItemCount: history.length,
+    compactionCount: compacted.length,
+    latestWindowId: compacted.at(-1)?.payload?.window_id ?? null,
+    model: latestTurn.model ?? 'gpt-5.6-sol',
+    sessionMeta: meta,
+  }, null, 2) + '\n');
+
+  const index = sessionManager.load();
+  index.sessions[session.id]!.messageCount = history.length;
+  sessionManager.save(index);
+  const recipePath = writeRecipe(opts.outDir, opts.agentName);
+  writeFileSync(join(opts.outDir, '.env.example'), [
+    `DATA_DIR=${dataDir}`,
+    'OPENAI_API_KEY=',
+    '',
+  ].join('\n'));
+  writeFileSync(join(opts.outDir, 'README.md'), [
+    '# Codex rollout Connectome instance',
+    '',
+    `Imported from \`${opts.source}\`.`,
+    '',
+    'Run from the connectome-host checkout:',
+    '',
+    '```sh',
+    `DATA_DIR=${dataDir} OPENAI_API_KEY=... bun src/index.ts ${recipePath}`,
+    '```',
+    '',
+    'The session uses provider-native Responses items and passthrough context management.',
+    'Do not run the Claude warmup importer; it would normalize the native prefix.',
+    '',
+  ].join('\n'));
+
+  console.log(JSON.stringify({
+    instanceDir: opts.outDir,
+    dataDir,
+    recipePath,
+    sessionId: session.id,
+    importedItems: history.length,
+    compactions: compacted.length,
+    snapshotPath,
+  }, null, 2));
+}
+
+if (import.meta.main) await main();