orca/src/shared/structured-agent-session-create.ts

import type { AgentSessionHandleProvider } from './agent-session-provider-handle'
import type { AgentSessionMutationEnvelope } from './agent-session-wire'
import {
  createStructuredAgentSessionOperationId,
  structuredAgentSessionCreateFingerprint
} from './structured-agent-session-mutation'

/**
 * The conversation a create adopts instead of starting a fresh one.
 *
 * Deliberately carries an identity and nothing else. The transcript file and the account home it
 * lives under are derived by the executing host, never sent: `agentSession.create` is reachable by
 * paired mobile clients, and a client-supplied path would let one choose which file the host reads
 * into a journal and which credential directory the provider child launches against.
 */
export type StructuredAgentSessionResumeSource = {
  /** claude: the session id. codex: the thread id. */
  providerSessionId: string
}

export type StructuredAgentSessionCreateParams = {
  envelope: AgentSessionMutationEnvelope
  worktree: string
  agent: AgentSessionHandleProvider
  resumeFrom?: StructuredAgentSessionResumeSource
}

/** Provider-prefixed so a session id names its lane on sight, and underscore-only
 *  so the id stays a single token everywhere it is embedded (tab ids, log keys). */
export function createStructuredAgentSessionId(
  agent: AgentSessionHandleProvider,
  randomUuid: () => string
): string {
  return `${agent}_${randomUuid().replaceAll('-', '_')}`
}

/**
 * The durable `agentSession.create` envelope every client replays on an ambiguous
 * transport failure. The fingerprint must be computed over the same fields the host
 * recomputes, so both clients build it here rather than each assembling their own.
 */
export function structuredAgentSessionCreateParams(args: {
  sessionId: string
  worktree: string
  agent: AgentSessionHandleProvider
  resumeFrom?: StructuredAgentSessionResumeSource
  randomUuid: () => string
  now?: number
}): StructuredAgentSessionCreateParams {
  const fields = {
    worktree: args.worktree,
    agent: args.agent,
    ...(args.resumeFrom ? { resumeFrom: args.resumeFrom } : {})
  }
  return {
    envelope: {
      sessionId: args.sessionId,
      clientOperationId: createStructuredAgentSessionOperationId(args.randomUuid, args.now),
      expectedRuntimeFence: null,
      payloadFingerprint: structuredAgentSessionCreateFingerprint({
        sessionId: args.sessionId,
        ...fields
      })
    },
    ...fields
  }
}