@aria-cli/tools 1.0.0

package/src/network-runtime/local-control-contract.ts

@@ -0,0 +1,778 @@
+import { z } from "zod";
+import type { Message } from "@aria/types";
+import {
+  ClientIdSchema,
+  ControlEndpointAdvertisementSchema,
+  EndpointRevisionSchema,
+  InboxAddressSchema,
+  NodeIdSchema,
+  PrincipalFingerprintSchema,
+  PeerTransportIdSchema,
+  RuntimeIdSchema,
+  TlsCaFingerprintSchema,
+  TransportEndpointAdvertisementSchema,
+} from "./address-types.js";
+import {
+  canonicalizeDeliveryReceipt,
+  DeliveryReceiptInputSchema,
+  RuntimeTransportSchema,
+  DeliveryStateSchema,
+  SessionStateSchema,
+  DeliveryReadinessSchema,
+  QueuedReasonSchema,
+} from "./delivery-receipts.js";
+import { AcceptInviteRequestSchema } from "./pair-route-contract.js";
+import { PeerIdentityStateSchema, PeerTransportStateSchema } from "./peer-state-machine.js";
+import type { AcceptInviteRequest } from "./pair-route-contract.js";
+
+const NonEmptyStringSchema = z.string().trim().min(1);
+const AutonomySchema = z.enum(["minimal", "balanced", "high", "full"]);
+const ToolNameListSchema = z.array(z.string()).optional();
+const MessageHistorySchema = z.array(z.custom<Message>()).optional();
+
+function toFastifyBodyJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {
+  const jsonSchema = z.toJSONSchema(schema) as Record<string, unknown>;
+  delete jsonSchema.$schema;
+  return jsonSchema;
+}
+
+export { AcceptInviteRequestSchema };
+export type { AcceptInviteRequest };
+
+export const RunRequestSchema = z
+  .object({
+    task: NonEmptyStringSchema,
+    arion: NonEmptyStringSchema.optional(),
+    cwd: NonEmptyStringSchema.optional(),
+    history: MessageHistorySchema,
+    preferredTier: z.enum(["fast", "balanced", "powerful", "ensemble"]).optional(),
+    budget: z.number().positive().optional(),
+    maxTurns: z.number().int().positive().optional(),
+    autonomy: AutonomySchema.optional(),
+    allowedTools: ToolNameListSchema,
+    deniedTools: ToolNameListSchema,
+    noMemory: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+    approvalMode: z.enum(["pause", "approve", "deny"]).optional(),
+    askUserAnswers: z.array(z.string()).optional(),
+  })
+  .strict();
+export type RunRequest = z.infer<typeof RunRequestSchema>;
+
+export const RuntimeErrorDiagnosticSchema: z.ZodType<Record<string, unknown>> = z.lazy(() =>
+  z
+    .object({
+      message: z.string(),
+      name: z.string().optional(),
+      stack: z.string().optional(),
+      cause: RuntimeErrorDiagnosticSchema.optional(),
+    })
+    .catchall(z.unknown()),
+);
+export type RuntimeErrorDiagnostic = z.infer<typeof RuntimeErrorDiagnosticSchema>;
+
+function extractRuntimeDiagnosticMessage(diagnostic: unknown): string | undefined {
+  if (!diagnostic || typeof diagnostic !== "object") {
+    return undefined;
+  }
+  const message = (diagnostic as { message?: unknown }).message;
+  if (typeof message !== "string") {
+    return undefined;
+  }
+  const trimmed = message.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function isGenericTrustedRuntimeMessage(message: string): boolean {
+  const normalized = message.trim().toLowerCase();
+  return (
+    normalized === "internal server error" ||
+    normalized.startsWith("internal server error:") ||
+    normalized.startsWith("http 500")
+  );
+}
+
+export function resolveTrustedRuntimeErrorMessage(
+  message: string | undefined,
+  diagnostic: unknown,
+): string | undefined {
+  const fallback = typeof message === "string" && message.trim().length > 0 ? message : undefined;
+  const diagnosticMessage = extractRuntimeDiagnosticMessage(diagnostic);
+  if (!diagnosticMessage) {
+    return fallback;
+  }
+  if (!fallback || isGenericTrustedRuntimeMessage(fallback)) {
+    return diagnosticMessage;
+  }
+  return fallback;
+}
+
+export function createTrustedRuntimeError(message: string | undefined, diagnostic: unknown): Error {
+  const resolvedMessage =
+    resolveTrustedRuntimeErrorMessage(message, diagnostic) ?? "Trusted runtime error";
+  return Object.assign(new Error(resolvedMessage), {
+    ...(diagnostic === undefined ? {} : { diagnostic }),
+    ...(typeof message === "string" && message.trim().length > 0 && message !== resolvedMessage
+      ? { publicMessage: message }
+      : {}),
+  });
+}
+
+export const RunResultSchema = z
+  .object({
+    success: z.boolean(),
+    output: z.string().optional(),
+    messages: z.array(z.unknown()).optional(),
+    toolCalls: z.array(z.unknown()).optional(),
+    usage: z.unknown().optional(),
+    turnCount: z.number().int().nonnegative().optional(),
+    thinking: z.array(z.unknown()).optional(),
+    nativeToolResults: z.array(z.unknown()).optional(),
+    traces: z.array(z.unknown()).optional(),
+    pipelineTiming: z.unknown().optional(),
+    guardrailEvents: z.array(z.unknown()).optional(),
+    handoffs: z.array(z.unknown()).optional(),
+    state: z.unknown().optional(),
+    error: z.string().optional(),
+    diagnostic: RuntimeErrorDiagnosticSchema.optional(),
+  })
+  .strict();
+export type RunResult = z.infer<typeof RunResultSchema>;
+
+export const ResumeRunRequestSchema = z
+  .object({
+    state: z.unknown(),
+    arion: NonEmptyStringSchema.optional(),
+    cwd: NonEmptyStringSchema.optional(),
+    preferredTier: z.enum(["fast", "balanced", "powerful", "ensemble"]).optional(),
+    budget: z.number().positive().optional(),
+    maxTurns: z.number().int().positive().optional(),
+    autonomy: AutonomySchema.optional(),
+    allowedTools: ToolNameListSchema,
+    deniedTools: ToolNameListSchema,
+    noMemory: z.boolean().optional(),
+    systemPrompt: z.string().optional(),
+    approvalMode: z.enum(["pause", "approve", "deny"]).optional(),
+    askUserAnswers: z.array(z.string()).optional(),
+  })
+  .strict();
+export type ResumeRunRequest = z.infer<typeof ResumeRunRequestSchema>;
+
+export const RuntimeRunEventSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("text_delta"),
+    content: z.string(),
+  }),
+  z.object({
+    type: z.literal("tool_start"),
+    id: NonEmptyStringSchema,
+    name: NonEmptyStringSchema,
+    input: z.unknown().optional(),
+  }),
+  z.object({
+    type: z.literal("approval_needed"),
+    toolName: NonEmptyStringSchema,
+    toolInput: z.unknown().optional(),
+    riskLevel: z.string().optional(),
+    issues: z.array(z.string()).optional(),
+  }),
+  z.object({
+    type: z.literal("tool_result"),
+    id: NonEmptyStringSchema,
+    name: NonEmptyStringSchema,
+    durationMs: z.number().nonnegative(),
+    result: z.unknown(),
+    input: z.unknown().optional(),
+  }),
+  z.object({
+    type: z.literal("usage_update"),
+    usage: z.unknown(),
+  }),
+  z.object({
+    type: z.literal("turn_complete"),
+    turnNumber: z.number().int().nonnegative(),
+  }),
+  z.object({
+    type: z.literal("guardrail_rejected"),
+    stage: z.enum(["input", "output"]),
+    message: z.string(),
+  }),
+  z.object({
+    type: z.literal("pipeline_timing"),
+    report: z.unknown(),
+  }),
+  z.object({
+    type: z.literal("messages_snapshot"),
+    messages: z.array(z.unknown()),
+  }),
+  z.object({
+    type: z.literal("error"),
+    error: z.object({
+      message: z.string(),
+      diagnostic: RuntimeErrorDiagnosticSchema.optional(),
+    }),
+  }),
+  z.object({
+    type: z.literal("native_tool_result"),
+    metadata: z.unknown(),
+  }),
+  z.object({
+    type: z.literal("thinking_start"),
+  }),
+  z.object({
+    type: z.literal("thinking_delta"),
+    content: z.string(),
+  }),
+  z.object({
+    type: z.literal("thinking_end"),
+    blocks: z.array(z.unknown()),
+    durationMs: z.number().nonnegative(),
+  }),
+  z.object({
+    type: z.literal("tool_args_delta"),
+    id: NonEmptyStringSchema,
+    args: z.string(),
+  }),
+  z.object({
+    type: z.literal("span_start"),
+    spanId: NonEmptyStringSchema,
+    spanType: NonEmptyStringSchema,
+    name: NonEmptyStringSchema,
+  }),
+  z.object({
+    type: z.literal("span_end"),
+    spanId: NonEmptyStringSchema,
+    durationMs: z.number().nonnegative(),
+  }),
+  z.object({
+    type: z.literal("handoff_start"),
+    target: NonEmptyStringSchema,
+    id: NonEmptyStringSchema,
+  }),
+  z.object({
+    type: z.literal("handoff_result"),
+    target: NonEmptyStringSchema,
+    result: z.string(),
+    id: NonEmptyStringSchema,
+  }),
+  z.object({
+    type: z.literal("paused"),
+    state: z.unknown(),
+  }),
+]);
+export type RuntimeRunEvent = z.infer<typeof RuntimeRunEventSchema>;
+
+export const RuntimeQueuedReceiptSchema = z
+  .object(DeliveryReceiptInputSchema.shape)
+  .strict()
+  .transform((receipt) => canonicalizeDeliveryReceipt(receipt));
+export type RuntimeQueuedReceipt = z.infer<typeof RuntimeQueuedReceiptSchema>;
+
+export const RuntimeDeliveryReceiptSchema = z
+  .object({
+    transport: RuntimeTransportSchema,
+    delivered: z.boolean(),
+    queued: z.boolean(),
+    accepted: z.boolean().optional(),
+    deliveryState: DeliveryStateSchema.optional(),
+    sessionState: SessionStateSchema.optional(),
+    deliveryReadiness: DeliveryReadinessSchema.optional(),
+    queuedReason: QueuedReasonSchema.optional(),
+    storedAt: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+  .transform(({ storedAt, ...receipt }) => ({
+    ...canonicalizeDeliveryReceipt(receipt),
+    ...(storedAt !== undefined ? { storedAt } : {}),
+  }));
+export type RuntimeDeliveryReceipt = z.infer<typeof RuntimeDeliveryReceiptSchema>;
+
+export const OutboundMessageSchema = z
+  .object({
+    rawMessage: z.record(z.string(), z.unknown()),
+    recipientInbox: InboxAddressSchema.optional(),
+    to: NonEmptyStringSchema.optional(),
+    content: z.string().optional(),
+    type: NonEmptyStringSchema.optional(),
+    priority: z.number().int().optional(),
+    correlationId: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+  .superRefine((message, ctx) => {
+    if (!message.recipientInbox || message.to === undefined) {
+      return;
+    }
+    if (message.recipientInbox.kind === "client") {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          'OutboundMessage.to is a compatibility alias for node recipients only; omit it for recipientInbox.kind === "client"',
+        path: ["to"],
+      });
+      return;
+    }
+    if (message.recipientInbox.nodeId !== message.to) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "OutboundMessage.recipientInbox.nodeId must match OutboundMessage.to when both are provided",
+        path: ["to"],
+      });
+    }
+  });
+export type OutboundMessage = z.infer<typeof OutboundMessageSchema>;
+
+export const RuntimeEventCursorSchema = z
+  .object({
+    afterRevision: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+export type RuntimeEventCursor = z.infer<typeof RuntimeEventCursorSchema>;
+
+export const InboxCursorSchema = z
+  .object({
+    afterCreatedAt: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+export type InboxCursor = z.infer<typeof InboxCursorSchema>;
+
+export const InboxListRequestSchema = z
+  .object({
+    cursor: InboxCursorSchema.optional(),
+    limit: z.number().int().positive().max(1000).optional(),
+    unreadOnly: z.boolean().optional(),
+  })
+  .strict();
+export type InboxListRequest = z.infer<typeof InboxListRequestSchema>;
+
+export const PersistedInboxEventSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    senderNodeId: NodeIdSchema,
+    senderDisplayNameSnapshot: NonEmptyStringSchema.optional(),
+    senderType: NonEmptyStringSchema.optional(),
+    inboxAddress: InboxAddressSchema,
+    type: NonEmptyStringSchema,
+    content: z.string(),
+    priority: z.number().int(),
+    createdAt: z.number().int().nonnegative(),
+    correlationId: z.string().nullable().optional(),
+    replyTo: z.string().nullable().optional(),
+  })
+  .strict();
+export type PersistedInboxEvent = z.infer<typeof PersistedInboxEventSchema>;
+
+export const PeerViewEventSchema = z
+  .object({
+    nodeId: NodeIdSchema,
+    transportPublicKey: PeerTransportIdSchema,
+    displayNameSnapshot: NonEmptyStringSchema.optional(),
+    identityState: PeerIdentityStateSchema,
+    transportState: PeerTransportStateSchema,
+    endpointRevision: EndpointRevisionSchema,
+    updatedAt: z.string(),
+    lastSeenAt: z.string().optional(),
+  })
+  .strict();
+export type PeerViewEvent = z.infer<typeof PeerViewEventSchema>;
+
+export const NearbyPeerViewSchema = z
+  .object({
+    displayNameSnapshot: NonEmptyStringSchema,
+    nodeId: NodeIdSchema,
+    host: NonEmptyStringSchema,
+    port: z.number().int().min(1).max(65535),
+    principalFingerprint: PrincipalFingerprintSchema,
+    version: NonEmptyStringSchema,
+    tlsCaFingerprint: TlsCaFingerprintSchema.optional(),
+    transport: z.enum(["lan", "wan"]).optional(),
+    status: z.enum(["discovered", "connected"]).optional(),
+  })
+  .strict();
+export type NearbyPeerView = z.infer<typeof NearbyPeerViewSchema>;
+
+export const RuntimeAutonomousLoopSafetyPolicySummarySchema = z
+  .object({
+    allowedToolCategories: z.array(NonEmptyStringSchema).optional(),
+    allowedShellCommands: z.array(NonEmptyStringSchema).optional(),
+    maxWriteOpsPerMinute: z.number().int().positive().optional(),
+    maxGitPushesPerHour: z.number().int().positive().optional(),
+  })
+  .strict();
+export type RuntimeAutonomousLoopSafetyPolicySummary = z.infer<
+  typeof RuntimeAutonomousLoopSafetyPolicySummarySchema
+>;
+
+export const RuntimeAutonomousLoopStatusSchema = z
+  .object({
+    status: z.enum(["running", "stopped"]),
+    intervalMs: z.number().int().positive().nullable(),
+    lastWakeTickAt: z.string().nullable(),
+    lastCheckpointResult: z.enum(["success", "error", "never"]),
+    safetyPolicySummary: RuntimeAutonomousLoopSafetyPolicySummarySchema,
+    ownerClientKind: NonEmptyStringSchema.nullable(),
+  })
+  .strict();
+export type RuntimeAutonomousLoopStatus = z.infer<typeof RuntimeAutonomousLoopStatusSchema>;
+
+function createDefaultRuntimeAutonomousLoopStatus(): RuntimeAutonomousLoopStatus {
+  return {
+    status: "stopped",
+    intervalMs: null,
+    lastWakeTickAt: null,
+    lastCheckpointResult: "never",
+    safetyPolicySummary: {},
+    ownerClientKind: null,
+  };
+}
+
+export const RuntimeStatusSchema = z
+  .object({
+    nodeId: NodeIdSchema,
+    runtimeId: RuntimeIdSchema,
+    port: z.number().int().min(1).max(65535),
+    attachedClients: z.number().int().nonnegative().optional(),
+    autonomousLoop: RuntimeAutonomousLoopStatusSchema.optional().default(
+      createDefaultRuntimeAutonomousLoopStatus(),
+    ),
+  })
+  .strict();
+export type RuntimeStatus = z.infer<typeof RuntimeStatusSchema>;
+
+export const RuntimeAutonomousLoopCommandSchema = z
+  .object({
+    intervalMs: z.number().int().positive().optional(),
+    safetyPolicy: RuntimeAutonomousLoopSafetyPolicySummarySchema.optional(),
+  })
+  .strict();
+export type RuntimeAutonomousLoopCommand = z.infer<typeof RuntimeAutonomousLoopCommandSchema>;
+
+export const PendingPairRequestViewSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    nodeId: NodeIdSchema,
+    displayNameSnapshot: NonEmptyStringSchema.optional(),
+    principalFingerprint: PrincipalFingerprintSchema,
+  })
+  .strict();
+export type PendingPairRequestView = z.infer<typeof PendingPairRequestViewSchema>;
+
+export const PendingInviteViewSchema = z
+  .object({
+    inviteId: NonEmptyStringSchema,
+    inviteLabel: NonEmptyStringSchema.optional(),
+    createdAt: NonEmptyStringSchema,
+    expiresAt: NonEmptyStringSchema.nullable().optional(),
+  })
+  .strict();
+export type PendingInviteView = z.infer<typeof PendingInviteViewSchema>;
+
+export const PairRequestDecisionSchema = z
+  .object({
+    requestId: NonEmptyStringSchema,
+    accepted: z.boolean(),
+  })
+  .strict();
+export type PairRequestDecision = z.infer<typeof PairRequestDecisionSchema>;
+
+export const PairRequestResponseSchema = z
+  .object({
+    accepted: z.boolean().optional(),
+    inviteToken: z.string().optional(),
+    error: z.string().optional(),
+  })
+  .strict();
+export type PairRequestResponse = z.infer<typeof PairRequestResponseSchema>;
+
+export const CreateInviteRequestSchema = z
+  .object({
+    inviteLabel: NonEmptyStringSchema.optional(),
+    durationMs: z.number().int().min(0).optional(),
+  })
+  .strict();
+export type CreateInviteRequest = z.infer<typeof CreateInviteRequestSchema>;
+
+export const CreateInviteResponseSchema = z
+  .object({
+    inviteToken: NonEmptyStringSchema,
+    pendingInvite: PendingInviteViewSchema,
+  })
+  .strict();
+export type CreateInviteResponse = z.infer<typeof CreateInviteResponseSchema>;
+
+export const InvitePeerRequestSchema = z
+  .object({
+    nodeId: NodeIdSchema,
+    displayName: NonEmptyStringSchema,
+    principalFingerprint: PrincipalFingerprintSchema.optional(),
+    controlEndpoint: ControlEndpointAdvertisementSchema,
+    transportEndpoint: TransportEndpointAdvertisementSchema.optional(),
+    transport: z.enum(["lan", "wan"]).optional(),
+  })
+  .strict();
+export type InvitePeerRequest = z.infer<typeof InvitePeerRequestSchema>;
+
+export const PairingProofStateSchema = z.enum(["pending_verification"]);
+export type PairingProofState = z.infer<typeof PairingProofStateSchema>;
+
+export const InvitePeerResultSchema = z.discriminatedUnion("mode", [
+  z
+    .object({
+      nodeId: NodeIdSchema,
+      displayNameSnapshot: NonEmptyStringSchema.optional(),
+      mode: z.literal("lan_direct"),
+      pairingProofState: z.literal("pending_verification"),
+    })
+    .strict(),
+  z
+    .object({
+      nodeId: NodeIdSchema,
+      displayNameSnapshot: NonEmptyStringSchema.optional(),
+      mode: z.literal("wan_pair"),
+      pairingProofState: z.literal("pending_verification"),
+    })
+    .strict(),
+]);
+export type InvitePeerResult = z.infer<typeof InvitePeerResultSchema>;
+
+export const AcceptInviteResponseSchema = z
+  .object({
+    success: z.boolean(),
+    nodeId: NodeIdSchema,
+    displayNameSnapshot: NonEmptyStringSchema.optional(),
+  })
+  .strict();
+export type AcceptInviteResponse = z.infer<typeof AcceptInviteResponseSchema>;
+
+export const AcceptInviteTokenRequestSchema = z
+  .object({
+    inviteToken: NonEmptyStringSchema,
+  })
+  .strict();
+export type AcceptInviteTokenRequest = z.infer<typeof AcceptInviteTokenRequestSchema>;
+
+export const AcceptInviteTokenResponseSchema = AcceptInviteResponseSchema;
+export type AcceptInviteTokenResponse = z.infer<typeof AcceptInviteTokenResponseSchema>;
+
+export const CancelInviteRequestSchema = z
+  .object({
+    inviteId: NonEmptyStringSchema,
+  })
+  .strict();
+export type CancelInviteRequest = z.infer<typeof CancelInviteRequestSchema>;
+
+export const CancelInviteResponseSchema = z
+  .object({
+    cancelled: z.boolean(),
+    inviteId: NonEmptyStringSchema,
+  })
+  .strict();
+export type CancelInviteResponse = z.infer<typeof CancelInviteResponseSchema>;
+
+export const DirectPairRequestSchema = z
+  .object({
+    peerNodeId: NodeIdSchema,
+    principalFingerprint: PrincipalFingerprintSchema,
+    peerDisplayName: NonEmptyStringSchema.optional(),
+    peerWgPubkey: PeerTransportIdSchema,
+    peerSigningPubkey: NonEmptyStringSchema,
+    transportEndpoint: TransportEndpointAdvertisementSchema,
+    controlEndpoint: ControlEndpointAdvertisementSchema,
+    psk: NonEmptyStringSchema,
+  })
+  .strict();
+export type DirectPairRequest = z.infer<typeof DirectPairRequestSchema>;
+export const DirectPairRequestJsonSchema = toFastifyBodyJsonSchema(DirectPairRequestSchema);
+
+export const DirectPairResponseSchema = z
+  .object({
+    received: z.literal(true),
+    pairingProofState: z.literal("pending_verification"),
+  })
+  .strict();
+export type DirectPairResponse = z.infer<typeof DirectPairResponseSchema>;
+
+export const RevokePeerRequestSchema = z
+  .object({
+    nodeId: NodeIdSchema,
+    envelope: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict();
+export type RevokePeerRequest = z.infer<typeof RevokePeerRequestSchema>;
+
+export const RevokePeerResponseSchema = z
+  .object({
+    revoked: z.boolean(),
+    nodeId: NodeIdSchema,
+    displayNameSnapshot: NonEmptyStringSchema.optional(),
+  })
+  .strict();
+export type RevokePeerResponse = z.infer<typeof RevokePeerResponseSchema>;
+
+export const RepairPeerRequestSchema = z
+  .object({
+    nodeId: NodeIdSchema,
+    endpointHost: NonEmptyStringSchema,
+    endpointPort: z.number().int().min(1).max(65535),
+    endpointRevision: EndpointRevisionSchema,
+  })
+  .strict();
+export type RepairPeerRequest = z.infer<typeof RepairPeerRequestSchema>;
+
+export const RepairPeerResponseSchema = z
+  .object({
+    repaired: z.boolean(),
+    nodeId: NodeIdSchema,
+    endpointHost: NonEmptyStringSchema,
+    endpointPort: z.number().int().min(1).max(65535),
+    endpointRevision: EndpointRevisionSchema,
+  })
+  .strict();
+export type RepairPeerResponse = z.infer<typeof RepairPeerResponseSchema>;
+
+export const LocalControlClientKindSchema = z.enum(["tui", "daemon-launcher", "pipe", "local-api"]);
+export type LocalControlClientKind = z.infer<typeof LocalControlClientKindSchema>;
+
+export const AttachedClientViewSchema = z
+  .object({
+    clientId: ClientIdSchema,
+    clientKind: LocalControlClientKindSchema,
+    displayLabel: NonEmptyStringSchema,
+    self: z.boolean(),
+    attachedAt: NonEmptyStringSchema,
+    lastSeenAt: NonEmptyStringSchema,
+  })
+  .strict();
+export type AttachedClientView = z.infer<typeof AttachedClientViewSchema>;
+
+export const AttachedClientLeaseGrantSchema = z
+  .object({
+    clientId: ClientIdSchema,
+    clientAuthToken: NonEmptyStringSchema,
+  })
+  .strict();
+export type AttachedClientLeaseGrant = z.infer<typeof AttachedClientLeaseGrantSchema>;
+
+export const AttachedClientAuthSchema = AttachedClientLeaseGrantSchema;
+export type AttachedClientAuth = z.infer<typeof AttachedClientAuthSchema>;
+
+export const LocalControlSocketAttachClientRequestSchema = z
+  .object({
+    clientKind: LocalControlClientKindSchema,
+    lease: z.boolean().optional(),
+  })
+  .strict();
+export type LocalControlSocketAttachClientRequest = z.infer<
+  typeof LocalControlSocketAttachClientRequestSchema
+>;
+
+export const LocalControlSocketAttachClientResponseSchema = AttachedClientLeaseGrantSchema;
+export type LocalControlSocketAttachClientResponse = z.infer<
+  typeof LocalControlSocketAttachClientResponseSchema
+>;
+
+export const LocalControlSocketDetachClientRequestSchema = z
+  .object({
+    clientId: ClientIdSchema,
+  })
+  .strict();
+export type LocalControlSocketDetachClientRequest = z.infer<
+  typeof LocalControlSocketDetachClientRequestSchema
+>;
+
+export const LocalControlSocketDetachClientResponseSchema = z
+  .object({
+    detached: z.boolean(),
+  })
+  .strict();
+export type LocalControlSocketDetachClientResponse = z.infer<
+  typeof LocalControlSocketDetachClientResponseSchema
+>;
+
+export const LocalControlSocketMethodSchema = z.enum([
+  "submitRun",
+  "resumeRun",
+  "streamRun",
+  "subscribeRuntimeEvents",
+  "sendBestEffort",
+  "sendDurable",
+  "listInbox",
+  "listDirectClientInbox",
+  "listPeers",
+  "listNearbyPeers",
+  "listAttachedClients",
+  "subscribeDirectClientInbox",
+  "getRuntimeStatus",
+  "startAutonomousLoop",
+  "stopAutonomousLoop",
+  "getRuntimeBootstrap",
+  "listPendingPairRequests",
+  "respondToPairRequest",
+  "createInvite",
+  "listPendingInvites",
+  "acceptInviteToken",
+  "cancelInvite",
+  "invitePeer",
+  "acceptInvite",
+  "directPair",
+  "revokePeer",
+  "repairPeer",
+  "attachClient",
+  "detachClient",
+  "watchInbox",
+]);
+export type LocalControlSocketMethod = z.infer<typeof LocalControlSocketMethodSchema>;
+
+const AttachedClientAuthRequiredSocketMethods = new Set<LocalControlSocketMethod>([
+  "listAttachedClients",
+  "listDirectClientInbox",
+  "subscribeDirectClientInbox",
+]);
+
+export const LocalControlSocketRequestSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    method: LocalControlSocketMethodSchema,
+    payload: z.unknown().optional(),
+    auth: AttachedClientAuthSchema.optional(),
+  })
+  .strict()
+  .superRefine((request, ctx) => {
+    if (AttachedClientAuthRequiredSocketMethods.has(request.method) && request.auth === undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `Local control socket method ${request.method} requires attached-client auth`,
+        path: ["auth"],
+      });
+    }
+  });
+export type LocalControlSocketRequest = z.infer<typeof LocalControlSocketRequestSchema>;
+
+export const LocalControlSocketSuccessResponseSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    ok: z.literal(true),
+    payload: z.unknown().optional(),
+  })
+  .strict();
+export type LocalControlSocketSuccessResponse = z.infer<
+  typeof LocalControlSocketSuccessResponseSchema
+>;
+
+export const LocalControlSocketErrorResponseSchema = z
+  .object({
+    id: NonEmptyStringSchema,
+    ok: z.literal(false),
+    error: NonEmptyStringSchema,
+    reason: z.string().optional(),
+    diagnostic: RuntimeErrorDiagnosticSchema.optional(),
+  })
+  .strict();
+export type LocalControlSocketErrorResponse = z.infer<typeof LocalControlSocketErrorResponseSchema>;
+
+export const LocalControlSocketResponseSchema = z.discriminatedUnion("ok", [
+  LocalControlSocketSuccessResponseSchema,
+  LocalControlSocketErrorResponseSchema,
+]);
+export type LocalControlSocketResponse = z.infer<typeof LocalControlSocketResponseSchema>;