@ai-dev-orchestrator/schemas 0.1.1

package/dist/runner/runner-system.js

@@ -0,0 +1,268 @@
+import { z } from 'zod/v4';
+import { artifactRefSchema, artifactTypeSchema } from '../artifacts/artifact-system';
+import { findingSchema } from '../governance/review-resolution';
+import { runIdSchema } from '../shared/shared';
+import { outputFormatSchema, sessionTransportSchema, threeTierSeveritySchema, } from '../shared/string-enums';
+import { agentConfigSchema, modelAssignmentSchema, roleContractSchema, roleIdSchema, } from './role-system';
+// ---------------------------------------------------------------------------
+// Agent session types
+// ---------------------------------------------------------------------------
+export const agentSessionStateSchema = z.enum([
+    'running',
+    'awaiting_human',
+    'paused',
+    'reconnecting',
+    'completed',
+    'failed',
+    'aborted',
+    'orphaned',
+]);
+export const agentSessionRefSchema = z.object({
+    sessionId: z.string(),
+    runId: z.string(),
+    stateId: z.string(),
+    role: roleIdSchema,
+    transport: sessionTransportSchema,
+});
+export const permissionPayloadSchema = z
+    .object({
+    action: z.string(),
+    resource: z.string(),
+    detail: z.string().optional(),
+    riskLevel: threeTierSeveritySchema.optional(),
+    externalRequestId: z.string().optional(),
+    toolInput: z.string().optional(),
+    granted: z.boolean().optional(),
+    reason: z.string().optional(),
+    timedOut: z.boolean().optional(),
+    aborted: z.boolean().optional(),
+})
+    .catchall(z.unknown());
+export const clarificationPayloadSchema = z
+    .object({
+    question: z.string(),
+    context: z.string().optional(),
+    options: z.array(z.string()).readonly().optional(),
+    answer: z.string().optional(),
+})
+    .catchall(z.unknown());
+export const sessionPendingRequestSchema = z.discriminatedUnion('kind', [
+    z.object({
+        requestId: z.string(),
+        kind: z.literal('permission'),
+        createdAt: z.string(),
+        payload: permissionPayloadSchema,
+    }),
+    z.object({
+        requestId: z.string(),
+        kind: z.literal('clarification'),
+        createdAt: z.string(),
+        payload: clarificationPayloadSchema,
+    }),
+]);
+export const stdioReconnectMetaSchema = z.object({
+    type: z.literal('stdio'),
+    pid: z.number(),
+    socketPath: z.string().optional(),
+});
+export const remoteReconnectMetaSchema = z.object({
+    type: z.literal('remote'),
+    remoteSessionId: z.string(),
+    reconnectUrl: z.string(),
+    websocketUrl: z.string().optional(),
+    leaseExpiresAt: z.string().optional(),
+    heartbeatIntervalMs: z.number().optional(),
+    authHeader: z.string().optional(),
+});
+export const reconnectMetaSchema = z.discriminatedUnion('type', [
+    stdioReconnectMetaSchema,
+    remoteReconnectMetaSchema,
+]);
+export const agentSessionSnapshotSchema = z.object({
+    ref: agentSessionRefSchema,
+    state: agentSessionStateSchema,
+    pendingRequests: z.array(sessionPendingRequestSchema).readonly(),
+    lastProtocolTimestamp: z.string(),
+    reconnect: reconnectMetaSchema.optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    expiresAt: z.string().optional(),
+    workerId: z.string().optional(),
+    error: z.string().optional(),
+});
+export const agentSessionHandleSchema = z.object({
+    ref: agentSessionRefSchema,
+    state: agentSessionStateSchema,
+    pendingRequests: z.array(sessionPendingRequestSchema).readonly(),
+});
+export const sessionDispatchOutcomeSchema = z.enum([
+    'completed',
+    'awaiting_human',
+    'session_active',
+]);
+// ---------------------------------------------------------------------------
+// Main runner-system types
+// ---------------------------------------------------------------------------
+export const resolvedArtifactSchema = z.object({
+    ref: artifactRefSchema,
+    content: z.string(),
+});
+export const workerOutputFormatSchema = outputFormatSchema;
+export const workerConstraintsSchema = z.object({
+    maxOutputTokens: z.number(),
+    timeout: z.number(),
+    requiredOutputType: artifactTypeSchema,
+    outputSchema: z.record(z.string(), z.unknown()).optional(),
+    outputFormat: workerOutputFormatSchema.optional(),
+});
+export const dispatchOverridesSchema = z.object({
+    model: modelAssignmentSchema.optional(),
+    timeout: z.number().optional(),
+    maxRetries: z.number().optional(),
+});
+export const dispatchRequestSchema = z.object({
+    runId: runIdSchema,
+    stateId: z.string(),
+    role: roleIdSchema,
+    inputArtifacts: z.array(artifactRefSchema).readonly(),
+    overrides: dispatchOverridesSchema.optional(),
+    humanFeedback: z.string().optional(),
+    userPrompt: z.string().optional(),
+    previousReviewContent: z.string().optional(),
+    structuredFindings: z.array(findingSchema).readonly().optional(),
+    iterationCount: z.number().optional(),
+    variableOverrides: z.record(z.string(), z.string()).optional(),
+});
+export const workerErrorTypeSchema = z.enum([
+    'agent_error',
+    'timeout',
+    'invalid_output',
+    'schema_violation',
+    'ownership_violation',
+    'cancelled',
+]);
+export const workerErrorSchema = z.object({
+    type: workerErrorTypeSchema,
+    message: z.string(),
+    retryable: z.boolean(),
+});
+export const workerMetricsSchema = z.object({
+    startedAt: z.string(),
+    completedAt: z.string(),
+    durationMs: z.number(),
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+    retryCount: z.number(),
+    modelUsed: z.string(),
+});
+export const dispatchStatusSchema = z.enum(['success', 'failure', 'timeout', 'cancelled']);
+export const dispatchResultSchema = z.object({
+    workerId: z.string(),
+    role: roleIdSchema,
+    status: dispatchStatusSchema,
+    outputArtifacts: z.array(artifactRefSchema).readonly(),
+    error: workerErrorSchema.optional(),
+    metrics: workerMetricsSchema,
+    sessionOutcome: sessionDispatchOutcomeSchema.optional(),
+    sessionRef: agentSessionRefSchema.optional(),
+    pendingRequest: sessionPendingRequestSchema.optional(),
+});
+export const workerStatusSchema = z.object({
+    workerId: z.string(),
+    role: roleIdSchema,
+    state: z.enum(['pending', 'running', 'completed', 'failed', 'timed-out']),
+    startedAt: z.string(),
+    elapsedMs: z.number(),
+});
+export const workerContextSchema = z.object({
+    role: roleContractSchema,
+    prompt: z.string(),
+    inputArtifacts: z.array(resolvedArtifactSchema).readonly(),
+    modelAssignment: modelAssignmentSchema,
+    constraints: workerConstraintsSchema,
+});
+export const workerInvocationRecordSchema = z.object({
+    timestamp: z.string(),
+    runId: runIdSchema,
+    workerId: z.string(),
+    stateId: z.string(),
+    role: roleIdSchema,
+    model: z.string(),
+    inputArtifacts: z.array(artifactRefSchema).readonly(),
+    outputArtifacts: z.array(artifactRefSchema).readonly(),
+    status: dispatchStatusSchema,
+    metrics: workerMetricsSchema,
+    error: workerErrorSchema.optional(),
+});
+export const retryPolicySchema = z.object({
+    maxRetries: z.number(),
+    initialDelayMs: z.number(),
+    maxDelayMs: z.number(),
+    backoffMultiplier: z.number(),
+});
+// ---------------------------------------------------------------------------
+// Agent types
+// ---------------------------------------------------------------------------
+export const agentConstraintsSchema = z.object({
+    timeout: z.number(),
+    requiredOutputType: artifactTypeSchema,
+    outputSchema: z.record(z.string(), z.unknown()).optional(),
+    outputFormat: workerOutputFormatSchema.optional(),
+});
+export const agentTaskSchema = z.object({
+    taskId: z.string(),
+    runId: z.string(),
+    stateId: z.string(),
+    role: roleIdSchema,
+    description: z.string(),
+    inputArtifacts: z.array(resolvedArtifactSchema).readonly(),
+    repoRoot: z.string(),
+    runDir: z.string(),
+    outputArtifactPath: z.string(),
+    constraints: agentConstraintsSchema,
+    instructions: z.string().optional(),
+    rolePrompt: z.string().optional(),
+    agentConfig: agentConfigSchema.optional(),
+    modelHint: z.string().optional(),
+    humanFeedback: z.string().optional(),
+    userPrompt: z.string().optional(),
+    previousFindings: z.string().optional(),
+    iterationCount: z.number().optional(),
+});
+export const agentTokenUsageSchema = z.object({
+    inputTokens: z.number(),
+    outputTokens: z.number(),
+});
+export const agentResultSchema = z.object({
+    taskId: z.string(),
+    status: z.enum(['success', 'failure', 'timeout']),
+    artifactContent: z.string().optional(),
+    error: z.string().optional(),
+    durationMs: z.number(),
+    tokenUsage: agentTokenUsageSchema.optional(),
+});
+// ---------------------------------------------------------------------------
+// Live response payload schemas (for human-in-the-loop responses)
+// ---------------------------------------------------------------------------
+export const livePermissionResponsePayloadSchema = z
+    .object({
+    granted: z.boolean().optional(),
+    reason: z.string().optional(),
+})
+    .loose();
+export const liveClarificationResponsePayloadSchema = z
+    .object({
+    answer: z.string().optional(),
+})
+    .loose();
+// ---------------------------------------------------------------------------
+// HTTP agent runner response schemas
+// ---------------------------------------------------------------------------
+export const submitResponseSchema = z.object({ taskId: z.string() }).loose();
+export const pollResponseSchema = z
+    .object({
+    status: z.enum(['running', 'completed', 'failed']),
+    result: agentResultSchema.optional(),
+    error: z.string().optional(),
+})
+    .loose();

package/dist/runner/task-brief.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod/v4';
+export declare const successCriterionSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodString;
+    verifiable: z.ZodBoolean;
+}, z.core.$strip>;
+export type SuccessCriterion = z.infer<typeof successCriterionSchema>;
+export declare const taskBriefSchema: z.ZodObject<{
+    what: z.ZodString;
+    why: z.ZodString;
+    how: z.ZodOptional<z.ZodString>;
+    successCriteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        description: z.ZodString;
+        verifiable: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TaskBrief = z.infer<typeof taskBriefSchema>;

package/dist/runner/task-brief.js

@@ -0,0 +1,12 @@
+import { z } from 'zod/v4';
+export const successCriterionSchema = z.object({
+    id: z.string(),
+    description: z.string(),
+    verifiable: z.boolean(),
+});
+export const taskBriefSchema = z.object({
+    what: z.string(),
+    why: z.string(),
+    how: z.string().optional(),
+    successCriteria: z.array(successCriterionSchema).min(1),
+});

package/dist/shared/index.d.ts

@@ -0,0 +1,3 @@
+export * from './shared';
+export * from './string-enums';
+export * from './utils';

package/dist/shared/index.js

@@ -0,0 +1,3 @@
+export * from './shared';
+export * from './string-enums';
+export * from './utils';

package/dist/shared/shared.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod/v4';
+export declare const AI_CONFIG_DIR_NAME = ".ai";
+export declare const RUNS_DIR_NAME = "runs";
+export declare const ARTIFACTS_DIR_NAME = "artifacts";
+export declare const VIDEOS_DIR_NAME = "videos";
+export declare const TMP_DIR_NAME = "tmp";
+export declare const RUN_LOCK_FILENAME = "run.lock";
+export declare const STATE_FILENAME = "state.yaml";
+export declare const INVENTORY_FILENAME = "inventory.yaml";
+export declare const WORKFLOW_DEFINITION_FILENAME = "workflow-definition.json";
+export declare const MEDIA_FILE_EXTENSIONS: readonly [".webm", ".mp4", ".png", ".jpg", ".jpeg", ".gif"];
+export type MediaFileExtension = (typeof MEDIA_FILE_EXTENSIONS)[number];
+export declare const MEDIA_MIME_TYPES: Readonly<Record<string, string>>;
+export declare const runIdSchema: z.core.$ZodBranded<z.ZodString, "RunId", "out">;
+export type RunId = z.infer<typeof runIdSchema>;
+export declare const workerIdSchema: z.core.$ZodBranded<z.ZodString, "WorkerId", "out">;
+export type WorkerId = z.infer<typeof workerIdSchema>;
+/**
+ * Result type for expected failures in domain/application layers.
+ * Cannot be expressed as a Zod schema due to generics -- hand-written.
+ */
+export type Result<T, E extends Error = Error> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+export declare function ok<T>(value: T): Result<T, never>;
+export declare function err<E extends Error>(error: E): Result<never, E>;

package/dist/shared/shared.js

@@ -0,0 +1,27 @@
+import { z } from 'zod/v4';
+export const AI_CONFIG_DIR_NAME = '.ai';
+export const RUNS_DIR_NAME = 'runs';
+export const ARTIFACTS_DIR_NAME = 'artifacts';
+export const VIDEOS_DIR_NAME = 'videos';
+export const TMP_DIR_NAME = 'tmp';
+export const RUN_LOCK_FILENAME = 'run.lock';
+export const STATE_FILENAME = 'state.yaml';
+export const INVENTORY_FILENAME = 'inventory.yaml';
+export const WORKFLOW_DEFINITION_FILENAME = 'workflow-definition.json';
+export const MEDIA_FILE_EXTENSIONS = ['.webm', '.mp4', '.png', '.jpg', '.jpeg', '.gif'];
+export const MEDIA_MIME_TYPES = {
+    '.webm': 'video/webm',
+    '.mp4': 'video/mp4',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+};
+export const runIdSchema = z.string().brand('RunId');
+export const workerIdSchema = z.string().brand('WorkerId');
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}

package/dist/shared/string-enums.d.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod/v4';
+export declare const threeTierSeveritySchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    low: "low";
+}>;
+export type ThreeTierSeverity = z.infer<typeof threeTierSeveritySchema>;
+export declare const sessionTransportSchema: z.ZodEnum<{
+    stdio: "stdio";
+    remote: "remote";
+}>;
+export type SessionTransport = z.infer<typeof sessionTransportSchema>;
+export declare const liveRequestKindSchema: z.ZodEnum<{
+    permission: "permission";
+    clarification: "clarification";
+}>;
+export type LiveRequestKind = z.infer<typeof liveRequestKindSchema>;
+export declare const readinessVerdictSchema: z.ZodEnum<{
+    Ready: "Ready";
+    NotReady: "NotReady";
+}>;
+export type ReadinessVerdict = z.infer<typeof readinessVerdictSchema>;
+export declare const outputFormatSchema: z.ZodEnum<{
+    markdown_with_frontmatter: "markdown_with_frontmatter";
+    yaml: "yaml";
+    json: "json";
+    freeform: "freeform";
+}>;
+export type OutputFormat = z.infer<typeof outputFormatSchema>;
+export declare const agentStreamEventTypeSchema: z.ZodEnum<{
+    stdout: "stdout";
+    stderr: "stderr";
+    status: "status";
+    permission_request: "permission_request";
+    clarification_request: "clarification_request";
+}>;
+export type AgentStreamEventType = z.infer<typeof agentStreamEventTypeSchema>;
+export declare const roleTrustLevelSchema: z.ZodEnum<{
+    high: "high";
+    medium: "medium";
+    none: "none";
+}>;
+export type RoleTrustLevel = z.infer<typeof roleTrustLevelSchema>;
+export declare const permissionActionSchema: z.ZodEnum<{
+    file_read: "file_read";
+    file_write: "file_write";
+    file_delete: "file_delete";
+    shell_execute: "shell_execute";
+    network_request: "network_request";
+    git_operation: "git_operation";
+    custom: "custom";
+}>;
+export type PermissionAction = z.infer<typeof permissionActionSchema>;
+export declare const permissionDecisionActionSchema: z.ZodEnum<{
+    grant: "grant";
+    deny: "deny";
+    ask_human: "ask_human";
+}>;
+export type PermissionDecisionAction = z.infer<typeof permissionDecisionActionSchema>;

package/dist/shared/string-enums.js

@@ -0,0 +1,24 @@
+import { z } from 'zod/v4';
+export const threeTierSeveritySchema = z.enum(['high', 'medium', 'low']);
+export const sessionTransportSchema = z.enum(['stdio', 'remote']);
+export const liveRequestKindSchema = z.enum(['permission', 'clarification']);
+export const readinessVerdictSchema = z.enum(['Ready', 'NotReady']);
+export const outputFormatSchema = z.enum(['markdown_with_frontmatter', 'yaml', 'json', 'freeform']);
+export const agentStreamEventTypeSchema = z.enum([
+    'stdout',
+    'stderr',
+    'status',
+    'permission_request',
+    'clarification_request',
+]);
+export const roleTrustLevelSchema = z.enum(['high', 'medium', 'none']);
+export const permissionActionSchema = z.enum([
+    'file_read',
+    'file_write',
+    'file_delete',
+    'shell_execute',
+    'network_request',
+    'git_operation',
+    'custom',
+]);
+export const permissionDecisionActionSchema = z.enum(['grant', 'deny', 'ask_human']);

package/dist/shared/utils.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Minimal schema interface for consumers that don't import Zod directly.
+ * Any Zod schema satisfies this interface. The type parameter `T` carries
+ * the parsed output type so callers get type-safe results without importing Zod.
+ */
+export interface SchemaLike<T = unknown> {
+    safeParse(data: unknown): {
+        success: boolean;
+        data?: T;
+        error?: {
+            issues: unknown[];
+        };
+    };
+}
+/**
+ * Parse a JSON value with a Zod schema.
+ *
+ * Throws a `SchemaValidationError` when parsing fails instead of
+ * silently returning unvalidated data.
+ */
+export declare function safeParseResponse<T>(schema: SchemaLike<T>, data: unknown): T;
+export declare class SchemaValidationError extends Error {
+    readonly issues: unknown[];
+    constructor(issues: unknown[]);
+}

package/dist/shared/utils.js

@@ -0,0 +1,22 @@
+/**
+ * Parse a JSON value with a Zod schema.
+ *
+ * Throws a `SchemaValidationError` when parsing fails instead of
+ * silently returning unvalidated data.
+ */
+export function safeParseResponse(schema, data) {
+    const result = schema.safeParse(data);
+    if (result.success && result.data !== undefined) {
+        return result.data;
+    }
+    const issues = result.error?.issues ?? [];
+    throw new SchemaValidationError(issues);
+}
+export class SchemaValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Schema validation failed: ${JSON.stringify(issues)}`);
+        this.name = 'SchemaValidationError';
+        this.issues = issues;
+    }
+}