@meistrari/agent-core 0.0.0

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

@@ -0,0 +1,361 @@
+import type { AgentError } from '../protocol'
+import z from 'zod'
+import { agentErrorSchema } from '../protocol'
+import { timestampSchema } from './envelopes/common'
+import { supervisorAgentRunSnapshotSchema } from './supervisor-agent-run-snapshot'
+
+export const inputAttachmentDeliveryFailureReasonSchema = z.enum([
+    'authorization',
+    'not_found',
+    'network',
+    'timeout',
+    'invalid_response',
+    'size_mismatch',
+    'sha256_mismatch',
+    'filesystem',
+])
+
+export type InputAttachmentDeliveryFailureReason = z.infer<typeof inputAttachmentDeliveryFailureReasonSchema>
+
+type SupervisorCommandFailure
+    = | {
+        type: 'command'
+        detail: string
+        error?: AgentError
+    }
+    | {
+        type: 'input_attachment'
+        attachmentId: string
+        reason: InputAttachmentDeliveryFailureReason
+        detail: string
+    }
+
+type SupervisorCommandFailedEvent
+    = | {
+        type: 'supervisor.command.failed'
+        payload: {
+            commandId: string
+            commandSeq: number
+            bodyType: 'agent.send-prompt'
+            failure: Extract<SupervisorCommandFailure, { type: 'input_attachment' }>
+        }
+    }
+    | {
+        type: 'supervisor.command.failed'
+        payload: {
+            commandId: string
+            commandSeq: number
+            bodyType: string
+            failure: Extract<SupervisorCommandFailure, { type: 'command' }>
+        }
+    }
+
+const supervisorShutdownReasonSchema = z.enum([
+    'sigterm',
+    'sigint',
+    'fatal_error',
+])
+
+const supervisorGitTriggerSchema = z.enum(['turn-ended', 'boot-reconcile'])
+
+const supervisorGitCommitFailureReasonSchema = z.literal('unknown')
+
+const supervisorGitPushFailureReasonSchema = z.enum([
+    'non-fast-forward',
+    'auth',
+    'network',
+    'rejected',
+    'unknown',
+])
+
+const supervisorGitRecoveryPromptFailureReasonSchema = z.enum(['dispatch-failed'])
+
+const supervisorGitEventCommonPayloadFields = {
+    turnId: z.string(),
+    repository: z.string(),
+    branch: z.string(),
+    trigger: supervisorGitTriggerSchema,
+}
+
+const sessionWorkspaceGitRepositorySchema = z.object({
+    id: z.string().min(1),
+    fullName: z.string().max(256).regex(/^[^/\s]+\/[^/\s]+$/),
+}).strict()
+
+const sessionWorkspaceGitRevisionPayloadFields = {
+    repository: sessionWorkspaceGitRepositorySchema,
+    branch: z.string().min(1),
+    sha: z.string().regex(/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/),
+}
+
+const sessionWorkspaceGitPayloadSchema = z.object({
+    ...sessionWorkspaceGitRevisionPayloadFields,
+    turnId: z.string().min(1),
+    trigger: supervisorGitTriggerSchema,
+}).strict()
+
+const supervisorInterruptionRecoveryCommonPayloadFields = {
+    sourceCommandId: z.string().min(1),
+    recoveryCommandId: z.string().min(1),
+    attempt: z.number().int().positive(),
+}
+
+const supervisorInterruptionRecoveryAcceptanceSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('submitted'),
+    }).strict(),
+    z.object({
+        kind: z.literal('turn'),
+        resultingTurnId: z.string().min(1),
+    }).strict(),
+])
+
+const supervisorInterruptionRecoveryOperationSchema = z.enum([
+    'resume',
+    'dispatch',
+])
+
+const supervisorInterruptionRecoveryWaitSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('retry'),
+        reason: z.string().min(1),
+        nextAttemptAt: timestampSchema,
+    }).strict(),
+    z.object({
+        kind: z.literal('external_action'),
+        reason: z.string().min(1),
+        nextAttemptAt: timestampSchema,
+    }).strict(),
+])
+
+const supervisorInterruptionRecoveryFailureSchema = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('provider_rejected'),
+        operation: supervisorInterruptionRecoveryOperationSchema,
+        reason: z.string().min(1),
+    }).strict(),
+    z.object({
+        kind: z.literal('turn'),
+        resultingTurnId: z.string().min(1),
+        status: z.enum(['failed', 'interrupted', 'cancelled']),
+    }).strict(),
+])
+
+const supervisorInterruptionRecoveryRequestedEventSchema = z.object({
+    type: z.literal('supervisor.interruption_recovery.requested'),
+    payload: z.object({
+        ...supervisorInterruptionRecoveryCommonPayloadFields,
+    }).strict(),
+}).strict()
+
+const supervisorInterruptionRecoveryAcceptedEventSchema = z.object({
+    type: z.literal('supervisor.interruption_recovery.accepted'),
+    payload: z.object({
+        ...supervisorInterruptionRecoveryCommonPayloadFields,
+        acceptance: supervisorInterruptionRecoveryAcceptanceSchema,
+    }).strict(),
+}).strict()
+
+const supervisorInterruptionRecoveryWaitingEventSchema = z.object({
+    type: z.literal('supervisor.interruption_recovery.waiting'),
+    payload: z.object({
+        ...supervisorInterruptionRecoveryCommonPayloadFields,
+        operation: supervisorInterruptionRecoveryOperationSchema,
+        wait: supervisorInterruptionRecoveryWaitSchema,
+    }).strict(),
+}).strict()
+
+const supervisorInterruptionRecoveryTurnCorrelatedEventSchema = z.object({
+    type: z.literal('supervisor.interruption_recovery.turn_correlated'),
+    payload: z.object({
+        ...supervisorInterruptionRecoveryCommonPayloadFields,
+        resultingTurnId: z.string().min(1),
+    }).strict(),
+}).strict()
+
+const supervisorInterruptionRecoveryFailedEventSchema = z.object({
+    type: z.literal('supervisor.interruption_recovery.failed'),
+    payload: z.object({
+        ...supervisorInterruptionRecoveryCommonPayloadFields,
+        failure: supervisorInterruptionRecoveryFailureSchema,
+    }).strict(),
+}).strict()
+
+const supervisorStartedEventSchema = z.object({
+    type: z.literal('supervisor.started'),
+    payload: z.object({}).strict(),
+}).strict()
+
+const supervisorAgentRunChangedEventSchema = z.object({
+    type: z.literal('supervisor.agent_run.changed'),
+    payload: z.object({
+        agentRun: supervisorAgentRunSnapshotSchema,
+    }).strict(),
+}).strict()
+
+const supervisorHeartbeatEventSchema = z.object({
+    type: z.literal('supervisor.heartbeat'),
+    payload: z.object({
+        unackedEventCount: z.number().int().nonnegative(),
+    }).strict(),
+}).strict()
+
+const supervisorShuttingDownEventSchema = z.object({
+    type: z.literal('supervisor.shutting_down'),
+    payload: z.object({
+        reason: supervisorShutdownReasonSchema,
+        detail: z.string().min(1).optional(),
+    }).strict(),
+}).strict()
+
+const supervisorSessionResumedEventSchema = z.object({
+    type: z.literal('supervisor.session_resumed'),
+    payload: z.object({
+        gapDuration: z.number().nonnegative(),
+    }).strict(),
+}).strict()
+
+const commandOutcomePayloadSchema = z.object({
+    commandId: z.string().min(1),
+    commandSeq: z.number().int().positive(),
+    bodyType: z.string().min(1),
+}).strict()
+
+const supervisorCommandAppliedEventSchema = z.object({
+    type: z.literal('supervisor.command.applied'),
+    payload: commandOutcomePayloadSchema,
+}).strict()
+
+const supervisorCommandTurnCorrelatedEventSchema = z.object({
+    type: z.literal('supervisor.command.turn_correlated'),
+    payload: commandOutcomePayloadSchema.extend({
+        bodyType: z.literal('agent.send-prompt'),
+        turnId: z.string().min(1),
+    }).strict(),
+}).strict()
+
+const supervisorCommandFailureSchema = z.object({
+    type: z.literal('command'),
+    detail: z.string().min(1),
+    error: agentErrorSchema.optional(),
+}).strict()
+
+const supervisorInputAttachmentFailureSchema = z.object({
+    type: z.literal('input_attachment'),
+    attachmentId: z.string().min(1),
+    reason: inputAttachmentDeliveryFailureReasonSchema,
+    detail: z.string().min(1),
+}).strict()
+
+const supervisorInputAttachmentCommandFailedPayloadSchema = commandOutcomePayloadSchema.extend({
+    bodyType: z.literal('agent.send-prompt'),
+    failure: supervisorInputAttachmentFailureSchema,
+}).strict() satisfies z.ZodType<SupervisorCommandFailedEvent['payload']>
+
+const supervisorOrdinaryCommandFailedPayloadSchema = commandOutcomePayloadSchema.extend({
+    failure: supervisorCommandFailureSchema,
+}).strict() satisfies z.ZodType<SupervisorCommandFailedEvent['payload']>
+
+const supervisorCommandFailedEventSchema = z.object({
+    type: z.literal('supervisor.command.failed'),
+    payload: z.union([
+        supervisorInputAttachmentCommandFailedPayloadSchema,
+        supervisorOrdinaryCommandFailedPayloadSchema,
+    ]),
+}).strict()
+
+// Deployed immutable supervisors retain these durable v1 event bodies for their sandbox lifetime.
+const legacySupervisorGitCommitCompletedEventSchema = z.object({
+    type: z.literal('supervisor.git.commit.completed'),
+    payload: z.object({
+        ...supervisorGitEventCommonPayloadFields,
+        commitSha: z.string(),
+    }).strict(),
+}).strict()
+
+const sessionWorkspaceGitInitializedEventSchema = z.object({
+    type: z.literal('session.workspace.git.initialized'),
+    payload: z.object(sessionWorkspaceGitRevisionPayloadFields).strict(),
+}).strict()
+
+const sessionWorkspaceReadyEventSchema = z.object({
+    type: z.literal('session.workspace.ready'),
+    payload: z.object({
+        repositories: z.array(z.object(sessionWorkspaceGitRevisionPayloadFields).strict()),
+    }).strict(),
+}).strict()
+
+const sessionWorkspaceGitCommittedEventSchema = z.object({
+    type: z.literal('session.workspace.git.committed'),
+    payload: sessionWorkspaceGitPayloadSchema,
+}).strict()
+
+const supervisorGitCommitFailedEventSchema = z.object({
+    type: z.literal('supervisor.git.commit.failed'),
+    payload: z.object({
+        ...supervisorGitEventCommonPayloadFields,
+        reason: supervisorGitCommitFailureReasonSchema,
+        detail: z.string(),
+    }).strict(),
+}).strict()
+
+const legacySupervisorGitPushCompletedEventSchema = z.object({
+    type: z.literal('supervisor.git.push.completed'),
+    payload: z.object({
+        ...supervisorGitEventCommonPayloadFields,
+        remoteHeadSha: z.string(),
+    }).strict(),
+}).strict()
+
+const sessionWorkspaceGitPushedEventSchema = z.object({
+    type: z.literal('session.workspace.git.pushed'),
+    payload: sessionWorkspaceGitPayloadSchema,
+}).strict()
+
+const supervisorGitPushFailedEventSchema = z.object({
+    type: z.literal('supervisor.git.push.failed'),
+    payload: z.object({
+        ...supervisorGitEventCommonPayloadFields,
+        reason: supervisorGitPushFailureReasonSchema,
+        detail: z.string(),
+    }).strict(),
+}).strict()
+
+const supervisorGitRecoveryPromptFailedEventSchema = z.object({
+    type: z.literal('supervisor.git.recovery_prompt.failed'),
+    payload: z.object({
+        turnId: z.string(),
+        branch: z.string(),
+        trigger: supervisorGitTriggerSchema,
+        commandId: z.string().min(1),
+        reason: supervisorGitRecoveryPromptFailureReasonSchema,
+        detail: z.string(),
+    }).strict(),
+}).strict()
+
+export const supervisorEventSchema = z.discriminatedUnion('type', [
+    supervisorStartedEventSchema,
+    supervisorAgentRunChangedEventSchema,
+    supervisorHeartbeatEventSchema,
+    supervisorShuttingDownEventSchema,
+    supervisorSessionResumedEventSchema,
+    supervisorCommandAppliedEventSchema,
+    supervisorCommandTurnCorrelatedEventSchema,
+    supervisorCommandFailedEventSchema,
+    supervisorInterruptionRecoveryRequestedEventSchema,
+    supervisorInterruptionRecoveryAcceptedEventSchema,
+    supervisorInterruptionRecoveryWaitingEventSchema,
+    supervisorInterruptionRecoveryTurnCorrelatedEventSchema,
+    supervisorInterruptionRecoveryFailedEventSchema,
+    legacySupervisorGitCommitCompletedEventSchema,
+    sessionWorkspaceGitInitializedEventSchema,
+    sessionWorkspaceReadyEventSchema,
+    sessionWorkspaceGitCommittedEventSchema,
+    supervisorGitCommitFailedEventSchema,
+    legacySupervisorGitPushCompletedEventSchema,
+    sessionWorkspaceGitPushedEventSchema,
+    supervisorGitPushFailedEventSchema,
+    supervisorGitRecoveryPromptFailedEventSchema,
+])
+
+export type SupervisorShutdownReason = z.infer<typeof supervisorShutdownReasonSchema>

package/src/supervisor-protocol/tela-page-content.ts

@@ -0,0 +1,6 @@
+export const telaPageCacheControlHeader = 'cache-control' as const
+export const telaPageCacheControlValue = 'private, no-store' as const
+export const telaPageContentTypeHeader = 'content-type' as const
+export const telaPageDeclaredSizeHeader = 'content-length' as const
+// Task-context materialization stays bounded independently of Pages Gateway storage limits.
+export const telaPageMaxBytes = 100 * 1024 * 1024

package/src/supervisor-protocol/wire-codec.ts

@@ -0,0 +1,71 @@
+import type {
+    ControlPlaneToSupervisorEnvelope,
+    SupervisorToControlPlaneEnvelope,
+    WireEnvelope,
+} from './envelope'
+import z from 'zod'
+import {
+    controlPlaneToSupervisorEnvelopeKinds,
+    controlPlaneToSupervisorEnvelopeSchema,
+    supervisorToControlPlaneEnvelopeKinds,
+    supervisorToControlPlaneEnvelopeSchema,
+    wireEnvelopeSchema,
+} from './envelope'
+
+const knownEnvelopeKinds = ['session.bootstrap', 'command', 'event.ack', 'rpc.response', 'runtime.state', 'event', 'command.ack', 'rpc.request', 'rpc.cancel'] as const
+const envelopeProbeSchema = z.object({ kind: z.string() }).passthrough()
+
+export type DecodedFrame<TFrame>
+    = | { kind: 'ok', frame: TFrame }
+        | { kind: 'unknown', detail: string }
+        | { kind: 'invalid', detail: string }
+
+export type DecodedWireFrame = DecodedFrame<WireEnvelope>
+export type DecodedControlPlaneFrame = DecodedFrame<ControlPlaneToSupervisorEnvelope>
+export type DecodedSupervisorFrame = DecodedFrame<SupervisorToControlPlaneEnvelope>
+
+export function decodeWireFrame(text: string): DecodedWireFrame {
+    return decodeWithSchema({ text, schema: wireEnvelopeSchema, knownKinds: knownEnvelopeKinds, direction: 'wire' })
+}
+
+export function decodeControlPlaneFrame(text: string): DecodedControlPlaneFrame {
+    return decodeWithSchema({
+        text,
+        schema: controlPlaneToSupervisorEnvelopeSchema,
+        knownKinds: controlPlaneToSupervisorEnvelopeKinds,
+        direction: 'control-plane',
+    })
+}
+
+export function decodeSupervisorFrame(text: string): DecodedSupervisorFrame {
+    return decodeWithSchema({
+        text,
+        schema: supervisorToControlPlaneEnvelopeSchema,
+        knownKinds: supervisorToControlPlaneEnvelopeKinds,
+        direction: 'supervisor',
+    })
+}
+
+export function encodeWireFrame(frame: WireEnvelope): string {
+    return JSON.stringify(frame)
+}
+
+function decodeWithSchema<TFrame>({ text, schema, knownKinds, direction }: { text: string, schema: z.ZodType<TFrame>, knownKinds: readonly string[], direction: string }): DecodedFrame<TFrame> {
+    let value: unknown
+    try {
+        value = JSON.parse(text)
+    }
+    catch {
+        return { kind: 'invalid', detail: 'Frame is not valid JSON.' }
+    }
+
+    const probe = envelopeProbeSchema.safeParse(value)
+    if (probe.success && !knownKinds.includes(probe.data.kind))
+        return { kind: 'unknown', detail: `Unknown ${direction} envelope kind: ${probe.data.kind}` }
+
+    const parsed = schema.safeParse(value)
+    if (!parsed.success)
+        return { kind: 'invalid', detail: `Frame does not match ${direction} envelope schema.` }
+
+    return { kind: 'ok', frame: parsed.data }
+}

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "lib": ["ES2024"],
+        "moduleDetection": "force",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "types": ["bun"],
+        "strict": true,
+        "allowUnreachableCode": false,
+        "allowUnusedLabels": false,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noImplicitReturns": true,
+        "noUncheckedIndexedAccess": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noEmit": true,
+        "isolatedModules": true,
+        "verbatimModuleSyntax": true,
+        "skipLibCheck": true
+    },
+    "include": ["src", "bin", "scripts", "e2e"]
+}