@meistrari/agent-core 0.0.0

package/src/protocol/agent-event.ts

@@ -0,0 +1,391 @@
+import z from 'zod'
+import { jsonValueSchema } from './agent-json'
+import { agentRunMetadataSchema } from './agent-metadata'
+import { agentPayloadOverflowSchema } from './agent-overflow'
+import { agentProviderIdSchema } from './agent-provider'
+import { agentToolCallStatusSchema, agentToolResultSchema } from './agent-tool'
+import { agentUsageSchema } from './agent-usage'
+import { agentUserInputAnswersSchema, agentUserInputQuestionSchema } from './agent-user-input'
+import { agentWorkObservationSchema } from './agent-work'
+
+export interface AgentError {
+    message: string
+    code?: string
+    name?: string
+    stack?: string
+    cause?: AgentError
+}
+
+export const agentErrorSchema: z.ZodType<AgentError> = z.object({
+    message: z.string().min(1),
+    code: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    stack: z.string().min(1).optional(),
+    cause: z.lazy(() => agentErrorSchema).optional(),
+}).strict()
+
+export const agentMessageRoleSchema = z.enum(['user', 'assistant', 'system'])
+export const agentSessionEndReasonSchema = z.enum(['completed', 'stopped', 'interrupted', 'failed'])
+export const agentSessionStateSchema = z.enum(['ready', 'running', 'idle', 'waiting_for_user_input', 'stopping', 'stopped', 'failed'])
+export const agentTurnEndStatusSchema = z.enum(['completed', 'failed', 'cancelled', 'interrupted'])
+export const agentSubagentStatusSchema = z.enum(['completed', 'failed', 'cancelled'])
+export const agentContextCompactionTriggerSchema = z.enum(['manual', 'auto', 'unknown'])
+export const agentContextCompactionStatusSchema = z.enum(['completed', 'failed'])
+export const agentErrorSourceSchema = z.enum(['provider', 'runtime', 'transport', 'unknown'])
+export const agentSkillScopeSchema = z.enum(['user', 'repository', 'system', 'admin'])
+
+export const agentSkillSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().min(1),
+    scope: agentSkillScopeSchema,
+}).strict()
+
+export const agentEventBaseSchema = z.object({
+    eventId: z.string().min(1),
+    provider: agentProviderIdSchema,
+    sessionId: z.string().min(1),
+    providerSessionId: z.string().min(1),
+    timestamp: z.string().datetime(),
+    sequence: z.number().int().nonnegative(),
+}).strict()
+
+export const agentEventActorOriginSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('tool_call'),
+        toolCallId: z.string().min(1),
+    }).strict(),
+    z.object({
+        type: z.literal('provider_task'),
+        taskId: z.string().min(1),
+    }).strict(),
+])
+
+export const agentEventActorSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('main'),
+        actorId: z.literal('main'),
+    }).strict(),
+    z.object({
+        type: z.literal('subagent'),
+        actorId: z.string().min(1),
+        subagentId: z.string().min(1),
+        parentActorId: z.string().min(1),
+        origin: agentEventActorOriginSchema,
+        parentToolCallId: z.string().min(1).optional(),
+        name: z.string().min(1).optional(),
+    }).strict(),
+])
+
+const subagentRefSchema = z.object({
+    subagentId: z.string().min(1),
+    actorId: z.string().min(1),
+    parentActorId: z.string().min(1),
+    origin: agentEventActorOriginSchema,
+    parentToolCallId: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+}).strict()
+
+export const agentTurnEventBaseSchema = agentEventBaseSchema.extend({
+    turnId: z.string().min(1),
+    actor: agentEventActorSchema,
+}).strict()
+
+export const sessionStartedAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('session.started'),
+    payload: agentRunMetadataSchema,
+}).strict()
+
+export const sessionConfiguredAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('session.configured'),
+    payload: z.object({
+        model: z.string().min(1),
+        cwd: z.string().min(1),
+        approvalMode: z.literal('full-access'),
+        tools: z.array(z.string().min(1)),
+        reasoningEffort: z.string().min(1).optional(),
+        environment: z.record(z.string().min(1), z.literal('[REDACTED]')),
+    }).strict(),
+}).strict()
+
+export const sessionSkillsUpdatedAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('session.skills.updated'),
+    payload: z.object({
+        skills: z.array(agentSkillSchema),
+    }).strict(),
+}).strict()
+
+export const sessionStateChangedAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('session.state.changed'),
+    payload: z.object({
+        state: agentSessionStateSchema,
+        error: agentErrorSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const sessionEndedAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('session.ended'),
+    payload: z.object({
+        reason: agentSessionEndReasonSchema,
+        exitCode: z.number().int().nullable().optional(),
+        signal: z.string().min(1).nullable().optional(),
+        error: agentErrorSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const turnStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('turn.started'),
+    payload: z.object({}).strict(),
+}).strict()
+
+export const turnEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('turn.ended'),
+    payload: z.object({
+        status: agentTurnEndStatusSchema,
+        reason: z.string().min(1).optional(),
+        error: agentErrorSchema.optional(),
+        duration: z.number().int().nonnegative().optional(),
+    }).strict(),
+}).strict()
+
+export const workObservedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('work.observed'),
+    payload: z.object({
+        observations: z.array(agentWorkObservationSchema).min(1),
+    }).strict(),
+}).strict()
+
+export const messageStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('message.started'),
+    payload: z.object({
+        messageId: z.string().min(1),
+        role: agentMessageRoleSchema,
+        commandId: z.string().min(1).optional(),
+    }).strict(),
+}).strict()
+
+export const messageDeltaAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('message.delta'),
+    payload: z.object({
+        messageId: z.string().min(1),
+        role: agentMessageRoleSchema,
+        delta: z.string(),
+    }).strict(),
+}).strict()
+
+export const messageEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('message.ended'),
+    payload: z.object({
+        messageId: z.string().min(1),
+        role: agentMessageRoleSchema,
+        text: z.string().optional(),
+        commandId: z.string().min(1).optional(),
+        overflow: agentPayloadOverflowSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const reasoningStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('reasoning.started'),
+    payload: z.object({
+        reasoningId: z.string().min(1),
+    }).strict(),
+}).strict()
+
+export const reasoningSummaryDeltaAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('reasoning.summary.delta'),
+    payload: z.object({
+        reasoningId: z.string().min(1),
+        text: z.string(),
+    }).strict(),
+}).strict()
+
+export const reasoningEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('reasoning.ended'),
+    payload: z.object({
+        reasoningId: z.string().min(1),
+        summary: z.string().optional(),
+    }).strict(),
+}).strict()
+
+export const toolCallStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('tool.call.started'),
+    payload: z.object({
+        toolCallId: z.string().min(1),
+        toolName: z.string().min(1),
+        input: jsonValueSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const toolOutputDeltaAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('tool.output.delta'),
+    payload: z.object({
+        toolCallId: z.string().min(1),
+        delta: z.string(),
+    }).strict(),
+}).strict()
+
+export const toolCallCompletedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('tool.call.completed'),
+    payload: z.object({
+        toolCallId: z.string().min(1),
+        status: agentToolCallStatusSchema,
+        output: agentToolResultSchema.optional(),
+        error: agentErrorSchema.optional(),
+        overflow: agentPayloadOverflowSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const subagentStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('subagent.started'),
+    payload: subagentRefSchema.extend({
+        description: z.string().min(1).optional(),
+    }).strict(),
+}).strict()
+
+export const subagentProgressAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('subagent.progress'),
+    payload: subagentRefSchema.extend({
+        summary: z.string().min(1).optional(),
+        lastToolName: z.string().min(1).optional(),
+        usage: agentUsageSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const subagentEndedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('subagent.ended'),
+    payload: subagentRefSchema.extend({
+        status: agentSubagentStatusSchema,
+        summary: z.string().optional(),
+        usage: agentUsageSchema.optional(),
+        error: agentErrorSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const usageAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('usage'),
+    payload: z.object({
+        usage: agentUsageSchema,
+    }).strict(),
+}).strict()
+
+export const contextCompactionStartedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('context.compaction.started'),
+    payload: z.object({
+        compactionId: z.string().min(1),
+        trigger: agentContextCompactionTriggerSchema,
+    }).strict(),
+}).strict()
+
+export const contextCompactionCompletedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('context.compaction.completed'),
+    payload: z.object({
+        compactionId: z.string().min(1),
+        trigger: agentContextCompactionTriggerSchema,
+        status: agentContextCompactionStatusSchema,
+        duration: z.number().int().nonnegative().optional(),
+        inputTokensBefore: z.number().int().nonnegative().optional(),
+        inputTokensAfter: z.number().int().nonnegative().optional(),
+        error: agentErrorSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const userInputRequestedAgentEventSchema = agentTurnEventBaseSchema.extend({
+    type: z.literal('user-input.requested'),
+    payload: z.object({
+        requestId: z.string().min(1),
+        toolCallId: z.string().min(1),
+        prompt: z.string().min(1),
+        questions: z.array(agentUserInputQuestionSchema).min(1),
+    }).strict(),
+}).strict()
+
+export const userInputResolvedAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('user-input.resolved'),
+    payload: z.object({
+        requestId: z.string().min(1),
+        requestedTurnId: z.string().min(1),
+        toolCallId: z.string().min(1),
+        answers: agentUserInputAnswersSchema,
+    }).strict(),
+}).strict()
+
+export const errorAgentEventSchema = agentEventBaseSchema.extend({
+    type: z.literal('error'),
+    payload: z.object({
+        message: z.string().min(1),
+        fatal: z.boolean(),
+        source: agentErrorSourceSchema.optional(),
+        error: agentErrorSchema.optional(),
+    }).strict(),
+}).strict()
+
+export const agentEventSchema = z.discriminatedUnion('type', [
+    sessionStartedAgentEventSchema,
+    sessionConfiguredAgentEventSchema,
+    sessionSkillsUpdatedAgentEventSchema,
+    sessionStateChangedAgentEventSchema,
+    sessionEndedAgentEventSchema,
+    turnStartedAgentEventSchema,
+    turnEndedAgentEventSchema,
+    workObservedAgentEventSchema,
+    messageStartedAgentEventSchema,
+    messageDeltaAgentEventSchema,
+    messageEndedAgentEventSchema,
+    reasoningStartedAgentEventSchema,
+    reasoningSummaryDeltaAgentEventSchema,
+    reasoningEndedAgentEventSchema,
+    toolCallStartedAgentEventSchema,
+    toolOutputDeltaAgentEventSchema,
+    toolCallCompletedAgentEventSchema,
+    subagentStartedAgentEventSchema,
+    subagentProgressAgentEventSchema,
+    subagentEndedAgentEventSchema,
+    usageAgentEventSchema,
+    contextCompactionStartedAgentEventSchema,
+    contextCompactionCompletedAgentEventSchema,
+    userInputRequestedAgentEventSchema,
+    userInputResolvedAgentEventSchema,
+    errorAgentEventSchema,
+])
+
+export type AgentMessageRole = z.infer<typeof agentMessageRoleSchema>
+export type AgentSessionEndReason = z.infer<typeof agentSessionEndReasonSchema>
+export type AgentSessionState = z.infer<typeof agentSessionStateSchema>
+export type AgentTurnEndStatus = z.infer<typeof agentTurnEndStatusSchema>
+export type AgentSubagentStatus = z.infer<typeof agentSubagentStatusSchema>
+export type AgentContextCompactionTrigger = z.infer<typeof agentContextCompactionTriggerSchema>
+export type AgentContextCompactionStatus = z.infer<typeof agentContextCompactionStatusSchema>
+export type AgentErrorSource = z.infer<typeof agentErrorSourceSchema>
+export type AgentSkillScope = z.infer<typeof agentSkillScopeSchema>
+export type AgentSkill = z.infer<typeof agentSkillSchema>
+export type AgentEventActorOrigin = z.infer<typeof agentEventActorOriginSchema>
+export type AgentEventActor = z.infer<typeof agentEventActorSchema>
+export type AgentEventBase = z.infer<typeof agentEventBaseSchema>
+export type AgentTurnEventBase = z.infer<typeof agentTurnEventBaseSchema>
+export type SessionStartedAgentEvent = z.infer<typeof sessionStartedAgentEventSchema>
+export type SessionConfiguredAgentEvent = z.infer<typeof sessionConfiguredAgentEventSchema>
+export type SessionSkillsUpdatedAgentEvent = z.infer<typeof sessionSkillsUpdatedAgentEventSchema>
+export type SessionStateChangedAgentEvent = z.infer<typeof sessionStateChangedAgentEventSchema>
+export type SessionEndedAgentEvent = z.infer<typeof sessionEndedAgentEventSchema>
+export type TurnStartedAgentEvent = z.infer<typeof turnStartedAgentEventSchema>
+export type TurnEndedAgentEvent = z.infer<typeof turnEndedAgentEventSchema>
+export type WorkObservedAgentEvent = z.infer<typeof workObservedAgentEventSchema>
+export type MessageStartedAgentEvent = z.infer<typeof messageStartedAgentEventSchema>
+export type MessageDeltaAgentEvent = z.infer<typeof messageDeltaAgentEventSchema>
+export type MessageEndedAgentEvent = z.infer<typeof messageEndedAgentEventSchema>
+export type ReasoningStartedAgentEvent = z.infer<typeof reasoningStartedAgentEventSchema>
+export type ReasoningSummaryDeltaAgentEvent = z.infer<typeof reasoningSummaryDeltaAgentEventSchema>
+export type ReasoningEndedAgentEvent = z.infer<typeof reasoningEndedAgentEventSchema>
+export type ToolCallStartedAgentEvent = z.infer<typeof toolCallStartedAgentEventSchema>
+export type ToolOutputDeltaAgentEvent = z.infer<typeof toolOutputDeltaAgentEventSchema>
+export type ToolCallCompletedAgentEvent = z.infer<typeof toolCallCompletedAgentEventSchema>
+export type SubagentStartedAgentEvent = z.infer<typeof subagentStartedAgentEventSchema>
+export type SubagentProgressAgentEvent = z.infer<typeof subagentProgressAgentEventSchema>
+export type SubagentEndedAgentEvent = z.infer<typeof subagentEndedAgentEventSchema>
+export type UsageAgentEvent = z.infer<typeof usageAgentEventSchema>
+export type ContextCompactionStartedAgentEvent = z.infer<typeof contextCompactionStartedAgentEventSchema>
+export type ContextCompactionCompletedAgentEvent = z.infer<typeof contextCompactionCompletedAgentEventSchema>
+export type UserInputRequestedAgentEvent = z.infer<typeof userInputRequestedAgentEventSchema>
+export type UserInputResolvedAgentEvent = z.infer<typeof userInputResolvedAgentEventSchema>
+export type ErrorAgentEvent = z.infer<typeof errorAgentEventSchema>
+export type AgentEvent = z.infer<typeof agentEventSchema>

package/src/protocol/agent-json.ts

@@ -0,0 +1,30 @@
+import type { ZodType } from 'zod'
+import z from 'zod'
+
+export const jsonPrimitiveSchema = z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+])
+
+export type JsonPrimitive = z.infer<typeof jsonPrimitiveSchema>
+export interface JsonObject { readonly [key: string]: JsonValue }
+export type JsonArray = readonly JsonValue[]
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray
+
+export const jsonValueSchema: ZodType<JsonValue> = z.lazy(() => z.union([
+    jsonPrimitiveSchema,
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+]))
+
+export const jsonObjectSchema: ZodType<JsonObject> = z.record(z.string(), jsonValueSchema)
+export const jsonArraySchema: ZodType<JsonArray> = z.array(jsonValueSchema)
+
+const utf8Encoder = new TextEncoder()
+
+/** UTF-8 byte length of `JSON.stringify(value)`; the unit every wire size cap is expressed in. */
+export function jsonUtf8ByteLength(value: unknown): number {
+    return utf8Encoder.encode(JSON.stringify(value)).byteLength
+}

package/src/protocol/agent-metadata.ts

@@ -0,0 +1,30 @@
+import z from 'zod'
+import { claudeModelIdSchema, codexModelIdSchema } from './agent-model'
+
+const metadataShape = {
+    sessionId: z.string().min(1),
+    providerSessionId: z.string().min(1),
+    cwd: z.string().min(1),
+    transcriptPath: z.string().min(1),
+} as const
+
+export const codexAgentRunMetadataSchema = z.object({
+    provider: z.literal('codex'),
+    ...metadataShape,
+    model: codexModelIdSchema.optional(),
+}).strict()
+
+export const claudeAgentRunMetadataSchema = z.object({
+    provider: z.literal('claude'),
+    ...metadataShape,
+    model: claudeModelIdSchema.optional(),
+}).strict()
+
+export const agentRunMetadataSchema = z.discriminatedUnion('provider', [
+    codexAgentRunMetadataSchema,
+    claudeAgentRunMetadataSchema,
+])
+
+export type CodexAgentRunMetadata = z.infer<typeof codexAgentRunMetadataSchema>
+export type ClaudeAgentRunMetadata = z.infer<typeof claudeAgentRunMetadataSchema>
+export type AgentRunMetadata = z.infer<typeof agentRunMetadataSchema>

package/src/protocol/agent-model.ts

@@ -0,0 +1,68 @@
+import type { AgentProviderId } from './agent-provider'
+import z from 'zod'
+
+/**
+ * Known model catalogs. They document what each harness has been exercised
+ * with and drive presentation helpers, but they are deliberately NOT the wire
+ * contract: a new model must be usable by re-provisioning nothing, so every
+ * schema that carries a model id accepts any non-empty string.
+ */
+export const codexModelIds = [
+    'gpt-5.6-sol',
+    'gpt-5.5',
+    'gpt-5.4',
+    'gpt-5.4-mini',
+    'gpt-5.3-codex',
+    'gpt-5.2',
+] as const
+
+export const claudeModelIds = [
+    'sonnet',
+    'claude-opus-4-8',
+    'opus',
+    'haiku',
+    'claude-opus-4-7',
+    'claude-mythos-preview',
+    'claude-opus-4-6',
+    'claude-sonnet-4-6',
+    'claude-haiku-4-5',
+    'claude-haiku-4-5-20251001',
+    'claude-opus-4-5',
+    'claude-opus-4-5-20251101',
+    'claude-sonnet-4-5',
+    'claude-sonnet-4-5-20250929',
+    'claude-opus-4-1',
+    'claude-opus-4-1-20250805',
+    'claude-opus-4-0',
+    'claude-opus-4-20250514',
+    'claude-sonnet-4-0',
+    'claude-sonnet-4-20250514',
+    'claude-3-haiku-20240307',
+] as const
+
+export const knownCodexModelIdSchema = z.enum(codexModelIds)
+export const knownClaudeModelIdSchema = z.enum(claudeModelIds)
+export const knownAgentModelIdSchema = z.union([knownCodexModelIdSchema, knownClaudeModelIdSchema])
+
+export const agentModelIdSchema = z.string().min(1).max(256)
+export const codexModelIdSchema = agentModelIdSchema
+export const claudeModelIdSchema = agentModelIdSchema
+
+export type KnownCodexModelId = typeof codexModelIds[number]
+export type KnownClaudeModelId = typeof claudeModelIds[number]
+export type KnownAgentModelId = KnownCodexModelId | KnownClaudeModelId
+
+export type CodexModelId = string
+export type ClaudeModelId = string
+
+export interface AgentModelIdByProvider {
+    codex: CodexModelId
+    claude: ClaudeModelId
+}
+
+export type AgentModelId<Provider extends AgentProviderId = AgentProviderId> = AgentModelIdByProvider[Provider]
+
+export function isKnownModelId(provider: AgentProviderId, modelId: string): modelId is KnownAgentModelId {
+    const catalog: readonly string[] = provider === 'codex' ? codexModelIds : claudeModelIds
+    return catalog.includes(modelId)
+}

package/src/protocol/agent-overflow.ts

@@ -0,0 +1,18 @@
+import z from 'zod'
+
+/**
+ * Reference to a payload that was too large to travel inline on the wire.
+ *
+ * The producer keeps a bounded head inline (for example the first bytes of a
+ * tool result) and stores the complete JSON-encoded value out of band. `ref` is
+ * opaque to agent-core: the host that provided the `LargePayloadStore` port is
+ * the only party that can resolve it (agent-api uses `vault://` references).
+ */
+export const agentPayloadOverflowSchema = z.object({
+    ref: z.string().min(1).max(2048),
+    byteLength: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/u),
+    encoding: z.literal('json'),
+}).strict()
+
+export type AgentPayloadOverflow = z.infer<typeof agentPayloadOverflowSchema>

package/src/protocol/agent-presentation.ts

@@ -0,0 +1,98 @@
+import type { AgentReasoningEffort } from './agent-command'
+import type { KnownCodexModelId } from './agent-model'
+
+/**
+ * Display metadata for protocol identifiers, kept beside the registries so a model
+ * or effort added to the wire unions cannot ship without its presentation: the
+ * `Record` types below fail to compile until every identifier is covered.
+ *
+ * Copy and figures mirror the bundled Codex CLI catalog
+ * (`codex-rs/models-manager/models.json` at the pinned `@openai/codex@0.145.0`).
+ * Update this file together with the pinned CLI version. Upstream defines efforts
+ * by description only — no per-effort reasoning-token budget exists, so none is
+ * invented here.
+ *
+ * This is UI copy and relative sizing only. Billing, pricing, and cost estimation
+ * stay out of protocol (docs/agents-protocol.md) — `relativeCost` is a 1–5 picker
+ * weight, not a price.
+ */
+export interface AgentModelPresentation {
+    label: string
+    description: string
+    /** Relative cost weight for pickers (1 = cheapest, 5 = most expensive). Not a price. */
+    relativeCost: 1 | 2 | 3 | 4 | 5
+    maxInputTokens: number
+    maxOutputTokens?: number
+    isMultiModal: boolean
+}
+
+const CODEX_CONTEXT_WINDOW = 272_000
+
+export const codexModelPresentation: Record<KnownCodexModelId, AgentModelPresentation> = {
+    'gpt-5.6-sol': {
+        label: 'GPT-5.6-Sol',
+        description: 'Latest frontier agentic coding model.',
+        relativeCost: 5,
+        maxInputTokens: CODEX_CONTEXT_WINDOW,
+        isMultiModal: true,
+    },
+    'gpt-5.5': {
+        label: 'GPT-5.5',
+        description: 'Frontier model for complex coding, research, and real-world work.',
+        relativeCost: 4,
+        maxInputTokens: CODEX_CONTEXT_WINDOW,
+        isMultiModal: true,
+    },
+    'gpt-5.4': {
+        label: 'GPT-5.4',
+        description: 'Strong model for everyday coding.',
+        relativeCost: 3,
+        maxInputTokens: CODEX_CONTEXT_WINDOW,
+        isMultiModal: true,
+    },
+    'gpt-5.4-mini': {
+        label: 'GPT-5.4-Mini',
+        description: 'Small, fast, and cost-efficient model for simpler coding tasks.',
+        relativeCost: 2,
+        maxInputTokens: CODEX_CONTEXT_WINDOW,
+        isMultiModal: true,
+    },
+    /* Absent from the 0.145.0 upstream catalog; retained in our registry, so the
+       copy below is ours. */
+    'gpt-5.3-codex': {
+        label: 'GPT-5.3-Codex',
+        description: 'Code-tuned model for focused engineering tasks.',
+        relativeCost: 3,
+        maxInputTokens: CODEX_CONTEXT_WINDOW,
+        isMultiModal: true,
+    },
+    'gpt-5.2': {
+        label: 'GPT-5.2',
+        description: 'Optimized for professional work and long-running agents.',
+        relativeCost: 3,
+        maxInputTokens: CODEX_CONTEXT_WINDOW,
+        isMultiModal: true,
+    },
+}
+
+interface AgentReasoningEffortPresentation {
+    label: string
+    description: string
+}
+
+/* Effort descriptions are upstream's own wording (gpt-5.6 catalog entries). */
+export const agentReasoningEffortPresentation: Record<AgentReasoningEffort, AgentReasoningEffortPresentation> = {
+    low: { label: 'Low', description: 'Fast responses with lighter reasoning' },
+    medium: { label: 'Medium', description: 'Balances speed and reasoning depth for everyday tasks' },
+    high: { label: 'High', description: 'Greater reasoning depth for complex problems' },
+    xhigh: { label: 'Extra high', description: 'Extra high reasoning depth for complex problems' },
+    max: { label: 'Max', description: 'Maximum reasoning depth for the hardest problems' },
+}
+
+/**
+ * The efforts products offer to users. `max` stays a valid wire value for
+ * compatibility but is not selectable anywhere.
+ */
+export const selectableAgentReasoningEfforts = ['low', 'medium', 'high', 'xhigh'] as const satisfies readonly AgentReasoningEffort[]
+
+export type SelectableAgentReasoningEffort = typeof selectableAgentReasoningEfforts[number]

package/src/protocol/agent-provider.ts

@@ -0,0 +1,4 @@
+import z from 'zod'
+
+export const agentProviderIdSchema = z.enum(['codex', 'claude'])
+export type AgentProviderId = z.infer<typeof agentProviderIdSchema>