mixdog 1.4.1 → 1.4.3

package/src/runtime/agent/orchestrator/runtime-core/goal-tool-exec.mjs

@@ -1,63 +1,21 @@
 /**
- * goal-tool-exec.mjs — the model-facing `goal` tool: optimistic-concurrency
- * bookkeeping (the revision the model last observed) and one handler per
- * tool action, each replying with the compact or full Goal view.
+ * goal-tool-exec.mjs — the model-facing `goal` tool: status, create, and the
+ * model's two settlements (complete after its evidence audit, block on an
+ * impasse), each replying with the compact or full Goal view.
  */
 import { validateGoalToolCall } from './goal-tool-defs.mjs';
 import { assertSessionId, parseGoalDuration } from './goal-state.mjs';
-import { goalFinished } from './goal-mutations.mjs';
 
-export function observeGoal(ctx, id, goal) {
-  if (goal) ctx.observedGoals.set(id, { id: goal.id, revision: goal.revision });
-  else ctx.observedGoals.delete(id);
-}
-
-function toolReply(ctx, id, goal, { full = false, previousIds = null } = {}) {
-  observeGoal(ctx, id, goal);
+function toolReply(goal, { full = false } = {}) {
   let goalView = goal;
   if (goal && !full) {
-    goalView = {
-      id: goal.id,
-      revision: goal.revision,
-      status: goal.status,
-      tasksCompleted: goal.tasksCompleted,
-      tasksTotal: goal.tasksTotal,
-      taskSlotsUsed: goal.taskSlotsUsed,
-      tasksUpdatedAt: goal.tasksUpdatedAt,
-      timeUsedMs: goal.timeUsedMs,
-    };
+    goalView = { id: goal.id, status: goal.status, timeUsedMs: goal.timeUsedMs };
     if (goal.blocker) goalView.blocker = goal.blocker;
-    if (goal.needsTaskReview) goalView.needsTaskReview = true;
-  }
-  const result = { goal: goalView, remaining_ms: goal?.remainingMs ?? null };
-  if (!full && previousIds && goal) {
-    const added = goal.tasks.filter((task) => !previousIds.has(task.id));
-    if (added.length) result.assigned_tasks = added.map(({ id: taskId, text }) => ({ id: taskId, text }));
   }
-  return JSON.stringify(result);
+  return JSON.stringify({ goal: goalView, remaining_ms: goal?.remainingMs ?? null });
 }
 
-function mutateObserved(ctx, id, args, operation) {
-  const current = ctx.requireGoal(id);
-  const expectedGoalId = ctx.turnGoalIds.get(id) || current.id;
-  const observed = ctx.observedGoals.get(id);
-  // Capture BEFORE queueing: two concurrent calls based on one snapshot must
-  // not both overwrite it. Old frozen schemas use the last tool result.
-  let expectedRevision = current.revision;
-  if (args.revision != null && args.revision !== '') expectedRevision = args.revision;
-  else if (observed?.id === expectedGoalId) expectedRevision = observed.revision;
-  return ctx.withMutation(id, () => {
-    const latest = ctx.requireGoal(id);
-    if (latest.id !== expectedGoalId) throw new Error('stale Goal update rejected because the active Goal changed');
-    if (latest.revision !== expectedRevision)
-      throw new Error(
-        `stale Goal revision: expected ${expectedRevision}, current ${latest.revision}; read goal status and reconcile before retrying`
-      );
-    return operation(expectedGoalId);
-  });
-}
-
-/** create/resume budget in ms, or undefined when the call carries none. */
+/** create budget in ms, or undefined when the call carries none. */
 function toolTimeLimitMs(args) {
   if (args.time_limit_minutes == null || args.time_limit_minutes === '') return undefined;
   const minutes = Number(args.time_limit_minutes);
@@ -67,75 +25,51 @@ function toolTimeLimitMs(args) {
   return parseGoalDuration(minutes * 60_000);
 }
 
-async function pauseOrResume(ctx, id, args, action) {
-  const timeLimitMs = action === 'resume' ? toolTimeLimitMs(args) : undefined;
-  const result = await mutateObserved(ctx, id, args, (expectedGoalId) => {
+// A settlement applies to the Goal this turn worked on: one replaced
+// meanwhile is refused instead of settled by mistake.
+async function settleStatus(ctx, id, args, action) {
+  const expectedGoalId = ctx.turnGoalIds.get(id) || ctx.requireGoal(id).id;
+  const goal = await ctx.withMutation(id, () => {
     const current = ctx.requireGoal(id);
-    if (goalFinished(current)) {
-      throw new Error(`a ${current.status === 'complete' ? 'completed' : 'stopped'} Goal cannot be paused or resumed`);
+    // The objective was edited after this turn last saw it: the claim was made
+    // against old wording. Show the current text once; the next call, made
+    // with that text in view, settles normally.
+    const seen = ctx.turnObjectiveRevisions.get(id);
+    if (current.id === expectedGoalId && seen !== undefined && seen !== current.objectiveRevision) {
+      ctx.turnObjectiveRevisions.set(id, current.objectiveRevision);
+      throw new Error(
+        `The Goal objective changed since this turn began, so ${action} was not recorded. ` +
+          `Current objective: ${current.objective}\nCheck the work against it, then call goal ${action} again if it still holds.`
+      );
     }
-    // The model pauses only at the user's explicit request, so its pause is the
-    // user's pause; waits on the user go through block.
-    const change =
-      action === 'resume'
-        ? { updates: args.updates, tasks: args.tasks, duration: timeLimitMs, timeMode: args.time_mode }
-        : {};
-    return ctx.control(id, { action, expectedGoalId, ...change });
-  });
-  return toolReply(ctx, id, result.goal, { full: action === 'resume' });
-}
-
-async function editTasks(ctx, id, args, action) {
-  let previousIds;
-  const goal = await mutateObserved(ctx, id, args, (expectedGoalId) => {
-    previousIds = new Set(ctx.requireGoal(id).tasks.map((task) => task.id));
-    return ctx.setGoalTasks(id, args, { expectedGoalId, partial: action === 'update_tasks' });
-  });
-  return toolReply(ctx, id, goal, { previousIds });
-}
-
-async function settleStatus(ctx, id, args, action) {
-  const goal = await mutateObserved(ctx, id, args, (expectedGoalId) =>
-    ctx.updateGoal(
+    return ctx.updateGoal(
       id,
-      {
-        status: action === 'block' ? 'blocked' : 'complete',
-        ...(action === 'block' ? { blocker: args.blocker } : {}),
-      },
+      { status: action === 'block' ? 'blocked' : 'complete', ...(action === 'block' ? { blocker: args.blocker } : {}) },
       { expectedGoalId }
-    )
-  );
-  return toolReply(ctx, id, goal);
+    );
+  });
+  return toolReply(goal);
 }
 
 const GOAL_TOOL_ACTIONS = {
   status(ctx, id) {
     // Same view the user sees. Reading the stored record here showed the
     // model Goals the user had already archived away.
-    ctx.readRecord(id); // A real I/O error is an actionable error, not "no Goal".
-    return toolReply(ctx, id, ctx.visibleSnapshot(id), { full: true });
+    const record = ctx.readRecord(id).goal; // A real I/O error is an actionable error, not "no Goal".
+    if (record && ctx.turnGoalIds.get(id) === record.id) ctx.turnObjectiveRevisions.set(id, record.objectiveRevision);
+    return toolReply(ctx.visibleSnapshot(id), { full: true });
   },
   async create(ctx, id, args) {
     const timeLimitMs = toolTimeLimitMs(args);
     const goal = await ctx.withMutation(id, () =>
       ctx.createGoal(id, {
         objective: args.objective,
-        tasks: args.tasks,
         startInCurrentTurn: true,
         ...(timeLimitMs != null ? { timeLimitMs } : {}),
-        timeMode: args.time_mode,
       })
     );
-    return toolReply(ctx, id, goal, { full: true });
-  },
-  async abandon(ctx, id, args) {
-    const goal = await mutateObserved(ctx, id, args, (expectedGoalId) => ctx.abandonGoal(id, { expectedGoalId }));
-    return toolReply(ctx, id, goal);
+    return toolReply(goal, { full: true });
   },
-  pause: pauseOrResume,
-  resume: pauseOrResume,
-  set_tasks: editTasks,
-  update_tasks: editTasks,
   block: settleStatus,
   complete: settleStatus,
 };
@@ -145,6 +79,5 @@ export async function executeGoalTool(ctx, name, args = {}, context = {}) {
   const id = assertSessionId(sessionId);
   if (name !== 'goal') throw new Error(`unknown Goal tool: ${name}`);
   const action = validateGoalToolCall(args);
-  const handler = GOAL_TOOL_ACTIONS[action];
-  return handler(ctx, id, args, action);
+  return GOAL_TOOL_ACTIONS[action](ctx, id, args, action);
 }

package/src/runtime/agent/orchestrator/runtime-core/goal-turns.mjs

@@ -4,38 +4,21 @@
  * should continue, and retiring finished work on the next user prompt.
  */
 import { continuationPrompt } from './goal-text.mjs';
-import { GOAL_TASK_SETTLED } from './goal-tool-defs.mjs';
 import {
   assertSessionId,
   checkpointActiveClock,
   clearTurnFailures,
-  publicGoal,
   resumeGoalState,
-  runningAgentWork,
   startActiveClock,
   stopActiveClock,
 } from './goal-state.mjs';
 import { goalFinished } from './goal-mutations.mjs';
-import { observeGoal } from './goal-tool-exec.mjs';
+import { awaitingBackgroundWork } from '../../../shared/background-wait.mjs';
 import { clean } from '../../../shared/clean.mjs';
 
-// Every recorded task is settled while a requested duration still has time.
-// Completed rows neither complete the objective nor shorten its duration, so
-// this state must not loop the model over an unchanged list.
-function settledDurationWait(goal) {
-  return (
-    goal?.status === 'active' &&
-    goal.timeMode === 'duration' &&
-    goal.remainingMs > 0 &&
-    !goal.needsTaskReview &&
-    goal.tasks.length > 0 &&
-    goal.tasks.every((task) => GOAL_TASK_SETTLED.includes(task.status))
-  );
-}
-
-// The review is spent per Goal, turn, and actionable revision: a resumed,
-// re-scoped, or re-planned Goal earns a fresh one without any extra clearing.
-const idleReviewKey = (goal) => `${goal.id}:${goal.turnCount}:${goal.revision}`;
+// The no-progress wait is spent per Goal and turn: the next user turn (or a
+// resume, which starts a new turn) earns a fresh continuation.
+const idleReviewKey = (goal) => `${goal.id}:${goal.turnCount}`;
 
 // An automatic turn that called no tool answered its prompt without progress.
 // Asking again over the same list only repeats that answer every few seconds
@@ -52,16 +35,8 @@ function automaticTurnWithoutActivity(detail, goal) {
 
 // Continuation prompts are enqueued as meta user messages, so a delivered rules
 // block stays in the transcript until the context is compacted or rewound. The
-// marker records which Goal's rules are already there: a new session or Goal, a
-// reconciliation the rules must frame, or an explicit reset re-sends them.
-function needsFullContinuationRules(markedGoalId, goal) {
-  return markedGoalId !== goal.id || goal.needsTaskReview === true;
-}
-
-// A durable list drifts out of attention after roughly ten quiet turns — the
-// staleness cadence task-reminder surfaces settle on across the industry — so
-// the state block returns on that count rather than on an arbitrary period.
-const GOAL_STATE_REMINDER_QUIET_TURNS = 10;
+// marker records which Goal's rules are already there: a new session or Goal,
+// or an explicit reset (compaction, objective edit) re-sends them.
 
 /** Fold a settled turn's outcome (usage limit, cancel, failure, or a clean
  *  finish) into the Goal status and clocks. */
@@ -103,7 +78,7 @@ function applyTurnOutcome(goal, detail, at) {
   if (goal.timeLimitMs > 0 && goal.timeUsedMs >= goal.timeLimitMs) {
     stopActiveClock(goal, at);
     goal.status = 'duration_reached';
-    goal.timeUsedMs = Math.max(goal.timeUsedMs, goal.timeLimitMs);
+    goal.timeUsedMs = goal.timeLimitMs;
   }
 }
 
@@ -112,6 +87,7 @@ export function createGoalTurnLifecycle(ctx) {
     now,
     turnGoalIds,
     turnStartedAt,
+    turnObjectiveRevisions,
     idleReviewTurns,
     continuationTiers,
     unsavedStops,
@@ -129,22 +105,19 @@ export function createGoalTurnLifecycle(ctx) {
         if (!goal || goal.archivedAt) {
           turnGoalIds.delete(id);
           turnStartedAt.delete(id);
+          turnObjectiveRevisions.delete(id);
           return null;
         }
         const at = now();
         turnGoalIds.set(id, goal.id);
         turnStartedAt.set(id, at);
-        observeGoal(ctx, id, publicGoal(goal, at));
+        turnObjectiveRevisions.set(id, goal.objectiveRevision);
         if (goal.status !== 'active') return visibleSnapshot(id);
         goal.turnCount = Math.max(0, Math.floor(Number(goal.turnCount) || 0)) + 1;
         startActiveClock(goal, at);
         goal.updatedAt = at;
-        const published = await commit(id, goal);
-        // A turn that starts from the settled duration wait IS that review, so
-        // the next continuation waits instead of asking again unchanged.
-        if (settledDurationWait(published)) idleReviewTurns.set(id, idleReviewKey(published));
-        else idleReviewTurns.delete(id);
-        return published;
+        idleReviewTurns.delete(id);
+        return commit(id, goal);
       });
     },
     settleTurn(sessionId, detail = {}) {
@@ -152,6 +125,7 @@ export function createGoalTurnLifecycle(ctx) {
         const expectedGoalId = turnGoalIds.get(id) || '';
         turnGoalIds.delete(id);
         turnStartedAt.delete(id);
+        turnObjectiveRevisions.delete(id);
         const goal = readRecord(id).goal;
         // commit() returns the record even when it is archived, so a settled
         // turn on retired work would republish the capsule the user's prompt
@@ -192,50 +166,21 @@ export function createGoalTurnLifecycle(ctx) {
         return commit(id, goal, options);
       });
     },
-    continuation(sessionId, { agentStatus = null } = {}) {
+    // `todo`: the session's open step list, carried in every continuation.
+    continuation(sessionId, { agentStatus = null, todo = '' } = {}) {
       const goal = visibleSnapshot(sessionId);
       if (goal?.status !== 'active') return { run: false, reason: goal?.status || 'missing', goal };
-      if (runningAgentWork(agentStatus)) return { run: false, reason: 'agent-running', goal };
       const id = assertSessionId(sessionId);
+      // The same wait rule as the todo completion check: a running agent or
+      // an awaited background shell wakes the session when it ends.
+      if (awaitingBackgroundWork({ sessionId: id, agentStatus })) return { run: false, reason: 'awaiting-work', goal };
       if (unsavedStops.get(id) === goal.id) return { run: false, reason: 'unsaved-stop', goal };
-      const answered = idleReviewTurns.get(id) === idleReviewKey(goal);
-      if (settledDurationWait(goal)) {
-        // The model already answered this exact list with no new work, so the
-        // deadline timer owns the rest of the wait and delivers closeout;
-        // task/scope changes still publish and wake newly actionable work.
-        if (answered) return { run: false, reason: 'duration-wait', goal };
-        // One turn to spend the remaining duration on new work or to park
-        // approval-dependent work: idling it away is not the requested wait.
-        // This turn has to decide the rest of the duration, so it carries the
-        // full rules that decision is judged against.
-        continuationTiers.set(id, { goalId: goal.id, revision: goal.revision, quietTurns: 0 });
-        return { run: true, reason: 'idle-review', goal, prompt: continuationPrompt(goal, { idleReview: true }) };
-      }
-      // The same wait for an unfinished list: a task change, a user turn, or
+      // An automatic turn already answered with no tool call: a user turn or
       // the deadline's closeout starts the next Goal turn.
-      if (answered) return { run: false, reason: 'no-progress-wait', goal };
-      const entry = continuationTiers.get(id);
-      if (needsFullContinuationRules(entry?.goalId, goal)) {
-        continuationTiers.set(id, { goalId: goal.id, revision: goal.revision, quietTurns: 0 });
-        return { run: true, reason: 'idle', goal, prompt: continuationPrompt(goal) };
-      }
-      // A changed revision means the model mutated tasks last turn and holds
-      // the fresh list in its own tool result; repeating it buys nothing. The
-      // state block returns only once the list has gone unread long enough to
-      // drift out of attention.
-      const quietTurns = entry.revision === goal.revision ? entry.quietTurns + 1 : 0;
-      const includeState = quietTurns >= GOAL_STATE_REMINDER_QUIET_TURNS;
-      continuationTiers.set(id, {
-        goalId: goal.id,
-        revision: goal.revision,
-        quietTurns: includeState ? 0 : quietTurns,
-      });
-      return {
-        run: true,
-        reason: 'idle',
-        goal,
-        prompt: continuationPrompt(goal, { includeRules: false, includeState }),
-      };
+      if (idleReviewTurns.get(id) === idleReviewKey(goal)) return { run: false, reason: 'no-progress-wait', goal };
+      const includeRules = continuationTiers.get(id) !== goal.id;
+      continuationTiers.set(id, goal.id);
+      return { run: true, reason: 'idle', goal, prompt: continuationPrompt(goal, { includeRules, todo }) };
     },
     resetContinuationRules(sessionId) {
       continuationTiers.delete(assertSessionId(sessionId));

package/src/runtime/agent/orchestrator/runtime-core/orchestration.mjs

@@ -1,59 +1,81 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { normalizeOrchestrationMode } from '../../../shared/orchestration.mjs';
-
-const BATCHING = {
-  focused: `Lead executes the main scope directly. Delegate only substantial,
-self-contained supporting work, one agent per role; batch related tasks
-rather than splitting them for parallelism.`,
-  balanced: `Delegate independent work by coherent feature or module, one agent per
-scope; a scope is one verifiable deliverable. Batch related tasks within the
-same change scope rather than splitting every file or step.`,
-  swarm: `Delegate every independent scope to its own agent; a scope is one
-verifiable deliverable, not a bundle of steps. Treat disjoint file or
-module sets as independent and merge scopes only on a true output
-dependency.`,
-};
-
-const SOLO = `# Orchestration Mode: Solo
-
-Lead executes all work directly and never delegates on its own judgment.
-Only when the user explicitly asks for delegation, load the deferred \`agent\`
-tool and brief each agent as the Lead rules describe.`;
+import { mixdogRoot, resolvePluginData } from '../../../shared/plugin-paths.mjs';
+import { decodeInstructionFile } from '../../../../lib/instruction-text.cjs';
 
 /** Agent mode's fixed delegation block, in place of the orchestration mode. */
 export const AGENT_MODE_DELEGATION = `# Delegation
 
-Handle conversation yourself. Delegate specialised work to sub-agents. Hand
-substantial coding to a new agent task session (\`session create\`) with
-a self-contained brief: start it when already requested, otherwise suggest it. Then relay the
-result in your own words. Promise a follow-up only when the session result allows it.`;
+Handle conversation yourself. Do quick lookups and small edits yourself. Hand
+self-contained investigation, writing or implementation to sub-agents
+(\`agent\`); their reports return to this chat. Open a new agent task session
+(\`session create\`) only for a big plan, multi-step work across many files or
+stages that needs its own Lead, with a self-contained brief: start it when
+already requested, otherwise suggest it. Then relay the result in your own
+words. Promise a follow-up only when the session result allows it.`;
 
 /** An agent-mode Lead's contact catalog intro: the user's other bots. */
 export const MIXY_CONTACTS_INTRO = `The user's other bots. Hand one a request with \`session send\` to its chat and a
 self-contained brief.`;
 
-export function orchestrationInstructions(value) {
+const modeFileName = (mode) => `${normalizeOrchestrationMode(mode)}.md`;
+
+/** The shipped mode file (<root>/orchestration/<mode>.md). */
+export const shippedOrchestrationPath = (mode) => join(mixdogRoot(), 'orchestration', modeFileName(mode));
+/** The user's replacement (<data>/orchestration/<mode>.md). */
+export const userOrchestrationPath = (mode) => join(resolvePluginData(), 'orchestration', modeFileName(mode));
+
+// A file's text (CRLF → LF, trailing whitespace trimmed), null when it does not
+// exist, or { problem } when it cannot serve as the prompt (instruction-text.cjs).
+// promptRulesRevision reads every mode on each check, so a read is reused while
+// the file's identity (mtime, ctime, inode, size) is unchanged — but only once
+// the file is older than the timestamp granularity: a file written moments ago
+// can change again within the same tick without any of those moving.
+const SETTLED_MS = 2000;
+const fileCache = new Map();
+export function readInstructionFile(file) {
+  let stat;
+  try {
+    stat = statSync(file);
+  } catch (error) {
+    return error?.code === 'ENOENT' || error?.code === 'ENOTDIR' ? null : { problem: 'unreadable' };
+  }
+  const key = `${stat.mtimeMs}:${stat.ctimeMs}:${stat.ino}:${stat.size}`;
+  const hit = fileCache.get(file);
+  if (hit?.key === key && hit.settled) return hit.value;
+  let value;
+  try {
+    if (!stat.isFile()) value = { problem: 'unreadable' };
+    else {
+      const decoded = decodeInstructionFile(readFileSync(file));
+      value = decoded.problem ? decoded : { text: decoded.text.replace(/\r\n/g, '\n').trimEnd() };
+    }
+  } catch {
+    value = { problem: 'unreadable' };
+  }
+  fileCache.set(file, { key, value, settled: Date.now() - stat.mtimeMs > SETTLED_MS });
+  return value;
+}
+
+/**
+ * Where a mode's text comes from: the user's file when it is usable, else the
+ * shipped one. `problem` says why a user file that exists was passed over
+ * (empty, too-large, not-text, unreadable); `text` is the prompt text.
+ */
+function orchestrationModeSource(value) {
   const mode = normalizeOrchestrationMode(value);
-  if (mode === 'none') return SOLO;
-  // Focused already says Lead executes the main scope directly.
-  const oneScope =
-    mode === 'focused' ? '' : '\nIf the plan has only one implementation scope, Lead executes it directly.';
-  return `# Orchestration Mode: ${mode[0].toUpperCase()}${mode.slice(1)}
-
-${BATCHING[mode]}
-
-The mode sets how work splits; an agent's description sets its role and when
-it runs. Splitting applies to every role alike — implementation, review,
-investigation, writing — by file, module, commit range or risk area.${oneScope}
-
-Delegation is for work whose size justifies a brief. When the brief would have
-to spell out the edits themselves — a few localized changes whose sites Lead
-already holds — Lead makes them directly in every mode; the number of files or
-scopes does not change this.
-
-Dispatch all ready independent scopes in one turn. Only a scope that requires
-another's output waits.
-A new independent need goes to a new agent. When scopes touch the same file, name one owner for
-that file in each brief.
-Use only available agents; when none fits a role, Lead does that work itself
-and never changes settings to enable one.`;
+  const user = readInstructionFile(userOrchestrationPath(mode));
+  if (user?.text) return { mode, source: 'user', text: user.text };
+  const shipped = readInstructionFile(shippedOrchestrationPath(mode));
+  return {
+    mode,
+    source: 'default',
+    text: shipped?.text ?? '',
+    ...(user?.problem ? { problem: user.problem } : {}),
+  };
+}
+
+export function orchestrationInstructions(value) {
+  return orchestrationModeSource(value).text;
 }