brainclaw 1.5.4 → 1.6.0

package/dist/core/loops/types.js

@@ -7,8 +7,13 @@ export const REVIEW_MODES = ['asymmetric', 'symmetric'];
  * Slot lifecycle states. `done` / `failed` / `cancelled` are terminal and
  * mirror the `complete_turn` outcome so a caller reading the thread can
  * observe the per-slot outcome without replaying the event journal.
+ *
+ * pln#508 step 1 — `waiting_input` added to support the bootstrap loop's
+ * operator-question primitive. A slot in `waiting_input` is non-terminal:
+ * the engine resumes it back to `working` once its open_question is
+ * answered (see request_input/provide_input intents, pln#508 step 2).
  */
-export const SLOT_STATUSES = ['open', 'assigned', 'working', 'done', 'failed', 'cancelled'];
+export const SLOT_STATUSES = ['open', 'assigned', 'working', 'waiting_input', 'done', 'failed', 'cancelled'];
 export const TERMINAL_SLOT_STATUSES = ['done', 'failed', 'cancelled'];
 export const LOOP_REF_KINDS = ['plan', 'sequence', 'claim', 'handoff', 'candidate', 'message'];
 export const LoopRefSchema = z.object({
@@ -103,6 +108,27 @@ export const LoopIterationSchema = z.object({
 export const LoopProtocolConfigSchema = z.object({
     review_mode: z.enum(REVIEW_MODES).optional(),
     iteration: LoopIterationSchema.optional(),
+    /**
+     * pln#508 step 1 — protocol preset selector. When set (e.g. `'bootstrap'`),
+     * the coordinate facade routes preset-specific behaviors (close hook,
+     * phase config, dispatch eligibility) keyed off this value. Loops without
+     * a preset fall back to kind-default behavior.
+     */
+    preset: z.string().min(1).optional(),
+    /**
+     * pln#508 step 1 — cap on operator_question artifacts per loop. Enforced
+     * at request_input intent time (pln#508 step 2). Bootstrap preset sets
+     * this to 3 to prevent the "agent defers everything to the human" failure
+     * mode documented in feedback_agent_autonomy_gap.md.
+     */
+    max_operator_questions: z.number().int().positive().optional(),
+    /**
+     * pln#508 step 1 — ISO-8601 duration string (e.g. 'P7D') capping how long
+     * a loop may stay in status='paused' before the timeout machinery fires.
+     * Used by request_input artifacts with on_timeout policy. Bootstrap
+     * preset defaults to 'P7D'.
+     */
+    max_pause_duration: z.string().min(1).optional(),
 });
 export const LoopSlotSchema = z.object({
     slot_id: z.string().regex(/^lsl_[0-9a-z]+$/),
@@ -114,6 +140,189 @@ export const LoopSlotSchema = z.object({
     phase: z.string().optional(),
     status: z.enum(SLOT_STATUSES),
 });
+// ───────────────────────────────────────────────────────────────────────
+// pln#508 step 1 — bootstrap loop foundation: operator-interaction schemas
+// ───────────────────────────────────────────────────────────────────────
+//
+// These body schemas validate the JSON payload encoded in LoopArtifact.body
+// for the artifact types introduced by the bootstrap loop preset and
+// generally reusable for any human-in-the-loop primitive. Step 2's
+// request_input / provide_input handlers parse and validate via
+// `KNOWN_ARTIFACT_BODY_SCHEMAS[type]`.
+/** Where the operator pause applies: just the asking slot, or the whole loop. */
+export const PAUSE_SCOPES = ['slot', 'loop'];
+/** What the engine should do when an operator_question times out (Phase 0 spec §6). */
+export const ON_TIMEOUT_POLICIES = ['use_default', 'cancel_loop', 'continue_incomplete'];
+/** How an operator_answer arrived (Phase 0 spec §2). */
+export const RESOLVED_VIA = ['answer', 'choose', 'skip', 'timeout_default'];
+/** Reasons a loop may be paused. Maintained alongside LoopThread.pause_reason. */
+export const PAUSE_REASONS = ['awaiting_operator', 'awaiting_file_apply'];
+export const OperatorQuestionOptionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    tradeoff: z.string().optional(),
+});
+/**
+ * Operator question artifact body. The Champion records the question the
+ * operator must answer, with `evidence` (anti-autonomy-gap: the slot must
+ * show it tried), an optional `suggested_default` (used by skip / timeout
+ * resolution), and an optional `options` set (2..4) that enables structured
+ * `--choose` replies via the CLI.
+ */
+export const OperatorQuestionBodySchema = z
+    .object({
+    question_id: z.string().regex(/^qst_[0-9a-z]+$/),
+    question_text: z.string().min(1).max(500),
+    evidence: z.array(z.string().min(1)).min(1),
+    suggested_default: z.string().optional(),
+    options: z.array(OperatorQuestionOptionSchema).min(2).max(4).optional(),
+    pause_scope: z.enum(PAUSE_SCOPES),
+    on_timeout: z.enum(ON_TIMEOUT_POLICIES),
+    timeout_at: z.string().datetime().optional(),
+    /**
+     * pln#508 step 2 — slot that asked the question. Set by the
+     * `request_input` handler from its `slot_id` parameter so the
+     * `provide_input` handler can find the right slot to resume when
+     * `pause_scope='slot'`. Optional for forward compatibility with
+     * questions created from non-slot contexts (e.g. timeout-synthesized
+     * answers don't need it; pause_scope='loop' doesn't need it either).
+     */
+    by_slot_id: z.string().min(1).optional(),
+})
+    .superRefine((q, ctx) => {
+    if (q.options && q.suggested_default !== undefined) {
+        const optionIds = new Set(q.options.map((o) => o.id));
+        if (!optionIds.has(q.suggested_default)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `OperatorQuestion.suggested_default "${q.suggested_default}" must match an options[].id when options is present`,
+                path: ['suggested_default'],
+            });
+        }
+    }
+    if (q.on_timeout === 'use_default' && q.suggested_default === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'OperatorQuestion.on_timeout=use_default requires suggested_default to be set',
+            path: ['on_timeout'],
+        });
+    }
+});
+/**
+ * Operator answer artifact body. `replies_to` correlates to a question_id
+ * tracked in `LoopThread.open_questions`. `by` distinguishes human-provided
+ * answers from system-synthesized ones (timeout default fallback); synthetic
+ * answers MUST be flagged so audit can identify them.
+ */
+export const OperatorAnswerBodySchema = z
+    .object({
+    replies_to: z.string().regex(/^qst_[0-9a-z]+$/),
+    resolved_via: z.enum(RESOLVED_VIA),
+    answer_text: z.string().optional(),
+    chosen_option_id: z.string().optional(),
+    by: z.enum(['operator', 'system']),
+    synthetic: z.boolean().optional(),
+})
+    .superRefine((a, ctx) => {
+    if (a.by === 'system' && a.resolved_via !== 'timeout_default') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'OperatorAnswer.by="system" requires resolved_via="timeout_default" (synthetic answers can only be timeout-induced)',
+            path: ['resolved_via'],
+        });
+    }
+    if (a.resolved_via === 'timeout_default' && a.by !== 'system') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'OperatorAnswer.resolved_via="timeout_default" requires by="system"',
+            path: ['by'],
+        });
+    }
+    if (a.by === 'system' && a.synthetic !== true) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'OperatorAnswer.by="system" must have synthetic=true for audit clarity',
+            path: ['synthetic'],
+        });
+    }
+    const hasText = a.answer_text !== undefined;
+    const hasChosen = a.chosen_option_id !== undefined;
+    if (hasText && hasChosen) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'OperatorAnswer must have exactly one of {answer_text, chosen_option_id}, not both',
+            path: ['answer_text'],
+        });
+    }
+    if (!hasText && !hasChosen) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'OperatorAnswer must have exactly one of {answer_text, chosen_option_id}',
+            path: ['answer_text'],
+        });
+    }
+});
+/**
+ * Ref-based artifact body — used by project_md_draft, project_md_final,
+ * signals_report, file_diff. The artifact's actual content lives at
+ * `.brainclaw/coordination/loops/<loop_id>/artifacts/<ref>`. The body
+ * JSON itself carries only metadata: path, size, content hash. This sidesteps
+ * the 4 KiB LOOP_ARTIFACT_BODY_MAX_BYTES limit empirically hit during the
+ * pln#508 design session (PROJECT.md + AGENTS.md = 6,714 bytes; unified
+ * diffs are bigger).
+ */
+export const RefBasedArtifactBodySchema = z.object({
+    ref: z.string().min(1),
+    byte_count: z.number().int().nonnegative(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/),
+});
+/**
+ * Set of artifact `type` strings whose `body` MUST be a JSON-encoded
+ * RefBasedArtifactBody. Validation lives in LoopArtifactSchema's
+ * superRefine below — older artifact types (proposal, critique, plan_draft,
+ * etc.) keep freeform-string body semantics for backward compatibility.
+ */
+export const REF_BASED_ARTIFACT_TYPES = new Set([
+    'project_md_draft',
+    'project_md_final',
+    'signals_report',
+    'file_diff',
+]);
+/**
+ * Lookup table mapping known artifact types to their body Zod schemas.
+ * Step 2 handlers (request_input/provide_input) parse `artifact.body` as
+ * JSON and call `safeParse` on `KNOWN_ARTIFACT_BODY_SCHEMAS[type]`.
+ *
+ * Body shapes fall into two categories:
+ * - RefBasedArtifactBodySchema: `body` is JSON metadata for a file written
+ *   under `.brainclaw/loops/threads/<loop_id>/artifacts/<ref>`.
+ * - Inline body schemas: `body` is the complete small JSON payload.
+ *
+ * Schema definitions live above in this file. Keep this table explicit so
+ * attach-call errors can name the expected shape for each known type.
+ *
+ * Types not listed keep the legacy freeform-body behavior — no body schema
+ * is enforced. This preserves backward compatibility with proposal / critique
+ * / revision / plan_draft / change_summary artifacts produced before pln#508.
+ */
+export const KNOWN_ARTIFACT_BODY_SCHEMAS = {
+    // inline JSON body: body = JSON.stringify({ ...fields per OperatorQuestionBodySchema })
+    operator_question: OperatorQuestionBodySchema,
+    // inline JSON body: body = JSON.stringify({ ...fields per OperatorAnswerBodySchema })
+    operator_answer: OperatorAnswerBodySchema,
+    // ref-based: body = JSON.stringify({ ref, byte_count, sha256 })
+    // Ref file lives at .brainclaw/loops/threads/<loop_id>/artifacts/<ref>
+    project_md_draft: RefBasedArtifactBodySchema,
+    // ref-based: body = JSON.stringify({ ref, byte_count, sha256 })
+    // Ref file lives at .brainclaw/loops/threads/<loop_id>/artifacts/<ref>
+    project_md_final: RefBasedArtifactBodySchema,
+    // ref-based: body = JSON.stringify({ ref, byte_count, sha256 })
+    // Ref file lives at .brainclaw/loops/threads/<loop_id>/artifacts/<ref>
+    signals_report: RefBasedArtifactBodySchema,
+    // ref-based: body = JSON.stringify({ ref, byte_count, sha256 })
+    // Ref file lives at .brainclaw/loops/threads/<loop_id>/artifacts/<ref>
+    file_diff: RefBasedArtifactBodySchema,
+};
 export const LoopArtifactSchema = z
     .object({
     artifact_id: z.string().min(1),
@@ -160,11 +369,48 @@ export const LoopArtifactSchema = z
             });
         }
     }
+    // pln#508 step 1 — validate the body of known-typed artifacts against
+    // their schema. For ref-based types (project_md_*, signals_report,
+    // file_diff) this enforces metadata-only bodies (ref + sha256 + byte_count)
+    // and rejects raw markdown/diff content inline. For operator_question /
+    // operator_answer it validates the structured fields used by the
+    // request_input/provide_input intents (step 2). Older artifact types
+    // (proposal, critique, revision, change_summary, plan_draft, ...) are
+    // not in KNOWN_ARTIFACT_BODY_SCHEMAS and keep freeform body semantics.
+    if (artifact.body !== undefined && artifact.type in KNOWN_ARTIFACT_BODY_SCHEMAS) {
+        const schema = KNOWN_ARTIFACT_BODY_SCHEMAS[artifact.type];
+        let parsed;
+        try {
+            parsed = JSON.parse(artifact.body);
+        }
+        catch {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `LoopArtifact type="${artifact.type}" requires body to be a JSON-encoded payload; got non-JSON content`,
+                path: ['body'],
+            });
+            return;
+        }
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `LoopArtifact type="${artifact.type}" body failed schema validation: ` +
+                    result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; '),
+                path: ['body'],
+            });
+        }
+    }
 });
 export const AtomicStopConditionSchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('phase_reached'), phase: z.string().min(1) }),
     z.object({ kind: z.literal('reviewer_green') }),
     z.object({ kind: z.literal('max_iterations'), n: z.number().int().positive() }),
+    // pln#516 step 2 — minimum-iteration floor. Used by the bootstrap preset's
+    // clarify gate (composed inside `all`) to refuse exiting the phase before
+    // the champion has had at least one iteration tick to call requestInput.
+    // Symmetric to `max_iterations`: matches when `iteration_count >= n`.
+    z.object({ kind: z.literal('min_iterations'), n: z.number().int().positive() }),
     z.object({
         kind: z.literal('artifact_produced'),
         phase: z.string().min(1),
@@ -181,6 +427,10 @@ export const AtomicStopConditionSchema = z.discriminatedUnion('kind', [
         n: z.number().int().positive(),
         scope: z.enum(['phase', 'loop']),
     }),
+    // pln#511 step 1 — bootstrap preset's clarify phase advances when the
+    // operator has no pending questions. Composed with `max_iterations=1`
+    // under an `any` gate so the loop never blocks the operator forever.
+    z.object({ kind: z.literal('no_open_questions') }),
     z.object({ kind: z.literal('manual') }),
 ]);
 export const StopConditionSchema = z.lazy(() => z.union([
@@ -206,6 +456,34 @@ export const LoopThreadSchema = z
     artifacts: z.array(LoopArtifactSchema),
     linked: LoopLinksSchema.optional(),
     stop_condition: StopConditionSchema.optional(),
+    /**
+     * pln#508 step 1 — set of unresolved operator_question artifact ids.
+     * The engine maintains this on every request_input / provide_input
+     * intent (step 2). Default `[]` for backward compatibility with loops
+     * created before this schema field landed.
+     */
+    open_questions: z.array(z.string().regex(/^qst_[0-9a-z]+$/)).default([]),
+    /**
+     * pln#508 step 1 — why the loop is paused, when status='paused'. The
+     * two valid reasons cover the bootstrap loop's operator-question and
+     * file-overwrite-approval primitives. Old paused loops without this
+     * field continue to load; only newly-paused loops are required to set it.
+     */
+    pause_reason: z.enum(PAUSE_REASONS).optional(),
+    /**
+     * pln#508 step 1 — set when `pause_reason='awaiting_file_apply'`.
+     * Carries the source artifact (project_md_final), target file path,
+     * and the diff artifact the operator is approving. The file is only
+     * written once an operator_answer with resolved_via in
+     * {answer, choose} lands AND the answer indicates approval.
+     */
+    pending_file_apply: z
+        .object({
+        artifact_id: z.string().min(1),
+        target_path: z.string().min(1),
+        diff_artifact_id: z.string().min(1),
+    })
+        .optional(),
     created_at: z.string().datetime(),
     updated_at: z.string().datetime(),
     closed_at: z.string().datetime().optional(),
@@ -228,6 +506,27 @@ export const LoopThreadSchema = z
             path: ['current_phase'],
         });
     }
+    // pln#508 step 1 — pause_reason / pending_file_apply invariants.
+    // We intentionally do NOT enforce "status=paused requires pause_reason"
+    // because pre-existing paused loops on disk may lack it; that bidirectional
+    // invariant is enforced by the request_input handler in step 2 at write
+    // time, not by the load-time schema.
+    if (thread.pause_reason !== undefined && thread.status !== 'paused') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `LoopThread.pause_reason is set ("${thread.pause_reason}") but status is "${thread.status}" — pause_reason requires status="paused"`,
+            path: ['pause_reason'],
+        });
+    }
+    if (thread.pending_file_apply !== undefined && thread.pause_reason !== 'awaiting_file_apply') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `LoopThread.pending_file_apply is set but pause_reason is ` +
+                `${thread.pause_reason === undefined ? 'undefined' : `"${thread.pause_reason}"`}` +
+                ' — pending_file_apply requires pause_reason="awaiting_file_apply"',
+            path: ['pending_file_apply'],
+        });
+    }
 });
 const LoopEventBaseShape = {
     event_id: z.string().min(1),
@@ -314,6 +613,52 @@ export const LoopEventSchema = z.discriminatedUnion('kind', [
         iteration: z.number().int().nonnegative(),
         max_iterations: z.number().int().positive(),
     }),
+    // pln#508 step 2 — bootstrap loop operator-interaction events.
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('input_requested'),
+        question_id: z.string().regex(/^qst_[0-9a-z]+$/),
+        pause_scope: z.enum(PAUSE_SCOPES),
+        by_slot_id: z.string().min(1),
+    }),
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('input_provided'),
+        question_id: z.string().regex(/^qst_[0-9a-z]+$/),
+        resolved_via: z.enum(RESOLVED_VIA),
+        /**
+         * Whose answer this is — `'operator'` for human-provided, `'system'`
+         * for engine-synthesized (timeout default). Named `answered_by` to
+         * avoid clashing with `LoopEventBaseShape.by` (event actor / source).
+         */
+        answered_by: z.enum(['operator', 'system']),
+        synthetic: z.boolean(),
+    }),
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('slot_status_changed'),
+        slot_id: z.string().min(1),
+        from_status: z.enum(SLOT_STATUSES),
+        to_status: z.enum(SLOT_STATUSES),
+    }),
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('pause_timeout'),
+        question_id: z.string().regex(/^qst_[0-9a-z]+$/),
+        action_taken: z.enum(ON_TIMEOUT_POLICIES),
+    }),
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('file_apply_requested'),
+        artifact_id: z.string().min(1),
+        target_path: z.string().min(1),
+    }),
+    z.object({
+        ...LoopEventBaseShape,
+        kind: z.literal('file_apply_resolved'),
+        artifact_id: z.string().min(1),
+        approved: z.boolean(),
+    }),
 ]);
 export const LoopConflictRecordSchema = z.object({
     conflict_id: z.string().min(1),