@meistrari/agent-core 0.2.0-experimental.0 → 0.2.0-experimental.2

package/src/protocol/agent-catalog.ts

@@ -0,0 +1,159 @@
+import type { AgentReasoningEffort } from './agent-command'
+import type { AgentModelPresentation } from './agent-presentation'
+import type { AgentProviderId } from './agent-provider'
+import z from 'zod'
+import { agentReasoningEffortSchema } from './agent-command'
+import { claudeModelIds, claudeModelIdSchema, codexModelIds, codexModelIdSchema } from './agent-model'
+import { claudeModelPresentation, codexModelPresentation } from './agent-presentation'
+
+/**
+ * The product catalog of agent harnesses and the models users may select for each.
+ * Every creation surface (API, Web, CLI, Slack assistant) reads its choices and defaults
+ * from here. The wire model unions in `agent-model.ts` stay broader so historical ids in
+ * stored events keep parsing; creation accepts only the selectable ids below.
+ *
+ * "Harness" is display vocabulary only: code and the public API keep `provider`.
+ */
+export const selectableCodexModelIds = codexModelIds
+
+/** Verified available to the configured Claude subscription through `supportedModels()`. */
+export const selectableClaudeModelIds = [
+    'claude-opus-5-5',
+    'claude-sonnet-5',
+    'claude-fable-5-1',
+] as const
+
+export type SelectableCodexModelId = typeof selectableCodexModelIds[number]
+export type SelectableClaudeModelId = typeof selectableClaudeModelIds[number]
+
+export interface SelectableAgentModelIdByProvider {
+    codex: SelectableCodexModelId
+    claude: SelectableClaudeModelId
+}
+
+export type SelectableAgentModelId<Provider extends AgentProviderId = AgentProviderId> = SelectableAgentModelIdByProvider[Provider]
+
+export interface AgentHarness<Provider extends AgentProviderId> {
+    provider: Provider
+    label: string
+    /** Picker order. */
+    models: readonly SelectableAgentModelId<Provider>[]
+    defaultModel: SelectableAgentModelId<Provider>
+    modelPresentation: Record<SelectableAgentModelId<Provider>, AgentModelPresentation>
+}
+
+export const agentHarnesses: { readonly [Provider in AgentProviderId]: AgentHarness<Provider> } = {
+    codex: {
+        provider: 'codex',
+        label: 'Codex',
+        models: selectableCodexModelIds,
+        defaultModel: 'gpt-6-astra',
+        modelPresentation: codexModelPresentation,
+    },
+    claude: {
+        provider: 'claude',
+        label: 'Claude',
+        models: selectableClaudeModelIds,
+        defaultModel: 'claude-opus-5-5',
+        modelPresentation: claudeModelPresentation,
+    },
+}
+
+/** Picker order for harnesses. */
+export const agentHarnessOrder = ['codex', 'claude'] as const satisfies readonly AgentProviderId[]
+
+const codexAgentSelectionSchema = z.strictObject({
+    provider: z.literal('codex'),
+    model: z.enum(selectableCodexModelIds),
+    reasoningEffort: agentReasoningEffortSchema,
+})
+
+const claudeAgentSelectionSchema = z.strictObject({
+    provider: z.literal('claude'),
+    model: z.enum(selectableClaudeModelIds),
+    reasoningEffort: agentReasoningEffortSchema,
+})
+
+/** A complete initial agent selection: harness, a model of that harness, and an effort. */
+export const agentSelectionSchema = z.discriminatedUnion('provider', [
+    codexAgentSelectionSchema,
+    claudeAgentSelectionSchema,
+])
+
+export type AgentSelection = z.infer<typeof agentSelectionSchema>
+
+/**
+ * An agent selection recorded earlier: a provisioned session, a queued job, or a published
+ * event. It accepts every wire model id of its harness so a record keeps parsing after its
+ * model leaves the selectable catalog. New selections validate with `agentSelectionSchema`.
+ */
+export const storedAgentSelectionSchema = z.discriminatedUnion('provider', [
+    z.strictObject({
+        provider: z.literal('codex'),
+        model: codexModelIdSchema,
+        reasoningEffort: agentReasoningEffortSchema,
+    }),
+    z.strictObject({
+        provider: z.literal('claude'),
+        model: claudeModelIdSchema,
+        reasoningEffort: agentReasoningEffortSchema,
+    }),
+])
+
+export type StoredAgentSelection = z.infer<typeof storedAgentSelectionSchema>
+
+const wireModelIdsByProvider: { readonly [Provider in AgentProviderId]: ReadonlySet<string> } = {
+    codex: new Set<string>(codexModelIds),
+    claude: new Set<string>(claudeModelIds),
+}
+
+/**
+ * The harness whose wire model ids include `model`, including ids no longer selectable.
+ * Use it to resolve a recorded selection; new selections use `agentHarnessForModel`.
+ */
+export function storedAgentHarnessForModel(model: string): AgentProviderId | undefined {
+    return agentHarnessOrder.find(provider => wireModelIdsByProvider[provider].has(model))
+}
+
+export const defaultAgentSelection = {
+    provider: 'codex',
+    model: 'gpt-6-astra',
+    reasoningEffort: 'medium',
+} as const satisfies AgentSelection
+
+const selectableModelIdsByProvider: { readonly [Provider in AgentProviderId]: ReadonlySet<string> } = {
+    codex: new Set<string>(selectableCodexModelIds),
+    claude: new Set<string>(selectableClaudeModelIds),
+}
+
+/** The harness that offers a selectable model id, or undefined for an unselectable id. */
+export function agentHarnessForModel(model: string): AgentProviderId | undefined {
+    return agentHarnessOrder.find(provider => isSelectableAgentModel(provider, model))
+}
+
+export function isSelectableAgentModel<Provider extends AgentProviderId>(
+    provider: Provider,
+    model: string,
+): model is SelectableAgentModelId<Provider> {
+    return selectableModelIdsByProvider[provider].has(model)
+}
+
+const selectableModelPresentationById: ReadonlyMap<string, AgentModelPresentation> = new Map([
+    ...selectableCodexModelIds.map(model => [model, codexModelPresentation[model]] as const),
+    ...selectableClaudeModelIds.map(model => [model, claudeModelPresentation[model]] as const),
+])
+
+/** Presentation for a selectable model id of any harness; undefined for historical or unknown ids. */
+export function selectableAgentModelPresentation(model: string): AgentModelPresentation | undefined {
+    return selectableModelPresentationById.get(model)
+}
+
+/**
+ * The complete selection for a selectable model id of any harness at the given effort, or
+ * undefined when no harness offers the model. Pickers that list every harness's models
+ * together use this to derive the harness from the chosen model.
+ */
+export function agentSelectionForModel(model: string, reasoningEffort: AgentReasoningEffort): AgentSelection | undefined {
+    const parsed = agentSelectionSchema.safeParse({ provider: agentHarnessForModel(model), model, reasoningEffort })
+    return parsed.success ? parsed.data : undefined
+}

package/src/protocol/agent-command.ts

@@ -1,67 +1,114 @@
 import z from 'zod'
 import { agentPromptSchema } from './agent-content'
+import { agentModelIdSchema } from './agent-model'
+import { agentNotificationInstructionSchema, agentNotificationsSchema, isAgentNotificationToolOutputWithinSizeLimit } from './agent-notification'
 import { agentProviderIdSchema } from './agent-provider'
 import { agentUserInputAnswersSchema } from './agent-user-input'
+import { objectRejectingKeys } from './rejected-keys'
 
 export const agentReasoningEffortSchema = z.enum(['low', 'medium', 'high', 'xhigh', 'max'])
 export const agentPromptModeSchema = z.enum(['next', 'steer'])
 
+// A prompt may change the session's model and/or reasoning effort. The change takes effect where the
+// prompt lands (a steer changes the running turn, a next-turn prompt the turn it starts) and stays
+// the session's current settings afterwards. The model must belong to the session's provider.
+export const agentSettingsChangeSchema = z.strictObject({
+    model: agentModelIdSchema.optional(),
+    reasoningEffort: agentReasoningEffortSchema.optional(),
+}).refine(settings => settings.model !== undefined || settings.reasoningEffort !== undefined, {
+    message: 'A settings change needs a model or a reasoning effort.',
+})
+
 export const agentAuthorSchema = z.object({
     name: z.string().min(1),
     email: z.string().min(1).optional(),
     gitEmail: z.string().min(1).optional(),
-}).strict()
+})
 
 const commandIdSchema = z.string().min(1)
 
-const runningCommandBaseSchema = z.object({
+// Provider turn identity never crosses this boundary; only the canonical turnId does.
+const runningCommandBaseSchema = objectRejectingKeys({
     provider: agentProviderIdSchema,
     sessionId: z.string().min(1),
     providerSessionId: z.string().min(1),
-}).strict()
+}, ['providerTurnId'])
 
 export const sendPromptCommandSchema = runningCommandBaseSchema.extend({
     type: z.literal('agent.send-prompt'),
     mode: agentPromptModeSchema,
+    turnId: z.string().min(1).optional(),
     origin: z.enum(['user', 'supervisor']).default('user'),
     prompt: agentPromptSchema,
     commandId: commandIdSchema,
     /** Resolved by the application for this prompt, including after runtime recovery. */
     model: z.string().trim().min(1).max(256).optional(),
+    reasoningEffort: agentReasoningEffortSchema.optional(),
     author: agentAuthorSchema.optional(),
-}).strict()
+    settings: agentSettingsChangeSchema.optional(),
+})
+
+export const agentNotifyCommandSchema = runningCommandBaseSchema.extend({
+    type: z.literal('agent.notify'),
+    commandId: commandIdSchema,
+    instruction: agentNotificationInstructionSchema.nullable(),
+    notifications: agentNotificationsSchema,
+}).superRefine((command, context) => {
+    if (isAgentNotificationToolOutputWithinSizeLimit({
+        commandId: command.commandId,
+        instruction: command.instruction,
+        notifications: command.notifications,
+    })) {
+        return
+    }
+    context.addIssue({
+        code: 'custom',
+        path: ['notifications'],
+        message: 'Serialized notification tool output exceeds the allowed size.',
+    })
+})
 
 export const interruptAgentCommandSchema = runningCommandBaseSchema.extend({
     type: z.literal('agent.interrupt'),
     commandId: commandIdSchema,
     turnId: z.string().min(1).optional(),
     reason: z.string().min(1).optional(),
-}).strict()
+})
+
+export const compactContextAgentCommandSchema = runningCommandBaseSchema.extend({
+    type: z.literal('agent.compact-context'),
+    commandId: commandIdSchema,
+})
 
 export const stopAgentCommandSchema = runningCommandBaseSchema.extend({
     type: z.literal('agent.stop'),
     reason: z.string().min(1).optional(),
-}).strict()
+})
 
 export const respondUserInputAgentCommandSchema = runningCommandBaseSchema.extend({
     type: z.literal('agent.respond-user-input'),
     commandId: commandIdSchema,
     requestId: z.string().min(1),
     answers: agentUserInputAnswersSchema,
-}).strict()
+})
 
 export const agentCommandSchema = z.union([
     sendPromptCommandSchema,
+    agentNotifyCommandSchema,
     interruptAgentCommandSchema,
+    compactContextAgentCommandSchema,
     stopAgentCommandSchema,
     respondUserInputAgentCommandSchema,
 ])
 
 export type AgentReasoningEffort = z.infer<typeof agentReasoningEffortSchema>
 export type AgentPromptMode = z.infer<typeof agentPromptModeSchema>
+export type AgentSettingsChange = z.infer<typeof agentSettingsChangeSchema>
 export type AgentAuthor = z.infer<typeof agentAuthorSchema>
 export type SendPromptCommand = z.infer<typeof sendPromptCommandSchema>
+export type AgentNotifyCommand = z.infer<typeof agentNotifyCommandSchema>
 export type InterruptAgentCommand = z.infer<typeof interruptAgentCommandSchema>
+export type CompactContextAgentCommand = z.infer<typeof compactContextAgentCommandSchema>
 export type StopAgentCommand = z.infer<typeof stopAgentCommandSchema>
 export type RespondUserInputAgentCommand = z.infer<typeof respondUserInputAgentCommandSchema>
 export type AgentCommand = z.infer<typeof agentCommandSchema>

package/src/protocol/agent-content.ts

@@ -1,54 +1,54 @@
 import z from 'zod'
 
-export const textAgentInputBlockSchema = z.object({
+export const textAgentInputBlockSchema = z.strictObject({
     type: z.literal('text'),
     text: z.string(),
-}).strict()
+})
 
-export const urlAgentImageSourceSchema = z.object({
+export const urlAgentImageSourceSchema = z.strictObject({
     kind: z.literal('url'),
     url: z.url(),
-}).strict()
+})
 
-export const base64AgentImageSourceSchema = z.object({
+export const base64AgentImageSourceSchema = z.strictObject({
     kind: z.literal('base64'),
     data: z.string().min(1),
     mimeType: z.string().min(1),
-}).strict()
+})
 
 export const agentImageSourceSchema = z.discriminatedUnion('kind', [
     urlAgentImageSourceSchema,
     base64AgentImageSourceSchema,
 ])
 
-export const imageAgentInputBlockSchema = z.object({
+export const imageAgentInputBlockSchema = z.strictObject({
     type: z.literal('image'),
     source: agentImageSourceSchema,
-}).strict()
+})
 
-export const textAgentFileSourceSchema = z.object({
+export const textAgentFileSourceSchema = z.strictObject({
     kind: z.literal('text'),
     name: z.string().min(1).optional(),
     text: z.string(),
     mimeType: z.string().min(1).optional(),
-}).strict()
+})
 
-export const urlAgentFileSourceSchema = z.object({
+export const urlAgentFileSourceSchema = z.strictObject({
     kind: z.literal('url'),
     url: z.url(),
     name: z.string().min(1).optional(),
     mimeType: z.string().min(1).optional(),
-}).strict()
+})
 
 export const agentFileSourceSchema = z.discriminatedUnion('kind', [
     textAgentFileSourceSchema,
     urlAgentFileSourceSchema,
 ])
 
-export const fileAgentInputBlockSchema = z.object({
+export const fileAgentInputBlockSchema = z.strictObject({
     type: z.literal('file'),
     source: agentFileSourceSchema,
-}).strict()
+})
 
 export const agentInputBlockSchema = z.discriminatedUnion('type', [
     textAgentInputBlockSchema,
@@ -56,9 +56,29 @@ export const agentInputBlockSchema = z.discriminatedUnion('type', [
     fileAgentInputBlockSchema,
 ])
 
+const wireAgentImageSourceSchema = z.discriminatedUnion('kind', [
+    urlAgentImageSourceSchema.strip(),
+    base64AgentImageSourceSchema.strip(),
+])
+const wireAgentFileSourceSchema = z.discriminatedUnion('kind', [
+    textAgentFileSourceSchema.strip(),
+    urlAgentFileSourceSchema.strip(),
+])
+const wireAgentInputBlockSchema = z.discriminatedUnion('type', [
+    textAgentInputBlockSchema.strip(),
+    z.object({
+        type: z.literal('image'),
+        source: wireAgentImageSourceSchema,
+    }),
+    z.object({
+        type: z.literal('file'),
+        source: wireAgentFileSourceSchema,
+    }),
+])
+
 export const agentPromptSchema = z.object({
-    blocks: z.array(agentInputBlockSchema).min(1),
-}).strict()
+    blocks: z.array(wireAgentInputBlockSchema).min(1),
+})
 
 export type TextAgentInputBlock = z.infer<typeof textAgentInputBlockSchema>
 export type UrlAgentImageSource = z.infer<typeof urlAgentImageSourceSchema>