Freshcodex contract foundation: canonicalize fresh-agent pane identity and stabilize full suite

scripts/audit-codex-app-server-schema.ts

@@ -0,0 +1,72 @@
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+
+import {
+  CODEX_CLIENT_REQUEST_METHODS,
+  CODEX_RUNTIME_LEAF_VALUES,
+  CODEX_SCHEMA_VERSION,
+  CODEX_SERVER_NOTIFICATION_METHODS,
+  CODEX_SERVER_REQUEST_METHODS,
+  CODEX_THREAD_ITEM_VARIANTS,
+} from '../test/fixtures/coding-cli/codex-app-server/schema-inventory.js'
+
+type JsonSchema = {
+  oneOf?: Array<{ properties?: { method?: { enum?: string[] }; type?: { const?: string; enum?: string[] } } }>
+  definitions?: Record<string, JsonSchema & { enum?: string[] }>
+  enum?: string[]
+}
+
+function readSchema(filePath: string): JsonSchema {
+  return JSON.parse(readFileSync(filePath, 'utf8')) as JsonSchema
+}
+
+function methods(filePath: string): string[] {
+  return (readSchema(filePath).oneOf ?? [])
+    .map((entry) => entry.properties?.method?.enum?.[0])
+    .filter((value): value is string => Boolean(value))
+}
+
+function threadItemVariants(filePath: string): string[] {
+  const schema = readSchema(filePath).definitions?.ThreadItem
+  return (schema?.oneOf ?? [])
+    .map((entry) => entry.properties?.type?.const ?? entry.properties?.type?.enum?.[0])
+    .filter((value): value is string => Boolean(value))
+}
+
+function compare(label: string, expected: readonly string[], actual: readonly string[]): string[] {
+  const missing = expected.filter((value) => !actual.includes(value))
+  const added = actual.filter((value) => !expected.includes(value))
+  const messages: string[] = []
+  if (missing.length > 0) messages.push(`${label} missing from generated schema: ${missing.join(', ')}`)
+  if (added.length > 0) messages.push(`${label} added by generated schema: ${added.join(', ')}`)
+  return messages
+}
+
+const workDir = mkdtempSync(path.join(tmpdir(), 'freshell-codex-schema-audit-'))
+try {
+  const jsonDir = path.join(workDir, 'json')
+  execFileSync('codex', ['app-server', 'generate-json-schema', '--out', jsonDir], { stdio: 'inherit' })
+
+  const failures = [
+    ...compare('client request methods', CODEX_CLIENT_REQUEST_METHODS, methods(path.join(jsonDir, 'ClientRequest.json'))),
+    ...compare('server request methods', CODEX_SERVER_REQUEST_METHODS, methods(path.join(jsonDir, 'ServerRequest.json'))),
+    ...compare('server notification methods', CODEX_SERVER_NOTIFICATION_METHODS, methods(path.join(jsonDir, 'ServerNotification.json'))),
+    ...compare('thread item variants', CODEX_THREAD_ITEM_VARIANTS, threadItemVariants(path.join(jsonDir, 'codex_app_server_protocol.v2.schemas.json'))),
+  ]
+
+  const v2Schema = readSchema(path.join(jsonDir, 'codex_app_server_protocol.v2.schemas.json'))
+  const generatedReasoningEffort = v2Schema.definitions?.ReasoningEffort?.enum ?? []
+  failures.push(...compare('reasoning effort values', CODEX_RUNTIME_LEAF_VALUES.reasoningEffort, generatedReasoningEffort))
+
+  if (failures.length > 0) {
+    console.error(`Codex app-server schema inventory is stale. Checked-in inventory version: ${CODEX_SCHEMA_VERSION}`)
+    for (const failure of failures) console.error(`- ${failure}`)
+    process.exit(1)
+  }
+
+  console.log(`Codex app-server schema inventory matches checked-in ${CODEX_SCHEMA_VERSION} fixture.`)
+} finally {
+  rmSync(workDir, { recursive: true, force: true })
+}

server/agent-api/layout-schema.ts

@@ -1,8 +1,88 @@
 import { z } from 'zod'
 import { SessionLocatorSchema } from '../../shared/ws-protocol.js'
 
+const FreshAgentContentSchema = z.object({
+  kind: z.literal('fresh-agent'),
+  sessionType: z.string().min(1),
+  provider: z.string().min(1),
+  createRequestId: z.string().min(1),
+  status: z.string().min(1),
+  sessionId: z.string().optional(),
+  resumeSessionId: z.string().optional(),
+  sessionRef: z.object({ provider: z.string().min(1), sessionId: z.string().min(1) }).optional(),
+  restoreError: z.object({ code: z.string().min(1), reason: z.string().min(1) }).optional(),
+  initialCwd: z.string().optional(),
+  model: z.string().optional(),
+  modelSelection: z.object({ kind: z.string().min(1), modelId: z.string().min(1) }).optional().or(z.null()),
+  permissionMode: z.string().optional(),
+  sandbox: z.enum(['read-only', 'workspace-write', 'danger-full-access']).optional(),
+  effort: z.string().optional(),
+  plugins: z.array(z.string()).optional(),
+  settingsDismissed: z.boolean().optional(),
+}).passthrough().refine(
+  (v) => !(v.sessionRef && v.restoreError),
+  { message: 'sessionRef and restoreError are mutually exclusive' },
+)
+
 const PaneNodeSchema: z.ZodType<any> = z.lazy(() => z.union([
-  z.object({ type: z.literal('leaf'), id: z.string(), content: z.record(z.string(), z.any()) }),
+  z.object({
+    type: z.literal('leaf'),
+    id: z.string(),
+    content: z.union([
+      z.object({
+        kind: z.literal('terminal'),
+        createRequestId: z.string(),
+        status: z.string(),
+        mode: z.string(),
+        terminalId: z.string().optional(),
+        shell: z.string().optional(),
+        resumeSessionId: z.string().optional(),
+        sessionRef: SessionLocatorSchema.optional(),
+        restoreError: z.object({ code: z.string(), reason: z.string() }).optional(),
+        initialCwd: z.string().optional(),
+      }).passthrough(),
+      z.object({
+        kind: z.literal('browser'),
+        browserInstanceId: z.string(),
+        url: z.string(),
+        devToolsOpen: z.boolean(),
+      }).passthrough(),
+      z.object({
+        kind: z.literal('editor'),
+        filePath: z.string().nullable(),
+        language: z.string().nullable(),
+        readOnly: z.boolean(),
+        content: z.string(),
+        viewMode: z.enum(['source', 'preview']),
+      }).passthrough(),
+      z.object({
+        kind: z.literal('picker'),
+      }).passthrough(),
+      FreshAgentContentSchema,
+      z.object({
+        kind: z.literal('agent-chat'),
+        provider: z.string(),
+        createRequestId: z.string(),
+        status: z.string(),
+        sessionId: z.string().optional(),
+        resumeSessionId: z.string().optional(),
+        sessionRef: SessionLocatorSchema.optional(),
+        restoreError: z.object({ code: z.string(), reason: z.string() }).optional(),
+        initialCwd: z.string().optional(),
+        modelSelection: z.object({ kind: z.string(), modelId: z.string() }).optional().or(z.null()),
+        permissionMode: z.string().optional(),
+        effort: z.string().optional(),
+        plugins: z.array(z.string()).optional(),
+        settingsDismissed: z.boolean().optional(),
+      }).passthrough(),
+      z.object({
+        kind: z.literal('extension'),
+        extensionName: z.string(),
+        props: z.record(z.string(), z.any()),
+      }).passthrough(),
+      z.object({ kind: z.string() }).passthrough(),
+    ]),
+  }),
   z.object({
     type: z.literal('split'),
     id: z.string(),

server/agent-api/layout-store.ts

@@ -100,6 +100,19 @@ export class LayoutStore {
       }
     }
 
+    if (content.kind === 'fresh-agent') {
+      switch (content.sessionType) {
+        case 'freshclaude':
+          return 'Freshclaude'
+        case 'freshcodex':
+          return 'Freshcodex'
+        case 'kilroy':
+          return 'Kilroy'
+        default:
+          return 'Fresh Agent'
+      }
+    }
+
     if (content.kind === 'extension') {
       return typeof content.extensionName === 'string' && content.extensionName
         ? content.extensionName
@@ -145,6 +158,12 @@ export class LayoutStore {
   updateFromUi(snapshot: UiSnapshot, connectionId: string) {
     this.snapshot = snapshot
     this.sourceConnectionId = connectionId
+    for (const tab of snapshot.tabs) {
+      const leaves = this.collectLeaves(snapshot.layouts?.[tab.id], [])
+      for (const leaf of leaves) {
+        this.seedPaneTitle(tab.id, leaf.id, leaf.content)
+      }
+    }
   }
 
   getSourceConnectionId() {

server/agent-timeline/service.ts

@@ -20,7 +20,15 @@ type TimelineCursorPayload = {
 
 type TimelineMessageRecord = CanonicalTurn & { sessionId: string }
 
+export type AgentTimelineSnapshot = {
+  sessionId: string
+  latestTurnId: string | null
+  revision: number
+  turns: CanonicalTurn[]
+}
+
 export type AgentTimelineService = {
+  getSnapshot: (query: { sessionId: string; revision?: number; signal?: AbortSignal }) => Promise<AgentTimelineSnapshot>
   getTimelinePage: (query: AgentTimelinePageQuery & { sessionId: string; signal?: AbortSignal }) => Promise<AgentTimelinePage>
   getTurnBody: (query: AgentTimelineTurnBodyQuery & { sessionId: string; turnId: string; signal?: AbortSignal }) => Promise<AgentTimelineTurn | null>
 }
@@ -134,6 +142,30 @@ export function createAgentTimelineService(deps: AgentTimelineServiceDeps): Agen
   }
 
   return {
+    async getSnapshot({ sessionId, revision, signal }) {
+      throwIfAborted(signal)
+      const timeline = await loadTimeline(sessionId)
+      throwIfAborted(signal)
+      if (revision != null && revision !== timeline.revision) {
+        throw new RestoreStaleRevisionError(revision, timeline.revision)
+      }
+      return {
+        sessionId: timeline.sessionId,
+        latestTurnId: timeline.latestTurnId,
+        revision: timeline.revision,
+        turns: timeline.records
+          .slice()
+          .reverse()
+          .map((record) => ({
+            turnId: record.turnId,
+            messageId: record.messageId,
+            ordinal: record.ordinal,
+            source: record.source,
+            message: record.message,
+          })),
+      }
+    },
+
     async getTimelinePage(query) {
       throwIfAborted(query.signal)
       if (query.revision == null) {

server/claude-session-id.ts

@@ -1,5 +1,5 @@
-const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+import { isCanonicalClaudeSessionId } from '../shared/session-contract.js'
 
 export function isValidClaudeSessionId(value?: string): value is string {
-  return typeof value === 'string' && UUID_REGEX.test(value)
+  return isCanonicalClaudeSessionId(value)
 }