@meistrari/agent-core 0.0.0

package/src/supervisor-protocol/command-body.ts

@@ -0,0 +1,82 @@
+import z from 'zod'
+import { agentPromptModeSchema, agentPromptSchema, agentUserInputAnswersSchema, jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
+
+const wireSenderContextSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('application') }).strict(),
+    z.object({
+        kind: z.literal('slack'),
+        mention: z.string().max(256).refine(value => value.trim().length > 0),
+    }).strict(),
+])
+
+const wireCommandUserSchema = z.object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    email: z.string().min(1).optional(),
+    gitEmail: z.string().min(1).optional(),
+    senderContext: wireSenderContextSchema.optional(),
+}).strict()
+
+const wireInputAttachmentRefSchema = z.object({
+    attachmentId: z.string().refine(value => value.trim().length > 0),
+    ordinal: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    filename: z.string().refine(value => value.trim().length > 0),
+    mediaType: z.string().refine(value => value.trim().length > 0),
+    byteSize: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+}).strict()
+
+/**
+ * Product-specific prompt context (agent-api: declared inputs, run id, model
+ * overrides). Opaque to agent-core; interpreted by the host's
+ * `WorkspacePreparer.prepareTurn`.
+ */
+export const wireCommandExtensionsMaxBytes = 32 * 1024
+export const wireCommandExtensionsSchema = jsonObjectSchema.refine(
+    value => jsonUtf8ByteLength(value) <= wireCommandExtensionsMaxBytes,
+    { message: `command extensions must encode to at most ${wireCommandExtensionsMaxBytes} bytes` },
+)
+
+const wireSendPromptCommandSchema = z.object({
+    type: z.literal('agent.send-prompt'),
+    mode: agentPromptModeSchema,
+    prompt: agentPromptSchema,
+    attachments: z.array(wireInputAttachmentRefSchema).superRefine((attachments, context) => {
+        const attachmentIds = new Set<string>()
+        for (const [index, attachment] of attachments.entries()) {
+            if (attachmentIds.has(attachment.attachmentId)) {
+                context.addIssue({ code: 'custom', path: [index, 'attachmentId'], message: 'attachmentId must be unique' })
+            }
+            attachmentIds.add(attachment.attachmentId)
+            if (attachment.ordinal !== index) {
+                context.addIssue({ code: 'custom', path: [index, 'ordinal'], message: 'ordinals must be contiguous and ordered' })
+            }
+        }
+    }),
+    user: wireCommandUserSchema.optional(),
+    extensions: wireCommandExtensionsSchema.optional(),
+}).strict()
+
+const wireInterruptCommandSchema = z.object({
+    type: z.literal('agent.interrupt'),
+}).strict()
+
+const wireRespondUserInputCommandSchema = z.object({
+    type: z.literal('agent.respond-user-input'),
+    requestId: z.string().min(1),
+    answers: agentUserInputAnswersSchema,
+    user: wireCommandUserSchema.optional(),
+}).strict()
+
+export const wireCommandBodySchema = z.discriminatedUnion('type', [
+    wireSendPromptCommandSchema,
+    wireInterruptCommandSchema,
+    wireRespondUserInputCommandSchema,
+])
+
+export type WireCommandUser = z.infer<typeof wireCommandUserSchema>
+export type WireInputAttachmentRef = z.infer<typeof wireInputAttachmentRefSchema>
+export type WireCommandExtensions = z.infer<typeof wireCommandExtensionsSchema>
+export type WireSendPromptCommand = z.infer<typeof wireSendPromptCommandSchema>
+export type WireRespondUserInputCommand = z.infer<typeof wireRespondUserInputCommandSchema>
+export type WireCommandBody = z.infer<typeof wireCommandBodySchema>

package/src/supervisor-protocol/context-file-content.ts

@@ -0,0 +1,90 @@
+import { Buffer } from 'node:buffer'
+
+import z from 'zod'
+
+export const contextFileContentTypeHeader = 'content-type' as const
+export const contextFileCacheControlHeader = 'cache-control' as const
+export const contextFileCacheControlValue = 'private, no-store' as const
+export const contextFileNameHeader = 'x-coding-agent-context-file-name' as const
+export const contextFileDeclaredSizeHeader = 'x-coding-agent-context-file-declared-size' as const
+export const contextFileMaxBytes = 104_857_600
+export const contextFileErrorBodyMaxBytes = 16 * 1024
+export const contextFileDownloadTimeoutMs = 600_000
+
+const contextFileMaxReferenceCharacters = 255
+const contextFileMaxFilenameBytes = 255
+const contextFileMaxEncodedFilenameCharacters = 340
+const contextFileMediaTypePattern = /^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/u
+const contextFileEncodedFilenamePattern = /^[\w-]{2,340}$/u
+
+export const contextFileRefSchema = z.string()
+    .min(1)
+    .max(contextFileMaxReferenceCharacters)
+    .refine(value => value.trim().length > 0)
+    .refine(value => value !== '.' && value !== '..')
+
+export const contextFileFilenameSchema = z.string()
+    .min(1)
+    .refine(value => Buffer.byteLength(value, 'utf8') <= contextFileMaxFilenameBytes)
+
+export const contextFileMediaTypeSchema = z.string().regex(contextFileMediaTypePattern)
+
+export const contextFileDeclaredByteSizeSchema = z.number()
+    .int()
+    .nonnegative()
+    .max(contextFileMaxBytes)
+
+export const contextFileErrorResponseSchema = z.object({
+    message: z.string().min(1).max(500),
+    details: z.record(z.string(), z.unknown()).optional(),
+}).strict()
+
+export type ContextFileErrorResponse = z.infer<typeof contextFileErrorResponseSchema>
+
+export function encodeContextFileName(filename: string): string {
+    const parsed = contextFileFilenameSchema.parse(filename)
+    return Buffer.from(parsed, 'utf8').toString('base64url')
+}
+
+export function decodeContextFileName(encoded: string): string | undefined {
+    if (encoded.length > contextFileMaxEncodedFilenameCharacters
+        || !contextFileEncodedFilenamePattern.test(encoded)) {
+        return undefined
+    }
+
+    const bytes = Buffer.from(encoded, 'base64url')
+    if (bytes.toString('base64url') !== encoded)
+        return undefined
+
+    let filename: string
+    try {
+        filename = new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    }
+    catch {
+        return undefined
+    }
+
+    const parsed = contextFileFilenameSchema.safeParse(filename)
+    return parsed.success ? parsed.data : undefined
+}
+
+export function normalizeContextFileMediaType(mediaType: string | undefined): string {
+    const parsed = contextFileMediaTypeSchema.safeParse(mediaType)
+    return parsed.success ? parsed.data : 'application/octet-stream'
+}
+
+export function decodeContextFileErrorResponse(body: Uint8Array): ContextFileErrorResponse | undefined {
+    if (body.byteLength > contextFileErrorBodyMaxBytes)
+        return undefined
+
+    let value: unknown
+    try {
+        value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body))
+    }
+    catch {
+        return undefined
+    }
+
+    const parsed = contextFileErrorResponseSchema.safeParse(value)
+    return parsed.success ? parsed.data : undefined
+}

package/src/supervisor-protocol/control-authority.ts

@@ -0,0 +1,88 @@
+import { z } from 'zod'
+
+export const sandboxControlAuthorityAlgorithm = 'ES256' as const
+export const sandboxControlAuthorityAudience = 'coding-agent:sandbox-supervisor-control' as const
+export const sandboxControlAuthorityHeaderName = 'X-Coding-Agent-Control-Authority' as const
+export const sandboxControlAuthorityAssertionLifetimeSeconds = 15
+export const sandboxControlAuthorityClockSkewSeconds = 5
+
+const nonemptyBoundedStringSchema = z.string().min(1).max(512)
+const base64UrlCoordinateSchema = z.string().regex(/^[\w-]+$/u)
+const keyIdSchema = z.string().regex(/^[\w.-]{1,128}$/u)
+const positiveSafeIntegerSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER)
+const nonnegativeSafeIntegerSchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)
+const numericDateSchema = z.number().int().nonnegative()
+
+export const sandboxControlAuthorityProtectedHeaderSchema = z.object({
+    alg: z.literal(sandboxControlAuthorityAlgorithm),
+    kid: keyIdSchema,
+    typ: z.literal('JWT'),
+}).strict()
+
+export const sandboxControlAuthorityPublicJwkSchema = z.object({
+    kty: z.literal('EC'),
+    crv: z.literal('P-256'),
+    x: base64UrlCoordinateSchema,
+    y: base64UrlCoordinateSchema,
+    kid: keyIdSchema,
+    alg: z.literal(sandboxControlAuthorityAlgorithm),
+    use: z.literal('sig'),
+    key_ops: z.tuple([z.literal('verify')]),
+}).strict()
+
+export const sandboxControlAuthorityPublicJwksSchema = z.object({
+    keys: z.array(sandboxControlAuthorityPublicJwkSchema).min(1),
+}).strict().superRefine((jwks, context) => {
+    const keyIds = new Set<string>()
+    for (const [index, key] of jwks.keys.entries()) {
+        if (keyIds.has(key.kid)) {
+            context.addIssue({
+                code: 'custom',
+                path: ['keys', index, 'kid'],
+                message: 'Control-authority key IDs must be unique.',
+            })
+        }
+        keyIds.add(key.kid)
+    }
+})
+
+export const sandboxControlAuthorityClaimsSchema = z.object({
+    iss: nonemptyBoundedStringSchema,
+    aud: z.literal(sandboxControlAuthorityAudience),
+    jti: z.uuid(),
+    iat: numericDateSchema,
+    nbf: numericDateSchema,
+    exp: numericDateSchema,
+    providerSandboxId: nonemptyBoundedStringSchema,
+    sessionId: nonemptyBoundedStringSchema,
+    sessionSandboxId: nonemptyBoundedStringSchema,
+    connectionGeneration: positiveSafeIntegerSchema,
+    runtimeConnectionAttemptId: z.uuid(),
+    eventAckFloor: nonnegativeSafeIntegerSchema,
+}).strict().superRefine((claims, context) => {
+    if (claims.jti !== claims.runtimeConnectionAttemptId) {
+        context.addIssue({
+            code: 'custom',
+            path: ['jti'],
+            message: 'Assertion ID must equal the runtime connection attempt ID.',
+        })
+    }
+    if (claims.nbf < claims.iat) {
+        context.addIssue({
+            code: 'custom',
+            path: ['nbf'],
+            message: 'Not-before time must not precede issued-at time.',
+        })
+    }
+    if (claims.exp <= claims.nbf) {
+        context.addIssue({
+            code: 'custom',
+            path: ['exp'],
+            message: 'Expiration time must follow not-before time.',
+        })
+    }
+})
+
+export type SandboxControlAuthorityClaims = z.infer<typeof sandboxControlAuthorityClaimsSchema>
+export type SandboxControlAuthorityProtectedHeader = z.infer<typeof sandboxControlAuthorityProtectedHeaderSchema>
+export type SandboxControlAuthorityPublicJwks = z.infer<typeof sandboxControlAuthorityPublicJwksSchema>

package/src/supervisor-protocol/durability.ts

@@ -0,0 +1,33 @@
+import type { WrappedAgentEvent } from './agent-event-wrapper'
+import type { WireEventBody, WireEventBodyType } from './event-body'
+
+type WireEventDurability = 'durable' | 'ephemeral'
+
+const ephemeralEventTypes = [
+    'agent.message.delta',
+    'agent.tool.output.delta',
+    'agent.reasoning.summary.delta',
+    'supervisor.heartbeat',
+] as const satisfies readonly WireEventBodyType[]
+
+type EphemeralWireEventType = typeof ephemeralEventTypes[number]
+type EphemeralWrappedAgentEventType = Extract<EphemeralWireEventType, WrappedAgentEvent['type']>
+
+export type EphemeralWrappedAgentEvent = Extract<
+    WrappedAgentEvent,
+    { type: EphemeralWrappedAgentEventType }
+>
+
+export type DurableWrappedAgentEvent = Exclude<WrappedAgentEvent, EphemeralWrappedAgentEvent>
+
+const ephemeralEventTypeSet = new Set<string>(ephemeralEventTypes)
+
+// Every product.* event is durable by construction; only the listed agent
+// deltas and the supervisor heartbeat are ephemeral.
+export function durabilityOf(type: WireEventBodyType): WireEventDurability {
+    return ephemeralEventTypeSet.has(type) ? 'ephemeral' : 'durable'
+}
+
+export function isEphemeralWrappedAgentEvent(body: WireEventBody): body is EphemeralWrappedAgentEvent {
+    return body.type !== 'supervisor.heartbeat' && ephemeralEventTypeSet.has(body.type)
+}

package/src/supervisor-protocol/envelope.ts

@@ -0,0 +1,58 @@
+import z from 'zod'
+import { controlPlaneToSupervisorEnvelopeSchema } from './envelopes/control-plane-to-supervisor'
+import { supervisorToControlPlaneEnvelopeSchema } from './envelopes/supervisor-to-control-plane'
+
+export {
+    commandSequenceSchema,
+    connectionGenerationSchema,
+    eventSequenceSchema,
+    sequenceFloorSchema,
+    timestampSchema,
+} from './envelopes/common'
+
+export {
+    commandEnvelopeSchema,
+    controlPlaneToSupervisorEnvelopeKinds,
+    controlPlaneToSupervisorEnvelopeSchema,
+    eventAckEnvelopeSchema,
+    sessionBootstrapEnvelopeSchema,
+} from './envelopes/control-plane-to-supervisor'
+export type {
+    CommandEnvelope,
+    ControlPlaneToSupervisorEnvelope,
+    EventAckEnvelope,
+    SessionBootstrapEnvelope,
+} from './envelopes/control-plane-to-supervisor'
+
+export {
+    commandAckEnvelopeSchema,
+    commandAckErrorCodeSchema,
+    commandAckStatusSchema,
+    durableEventEnvelopeSchema,
+    ephemeralEventEnvelopeSchema,
+    eventDeliverySemanticsSchema,
+    eventEnvelopeSchema,
+    receivedCommandAckEnvelopeSchema,
+    rejectedCommandAckEnvelopeSchema,
+    runtimeStateEnvelopeSchema,
+    supervisorToControlPlaneEnvelopeKinds,
+    supervisorToControlPlaneEnvelopeSchema,
+} from './envelopes/supervisor-to-control-plane'
+export type {
+    CommandAckEnvelope,
+    CommandAckStatus,
+    DurableEventEnvelope,
+    EphemeralEventEnvelope,
+    EventEnvelope,
+    ReceivedCommandAckEnvelope,
+    RejectedCommandAckEnvelope,
+    RuntimeStateEnvelope,
+    SupervisorToControlPlaneEnvelope,
+} from './envelopes/supervisor-to-control-plane'
+
+export const wireEnvelopeSchema = z.union([
+    controlPlaneToSupervisorEnvelopeSchema,
+    supervisorToControlPlaneEnvelopeSchema,
+])
+
+export type WireEnvelope = z.infer<typeof wireEnvelopeSchema>

package/src/supervisor-protocol/envelopes/common.ts

@@ -0,0 +1,7 @@
+import z from 'zod'
+
+export const eventSequenceSchema = z.number().int().positive()
+export const sequenceFloorSchema = z.number().int().nonnegative()
+export const commandSequenceSchema = z.number().int().positive()
+export const connectionGenerationSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER)
+export const timestampSchema = z.string().datetime()

package/src/supervisor-protocol/envelopes/control-plane-to-supervisor.ts

@@ -0,0 +1,38 @@
+import z from 'zod'
+import { ephemeralCredentialsSchema, sessionBootstrapBodySchema, sessionBootstrapGitTokenSchema } from '../bootstrap'
+import { supervisorRpcResponseEnvelopeSchema } from '../rpc'
+import { commandSequenceSchema, sequenceFloorSchema } from './common'
+
+export const sessionBootstrapEnvelopeSchema = z.object({
+    kind: z.literal('session.bootstrap'),
+    connectionGeneration: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    body: sessionBootstrapBodySchema,
+    gitToken: sessionBootstrapGitTokenSchema.optional(),
+    credentials: ephemeralCredentialsSchema.optional(),
+}).strict()
+
+export const eventAckEnvelopeSchema = z.object({
+    kind: z.literal('event.ack'),
+    highWaterMark: sequenceFloorSchema,
+}).strict()
+
+export const commandEnvelopeSchema = z.object({
+    kind: z.literal('command'),
+    commandId: z.string().min(1),
+    commandSeq: commandSequenceSchema,
+    body: z.unknown(),
+}).strict()
+
+export const controlPlaneToSupervisorEnvelopeSchema = z.union([
+    sessionBootstrapEnvelopeSchema,
+    eventAckEnvelopeSchema,
+    commandEnvelopeSchema,
+    supervisorRpcResponseEnvelopeSchema,
+])
+
+export const controlPlaneToSupervisorEnvelopeKinds = ['session.bootstrap', 'event.ack', 'command', 'rpc.response'] as const
+
+export type SessionBootstrapEnvelope = z.infer<typeof sessionBootstrapEnvelopeSchema>
+export type EventAckEnvelope = z.infer<typeof eventAckEnvelopeSchema>
+export type CommandEnvelope = z.infer<typeof commandEnvelopeSchema>
+export type ControlPlaneToSupervisorEnvelope = z.infer<typeof controlPlaneToSupervisorEnvelopeSchema>

package/src/supervisor-protocol/envelopes/supervisor-to-control-plane.ts

@@ -0,0 +1,89 @@
+import z from 'zod'
+import { durabilityOf } from '../durability'
+import { wireEventBodySchema } from '../event-body'
+import { supervisorRpcCancelEnvelopeSchema, supervisorRpcRequestEnvelopeSchema } from '../rpc'
+import { supervisorAgentRunSnapshotSchema } from '../supervisor-agent-run-snapshot'
+import { commandSequenceSchema, eventSequenceSchema, timestampSchema } from './common'
+
+export const eventDeliverySemanticsSchema = z.enum(['durable', 'ephemeral'])
+export const commandAckStatusSchema = z.enum(['received', 'rejected'])
+export const commandAckErrorCodeSchema = z.string()
+    .min(3)
+    .max(100)
+    .regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/u)
+
+export const runtimeStateEnvelopeSchema = z.object({
+    kind: z.literal('runtime.state'),
+    lastReceivedCommandSeq: z.number().int().nonnegative(),
+    nextEventSeq: eventSequenceSchema,
+    agentRun: supervisorAgentRunSnapshotSchema,
+}).strict()
+
+export const durableEventEnvelopeSchema = z.object({
+    kind: z.literal('event'),
+    delivery_semantics: z.literal('durable'),
+    seq: eventSequenceSchema,
+    occurredAt: timestampSchema,
+    body: wireEventBodySchema,
+}).strict()
+
+export const ephemeralEventEnvelopeSchema = z.object({
+    kind: z.literal('event'),
+    delivery_semantics: z.literal('ephemeral'),
+    occurredAt: timestampSchema,
+    body: wireEventBodySchema,
+}).strict()
+
+export const eventEnvelopeSchema = z.discriminatedUnion('delivery_semantics', [
+    durableEventEnvelopeSchema,
+    ephemeralEventEnvelopeSchema,
+]).superRefine((envelope, context) => {
+    const expected = durabilityOf(envelope.body.type)
+    if (expected !== envelope.delivery_semantics) {
+        context.addIssue({
+            code: 'custom',
+            message: `Event body type "${envelope.body.type}" is ${expected}, but the envelope is marked ${envelope.delivery_semantics}.`,
+        })
+    }
+})
+
+const commandAckIdentitySchema = z.object({
+    kind: z.literal('command.ack'),
+    commandId: z.string().min(1),
+    commandSeq: commandSequenceSchema,
+}).strict()
+
+export const receivedCommandAckEnvelopeSchema = commandAckIdentitySchema.extend({
+    status: z.literal('received'),
+}).strict()
+
+export const rejectedCommandAckEnvelopeSchema = commandAckIdentitySchema.extend({
+    status: z.literal('rejected'),
+    errorCode: commandAckErrorCodeSchema,
+    detail: z.string().min(1).max(240).optional(),
+}).strict()
+
+export const commandAckEnvelopeSchema = z.discriminatedUnion('status', [
+    receivedCommandAckEnvelopeSchema,
+    rejectedCommandAckEnvelopeSchema,
+])
+
+export const supervisorToControlPlaneEnvelopeSchema = z.union([
+    runtimeStateEnvelopeSchema,
+    eventEnvelopeSchema,
+    commandAckEnvelopeSchema,
+    supervisorRpcRequestEnvelopeSchema,
+    supervisorRpcCancelEnvelopeSchema,
+])
+
+export const supervisorToControlPlaneEnvelopeKinds = ['runtime.state', 'event', 'command.ack', 'rpc.request', 'rpc.cancel'] as const
+
+export type CommandAckStatus = z.infer<typeof commandAckStatusSchema>
+export type ReceivedCommandAckEnvelope = z.infer<typeof receivedCommandAckEnvelopeSchema>
+export type RejectedCommandAckEnvelope = z.infer<typeof rejectedCommandAckEnvelopeSchema>
+export type RuntimeStateEnvelope = z.infer<typeof runtimeStateEnvelopeSchema>
+export type DurableEventEnvelope = z.infer<typeof durableEventEnvelopeSchema>
+export type EphemeralEventEnvelope = z.infer<typeof ephemeralEventEnvelopeSchema>
+export type EventEnvelope = z.infer<typeof eventEnvelopeSchema>
+export type CommandAckEnvelope = z.infer<typeof commandAckEnvelopeSchema>
+export type SupervisorToControlPlaneEnvelope = z.infer<typeof supervisorToControlPlaneEnvelopeSchema>

package/src/supervisor-protocol/event-body.ts

@@ -0,0 +1,13 @@
+import z from 'zod'
+import { wrappedAgentEventSchema } from './agent-event-wrapper'
+import { productEventSchema } from './product-event'
+import { supervisorEventSchema } from './supervisor-event'
+
+export const wireEventBodySchema = z.union([
+    wrappedAgentEventSchema,
+    supervisorEventSchema,
+    productEventSchema,
+])
+
+export type WireEventBody = z.infer<typeof wireEventBodySchema>
+export type WireEventBodyType = WireEventBody['type']

package/src/supervisor-protocol/input-attachment-content.ts

@@ -0,0 +1,3 @@
+export const inputAttachmentContentTypeHeader = 'content-type' as const
+export const inputAttachmentCacheControlHeader = 'cache-control' as const
+export const inputAttachmentCacheControlValue = 'private, no-store' as const

package/src/supervisor-protocol/payload-overflow.ts

@@ -0,0 +1,15 @@
+export { agentPayloadOverflowSchema } from '../protocol'
+export type { AgentPayloadOverflow } from '../protocol'
+
+/** Hard cap on a single WebSocket frame in either direction. */
+export const maxWireFrameBytes = 128 * 1024
+/**
+ * Largest durable event body a supervisor may emit inline. Bodies above this
+ * are truncated to a bounded head and spilled through the host's
+ * `LargePayloadStore`, with the full value referenced by `overflow`.
+ */
+export const maxDurableEventBytes = 96 * 1024
+/** Cap on each ephemeral streaming delta (message, reasoning, tool output). */
+export const maxEphemeralDeltaBytes = 16 * 1024
+/** Cap on a `product.*` event payload. */
+export const maxProductEventPayloadBytes = 64 * 1024

package/src/supervisor-protocol/product-event.ts

@@ -0,0 +1,27 @@
+import z from 'zod'
+import { jsonUtf8ByteLength, jsonValueSchema } from '../protocol'
+import { maxProductEventPayloadBytes } from './payload-overflow'
+
+/**
+ * Durable events emitted by a product's supervisor extensions (for example
+ * agent-api's `product.turn.result`). agent-core relays them untouched; only
+ * the type namespace and payload size are enforced here.
+ */
+export const productEventTypePattern = /^product\.[a-z][a-z0-9.-]+$/u
+
+export const productEventTypeSchema = z.string().max(128).regex(productEventTypePattern)
+
+export const productEventSchema = z.object({
+    type: productEventTypeSchema as z.ZodType<ProductEventType>,
+    payload: jsonValueSchema.refine(
+        value => jsonUtf8ByteLength(value) <= maxProductEventPayloadBytes,
+        { message: `product event payload must encode to at most ${maxProductEventPayloadBytes} bytes` },
+    ),
+}).strict()
+
+export type ProductEventType = `product.${string}`
+export type ProductEvent = z.infer<typeof productEventSchema>
+
+export function isProductEventType(type: string): type is ProductEventType {
+    return productEventTypePattern.test(type)
+}

package/src/supervisor-protocol/profile.ts

@@ -0,0 +1,22 @@
+import z from 'zod'
+import { jsonObjectSchema, jsonUtf8ByteLength } from '../protocol'
+
+/**
+ * A profile names the product that operates a sandbox (for example `agent-api`
+ * or `coding-agent`) and carries the product-specific bootstrap data its
+ * supervisor extensions consume. agent-core never interprets `data`; it only
+ * bounds it and hands it to the host's `SupervisorExtensions`.
+ */
+export const sessionProfileNameSchema = z.string().max(64).regex(/^[a-z][a-z0-9-]*$/u)
+export const sessionProfileMaxDataBytes = 32 * 1024
+
+export const sessionProfileSchema = z.object({
+    name: sessionProfileNameSchema,
+    version: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    data: jsonObjectSchema.refine(
+        value => jsonUtf8ByteLength(value) <= sessionProfileMaxDataBytes,
+        { message: `profile data must encode to at most ${sessionProfileMaxDataBytes} bytes` },
+    ),
+}).strict()
+
+export type SessionProfile = z.infer<typeof sessionProfileSchema>

package/src/supervisor-protocol/rpc.ts

@@ -0,0 +1,77 @@
+import z from 'zod'
+
+/**
+ * Reverse RPC methods every supervisor may call on its control plane. The first
+ * ten are the coding-agent set; `credentials.issue` and `payload.put-grant` are
+ * the product-neutral additions agent-core hosts implement. Products register
+ * further methods under the `x-<profile>.` namespace.
+ */
+export const supervisorRpcMethods = [
+    'git.issue-token',
+    'git.resolve-repository',
+    'codex.auth.start',
+    'codex.auth.refresh',
+    'git.generate-commit-message',
+    'tool.execute',
+    'artifact.initiate',
+    'artifact.complete',
+    'input-attachment.get-content-grant',
+    'context-file.get-content-grant',
+    'credentials.issue',
+    'payload.put-grant',
+] as const
+
+export const productRpcMethodPattern = /^x-[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]+)+$/u
+
+export const builtinSupervisorRpcMethodSchema = z.enum(supervisorRpcMethods)
+export const productRpcMethodSchema = z.string().max(128).regex(productRpcMethodPattern)
+const supervisorRpcMethodSchema = z.union([builtinSupervisorRpcMethodSchema, productRpcMethodSchema])
+
+export type BuiltinSupervisorRpcMethod = typeof supervisorRpcMethods[number]
+export type ProductRpcMethod = `x-${string}.${string}`
+export type SupervisorRpcMethod = BuiltinSupervisorRpcMethod | ProductRpcMethod
+
+export function isProductRpcMethod(method: string): method is ProductRpcMethod {
+    return productRpcMethodPattern.test(method)
+}
+
+export function isBuiltinSupervisorRpcMethod(method: string): method is BuiltinSupervisorRpcMethod {
+    return (supervisorRpcMethods as readonly string[]).includes(method)
+}
+
+export const supervisorRpcRequestEnvelopeSchema = z.object({
+    kind: z.literal('rpc.request'),
+    requestId: z.string().min(1),
+    method: supervisorRpcMethodSchema as z.ZodType<SupervisorRpcMethod>,
+    deadlineMs: z.number().int().positive().max(10 * 60 * 1_000),
+    body: z.unknown(),
+}).strict()
+
+const supervisorRpcSuccessSchema = z.object({
+    status: z.literal('ok'),
+    value: z.unknown(),
+}).strict()
+
+const supervisorRpcFailureSchema = z.object({
+    status: z.literal('error'),
+    error: z.object({
+        code: z.string().min(1),
+        message: z.string().min(1),
+        retryable: z.boolean(),
+    }).strict(),
+}).strict()
+
+export const supervisorRpcCancelEnvelopeSchema = z.object({
+    kind: z.literal('rpc.cancel'),
+    requestId: z.string().min(1),
+}).strict()
+
+export const supervisorRpcResponseEnvelopeSchema = z.object({
+    kind: z.literal('rpc.response'),
+    requestId: z.string().min(1),
+    result: z.discriminatedUnion('status', [supervisorRpcSuccessSchema, supervisorRpcFailureSchema]),
+}).strict()
+
+export type SupervisorRpcRequestEnvelope = z.infer<typeof supervisorRpcRequestEnvelopeSchema>
+export type SupervisorRpcCancelEnvelope = z.infer<typeof supervisorRpcCancelEnvelopeSchema>
+export type SupervisorRpcResponseEnvelope = z.infer<typeof supervisorRpcResponseEnvelopeSchema>

package/src/supervisor-protocol/supervisor-agent-run-snapshot.ts

@@ -0,0 +1,12 @@
+import z from 'zod'
+import { agentSessionStateSchema } from '../protocol'
+
+export const supervisorAgentRunSnapshotSchema = z.discriminatedUnion('status', [
+    z.object({ status: z.literal('not_attached') }).strict(),
+    z.object({
+        status: z.literal('attached'),
+        agentState: agentSessionStateSchema.nullable(),
+    }).strict(),
+])
+
+export type SupervisorAgentRunSnapshot = z.infer<typeof supervisorAgentRunSnapshotSchema>