brainclaw 1.26.2 → 1.28.0

package/dist/core/harness-adapters/registry.js

@@ -0,0 +1,48 @@
+import { ClaudeHarnessAdapter } from './claude.js';
+import { CodexHarnessAdapter } from './codex.js';
+import { PromptOnlyHarnessAdapter } from './prompt-only.js';
+const promptOnly = new PromptOnlyHarnessAdapter();
+const nativeAdapters = [new CodexHarnessAdapter(), new ClaudeHarnessAdapter()];
+export function nativeHarnessEnabled(env = process.env) {
+    return env.BRAINCLAW_NATIVE_HARNESS === '1';
+}
+export function selectHarnessAdapter(agent, native = nativeHarnessEnabled()) {
+    if (!native)
+        return promptOnly;
+    return nativeAdapters.find((adapter) => adapter.matches(agent)) ?? promptOnly;
+}
+export function resolveHarnessBinding(agent, requestedModel, native, probeOptions) {
+    return selectHarnessAdapter(agent, native).resolve(agent, requestedModel, probeOptions);
+}
+export function prepareHarnessInvocation(input) {
+    const binding = input.binding ?? resolveHarnessBinding(input.capability_snapshot?.agent ?? '', input.capability_snapshot?.requested.model, input.native);
+    const adapter = selectHarnessAdapter(binding.agent, input.native ?? binding.adapter_id !== 'prompt-only');
+    if (adapter.id !== binding.adapter_id || adapter.version !== binding.adapter_version) {
+        throw new Error(`harness_binding_mismatch: frozen ${binding.adapter_id}@${binding.adapter_version}, selected ${adapter.id}@${adapter.version}`);
+    }
+    return adapter.prepare({ ...input, binding });
+}
+export function buildHarnessInvocation(agent, prompt, options = {}) {
+    let binding;
+    try {
+        binding = options.binding ?? resolveHarnessBinding(agent, options.model, options.native);
+    }
+    catch (error) {
+        if (error instanceof Error && / is unavailable for /.test(error.message))
+            return undefined;
+        throw error;
+    }
+    return prepareHarnessInvocation({
+        binding,
+        prompt,
+        mode: options.mode ?? 'worker',
+        platform: options.platform,
+        native: options.native,
+        contract: options.contract,
+        capability_snapshot: options.capability_snapshot,
+    });
+}
+export function listHarnessAdapters() {
+    return [promptOnly, ...nativeAdapters];
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/harness-adapters/result.js

@@ -0,0 +1,33 @@
+import { listHarnessAdapters } from './registry.js';
+export function parseHarnessOutcome(adapterId, observation, adapterVersion) {
+    const adapter = listHarnessAdapters().find((candidate) => candidate.id === adapterId);
+    if (!adapter)
+        throw new Error(`unknown harness adapter: ${adapterId}`);
+    if (adapterVersion && adapter.version !== adapterVersion) {
+        throw new Error(`harness adapter version mismatch: installed ${adapter.id}@${adapter.version}, frozen ${adapterId}@${adapterVersion}`);
+    }
+    return adapter.parseOutcome(observation);
+}
+/**
+ * Convert an untrusted harness claim to the existing LaneResult ingress shape.
+ * This is deliberately normalization only: reconcileTurn still validates
+ * attempt identity and reducers/evidence/gates remain the authority boundary.
+ */
+export function normalizeHarnessClaimToLaneResult(claim, identity) {
+    const status = claim.status === 'completed'
+        ? 'completed'
+        : claim.status === 'blocked' ? 'blocked' : 'failed';
+    return {
+        ...identity,
+        status,
+        summary: claim.summary,
+        body: claim.body,
+        artifact_type: claim.artifact_type,
+        review_verdict: claim.review_verdict,
+        review_summary: claim.review_verdict ? claim.summary : undefined,
+        notes: claim.diagnostics.length > 0
+            ? claim.diagnostics.map((item) => `${item.kind}:${item.code}: ${item.message}`).join('\n')
+            : undefined,
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/core/harness-adapters/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/ideation-loop-close.js

@@ -1,5 +1,5 @@
 import { getLoop } from './loops/store.js';
-import { complete_turn, advance, evaluatePhaseAdvanceGate } from './loops/verbs.js';
+import { complete_turn, completeTurnWithEvidence, advance, evaluatePhaseAdvanceGate } from './loops/verbs.js';
 import { withLoopLock } from './loops/lock.js';
 import { LOOP_ARTIFACT_BODY_MAX_BYTES } from './loops/types.js';
 /** ideate-loop:lop_xxx[:slot] → the loop id (dispatch sets `ideate-loop:${loopId}:${slotId}`). */
@@ -137,7 +137,30 @@ export function closeIdeationLoopFromLaneResult(assignment, lane, actor, cwd) {
                 // artifact stops satisfying the current gate by construction — no
                 // separate refusal path, and the content is preserved rather than lost.
                 const dispatchPhase = slot.phase ?? loop.current_phase;
-                complete_turn({ id: loopId, slot_id: slot.slot_id, actor, outcome: 'done', artifact: { phase: dispatchPhase, type: 'critique', body: capCritique(critique) } }, cwd);
+                completeTurnWithEvidence({
+                    id: loopId,
+                    slot_id: slot.slot_id,
+                    actor,
+                    outcome: 'done',
+                    artifact: { phase: dispatchPhase, type: 'critique', body: capCritique(critique) },
+                    // This adapter is the trusted bridge from a harvested, assignment-bound
+                    // LANE-RESULT to the slot that produced it. Without an explicit slot
+                    // context, a coordinator-driven harvest is sealed as coordinator
+                    // narration and the evidence gate correctly rejects it. Preserve the
+                    // actual producer identity while keeping legacy lanes (which have no
+                    // TurnReservation nonce) on the narrow complete_turn authority.
+                    evidence_context: {
+                        channel: 'complete_turn',
+                        producer_kind: 'slot',
+                        producer_id: slot.slot_id,
+                        agent_id: slot.agent_id,
+                        slot_id: slot.slot_id,
+                        slot_role: slot.role,
+                        assignment_id: slot.assignment_id ?? assignment.id,
+                        claim_id: slot.claim_id,
+                        turn_id: slot.current_turn_id,
+                    },
+                }, cwd);
                 const advanced = tryAdvance(true);
                 return reportedArtifactType && reportedArtifactType !== expectedArtifactType
                     ? { ...advanced, reason: `reconciled reported artifact type "${reportedArtifactType}" to expected "${expectedArtifactType}"; ${advanced.reason}` }

package/dist/core/instruction-templates.js

@@ -257,8 +257,9 @@ function renderUserWorkflow() {
         '',
         'Entities: `plan` (intended outcome) · `step` (unit inside a plan) · `sequence` (optional parallel lanes) · `claim` (advisory scope reservation) · `handoff` (stage snapshot) · `candidate` (proposed memory awaiting review) · `decision`/`constraint`/`trap`/`runtime_note` (context captured along the way).',
         '',
-        'Review & Fix Loop: start with `bclaw_coordinate(intent=review, open_loop=true, review_mode=symmetric|asymmetric, targetAgents=[reviewer])` — opens the loop AND dispatches the first turn. Drive your turns with `bclaw_loop(intent=turn|complete_turn|advance|close)`. Parallelize a sequence\'s lanes with `bclaw_dispatch(intent=execute)`.',
-        'Ideation / Debug / Research loops — *planned* (`docs/product/agent-first-model.md` §3).',
+        'Loop Engine: five shipped protocols share one lifecycle — `review` validates a change, `ideation` pressure-tests a proposal, `implementation` drives a bound plan to green, `research` converges an open question, and `debug` drives a reproducible failure back to green.',
+        'Entry points: start review with `bclaw_coordinate(intent=review, open_loop=true, review_mode=symmetric|asymmetric, targetAgents=[reviewer])`; start ideation with `bclaw_coordinate(intent=ideate, targetAgents=[critic])`. For implementation, research, or debug, direct `bclaw_loop(intent=open, kind=<kind>, allow_orphan=true)` is supported only when the caller will explicitly drive or dispatch the loop.',
+        'Drive turns with `bclaw_loop(intent=turn|complete_turn|advance|close)` and follow each response\'s `next_actions`; on a worker phase, trusted `bclaw_loop(intent=turn, dispatch=true)` runs the common AttemptAuthority dispatch path. Parallelize a sequence\'s independent lanes with `bclaw_dispatch(intent=execute)`. Protocol details: `docs/concepts/loop-engine.md` and `docs/loops/`.',
     ].join('\n');
 }
 /**

package/dist/core/loop-turn-dispatch.js

@@ -0,0 +1,235 @@
+/**
+ * Generic production driver for one worker-backed Loop Engine turn.
+ *
+ * Review and ideation retain their ergonomic coordinate drivers, but every
+ * loop kind can enter the same AttemptAuthority lifecycle through this seam.
+ * The adapter creates transport projections and starts the worker; it never
+ * advances a phase or evaluates a gate.
+ */
+import { resolveModel } from './agent-capability.js';
+import { listAgentIdentities } from './agent-registry.js';
+import { transitionAgentRun } from './agentruns.js';
+import { loadAssignment, patchAssignmentMessageId, transitionAssignment } from './assignments.js';
+import { attachAssignmentMessageToClaim, createCoordinatorClaim, ensureClaimAssignmentBinding, } from './claims.js';
+import { generateDispatchBrief } from './dispatcher.js';
+import { search } from './search.js';
+import { attemptExecution } from './execution.js';
+import { resolveExecutionCandidate } from './execution-contract.js';
+import { buildHarnessInvocation, resolveHarnessBinding } from './harness-adapters/index.js';
+import { phasePolicy } from './loops/kind-policies.js';
+import { buildIdeationBrief } from './loops/brief-assembly.js';
+import { getLoop } from './loops/store.js';
+import { prepareTurnExecution } from './loops/turn-execution.js';
+import { sendMessage } from './messaging.js';
+export async function dispatchLoopTurn(input) {
+    const loop = getLoop(input.loop_id, input.cwd);
+    if (!loop)
+        return { loop_id: input.loop_id, slot_id: input.slot_id, error: `unknown loop_id ${input.loop_id}` };
+    const slot = loop.slots.find((candidate) => candidate.slot_id === input.slot_id);
+    const result = {
+        loop_id: loop.id,
+        slot_id: input.slot_id,
+        kind: loop.kind,
+        phase: loop.current_phase,
+        agent: slot?.agent,
+    };
+    if (loop.status !== 'open')
+        return { ...result, error: `loop ${loop.id} is ${loop.status}, not open` };
+    if (!slot)
+        return { ...result, error: `slot ${input.slot_id} not found` };
+    const policy = phasePolicy(loop.kind, loop.current_phase);
+    if (!policy || policy.execution !== 'worker') {
+        return { ...result, error: `${loop.kind}.${loop.current_phase} is ${policy?.execution ?? 'unknown'}, not a worker phase` };
+    }
+    let agent = slot.agent;
+    let agentId = slot.agent_id;
+    if (!agent) {
+        const registered = listAgentIdentities(input.cwd).filter((identity) => identity.kind !== 'human');
+        const allowed = new Set(input.candidate_agents ?? registered.map((identity) => identity.agent_name));
+        const candidates = registered
+            .filter((identity) => allowed.has(identity.agent_name))
+            .map((identity) => ({ agent: identity.agent_name, agent_id: identity.agent_id }));
+        const role = loop.kind === 'review' || loop.kind === 'ideation'
+            ? 'review'
+            : loop.kind === 'research' ? 'consult' : 'execute';
+        const selection = resolveExecutionCandidate(candidates, {
+            roles: [role], required_surfaces: ['cli_spawn'], execution_surfaces: [], required_tools: [],
+        });
+        if (selection.kind !== 'selected') {
+            return { ...result, error: `slot ${slot.slot_id} has no compatible worker candidate` };
+        }
+        agent = selection.selected.agent;
+        agentId = selection.selected.agent_id;
+        result.agent = agent;
+    }
+    const scope = slot.scope_hint ?? `loop:${loop.kind}:${loop.id}:slot:${slot.slot_id}`;
+    const sectionByCategory = {
+        traps: 'traps', decisions: 'decisions', constraints: 'constraints', handoffs: 'handoffs',
+        plans: 'plans', candidates: 'candidates',
+    };
+    const provider = {
+        fetch(category, query, topK) {
+            const section = sectionByCategory[category];
+            if (!section)
+                return [];
+            return search({ query, section, maxResults: topK, cwd: input.cwd, includePending: section === 'candidates' })
+                .map((item) => ({
+                id: item.id, category, text: item.text, score: item.score, relatedPaths: item.related_paths,
+            }));
+        },
+    };
+    const phaseBrief = buildIdeationBrief({
+        thread: loop,
+        slotRole: slot.role,
+        memoryProvider: provider,
+        seedText: input.task,
+        scopeHints: slot.scope_hint ? slot.scope_hint.split(',').map((value) => value.trim()) : [],
+    });
+    const laneContext = slot.lane
+        ? `Lane: ${slot.lane}\nPlans: ${(slot.plan_ids ?? []).join(', ') || '(none)'}\nSteps: ${(slot.step_ids ?? []).join(', ') || '(whole plan)'}`
+        : '';
+    const scopedTask = [phaseBrief.text, laneContext].filter(Boolean).join('\n\n');
+    const description = `${loop.kind} loop turn for ${loop.id} slot ${slot.slot_id} phase ${loop.current_phase}. ${input.task}`;
+    try {
+        const claim = createCoordinatorClaim({
+            agent,
+            scope,
+            description,
+            dispatcherAgent: input.dispatcher_agent,
+            sessionId: input.session_id,
+            cwd: input.cwd,
+        });
+        result.claim_id = claim.claimId;
+        result.worktree_path = claim.worktreePath;
+        if (claim.scopeConflict) {
+            result.error = `scope ${scope} is already claimed by ${claim.conflictAgent ?? 'another agent'}`;
+            return result;
+        }
+        const model = resolveModel(agent, { override: input.model });
+        const binding = resolveHarnessBinding(agent, model);
+        const prepared = prepareTurnExecution({
+            kind: loop.kind,
+            loop_id: loop.id,
+            slot_id: slot.slot_id,
+            phase: loop.current_phase,
+            agent,
+            agent_id: agentId,
+            claim_id: claim.claimId,
+            dispatcher_agent: input.dispatcher_agent,
+            dispatcher_agent_id: input.dispatcher_agent_id,
+            dispatcher_session_id: input.session_id,
+            scope,
+            description,
+            task: scopedTask,
+            cwd: input.cwd,
+            worktree_path: claim.worktreePath,
+            model,
+            harness_binding: binding,
+            assignment_tags: ['coordinate', loop.kind, 'loop', 'turn-owned'],
+            run_tags: ['turn-owned', loop.kind, 'loop'],
+        });
+        if (prepared.kind !== 'won') {
+            result.execution_status = 'inbox_only';
+            result.error = prepared.reason;
+            return result;
+        }
+        result.assignment_id = prepared.assignment_id;
+        result.run_id = prepared.run_id;
+        result.turn_id = prepared.turn_id;
+        result.worktree_path = prepared.workspace_path;
+        const turnEcho = {
+            turn_id: prepared.turn_id,
+            run_id: prepared.run_id,
+            nonce: prepared.nonce,
+            ...(prepared.execution_contract_ref ? {
+                contract_hash: prepared.execution_contract_ref.hash,
+                capability_snapshot_hash: prepared.execution_contract_ref.snapshot_hash,
+            } : {}),
+            ...(prepared.attempt_epoch !== undefined ? { attempt_epoch: prepared.attempt_epoch } : {}),
+            ...(prepared.workspace_digest ? { workspace_digest: prepared.workspace_digest } : {}),
+        };
+        const brief = generateDispatchBrief({
+            task: scopedTask,
+            agent,
+            claimId: claim.claimId,
+            scope,
+            worktreePath: prepared.workspace_path,
+            assignmentId: prepared.assignment_id,
+            executionContractRef: prepared.execution_contract_ref,
+            attemptFence: prepared.attempt_epoch !== undefined && prepared.workspace_digest ? {
+                turn_id: prepared.turn_id,
+                run_id: prepared.run_id,
+                nonce: prepared.nonce,
+                attempt_epoch: prepared.attempt_epoch,
+                workspace_digest: prepared.workspace_digest,
+            } : undefined,
+            cwd: input.cwd,
+        });
+        const message = sendMessage({
+            from: input.dispatcher_agent,
+            to: agent,
+            type: 'assign',
+            text: brief,
+            ref: loop.id,
+            scope,
+            requires_ack: true,
+            claim_id: claim.claimId,
+            assignment_id: prepared.assignment_id,
+            tags: ['coordinate', loop.kind, 'loop', 'turn-owned'],
+            author_id: input.dispatcher_agent_id,
+            session_id: input.session_id,
+            payload: {
+                intent: 'loop_turn', loop_id: loop.id, slot_id: slot.slot_id,
+                phase: loop.current_phase, scope, claim_id: claim.claimId,
+                assignment_id: prepared.assignment_id, worktree_path: prepared.workspace_path,
+            },
+        }, input.cwd);
+        result.message_id = message.id;
+        attachAssignmentMessageToClaim(claim.claimId, message.id, input.cwd);
+        ensureClaimAssignmentBinding(claim.claimId, prepared.assignment_id, input.cwd, {
+            worktreePath: prepared.workspace_path,
+        });
+        const assignment = loadAssignment(prepared.assignment_id, input.cwd);
+        if (assignment?.status === 'created' || assignment?.status === 'retrying') {
+            transitionAssignment(prepared.assignment_id, 'offered', { actor: input.dispatcher_agent }, input.cwd);
+        }
+        patchAssignmentMessageId(prepared.assignment_id, message.id, input.cwd);
+        const invoke = buildHarnessInvocation(agent, brief, {
+            mode: 'worker', model, binding,
+            contract: undefined,
+            capability_snapshot: prepared.capability_snapshot,
+        })?.invoke;
+        const execution = await attemptExecution(invoke, {
+            agent,
+            autoExecute: input.auto_execute ?? true,
+            worktreePath: prepared.workspace_path,
+            claimId: claim.claimId,
+            assignmentId: prepared.assignment_id,
+            dispatcherAgent: input.dispatcher_agent,
+            dispatcherAgentId: input.dispatcher_agent_id,
+            cwd: input.cwd,
+            requireWorktree: true,
+            turnEcho,
+        });
+        result.execution_status = execution.execution_status;
+        result.command = execution.command;
+        result.shell = execution.shell;
+        if (execution.error)
+            result.error = execution.error;
+        if (execution.execution_status === 'delivered_and_started') {
+            try {
+                transitionAgentRun(prepared.run_id, 'running', {
+                    actor: input.dispatcher_agent,
+                    status_reason: `turn-owned ${loop.kind} worker spawned`,
+                }, input.cwd);
+            }
+            catch { /* the reconciler converges transport state */ }
+        }
+        return result;
+    }
+    catch (error) {
+        result.error = `loop turn dispatch failed: ${error instanceof Error ? error.message : String(error)}`;
+        return result;
+    }
+}
+//# sourceMappingURL=loop-turn-dispatch.js.map

package/dist/core/loops/artifact-contract.js

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+/** Immutable description of one artifact expected from a worker attempt. */
+export const ExpectedArtifactSchema = z.object({
+    logical_name: z.string().min(1),
+    worker_path: z.string().min(1),
+    loop_artifact_type: z.string().min(1),
+    schema_id: z.string().optional(),
+    completion_policy: z.enum(['required', 'optional']).default('required'),
+    sha256: z.string().optional(),
+});
+//# sourceMappingURL=artifact-contract.js.map