@moxxy/mode-goal 0.26.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@moxxy/mode-goal",
+  "version": "0.26.0",
+  "description": "Goal mode: state a goal once and the agent works autonomously across many turns until it calls goal_complete (or goal_abandon), guarded by an iteration cap, a token budget, a stuck-loop detector, no-progress detection, and the user's abort.",
+  "keywords": [
+    "moxxy",
+    "agent",
+    "mode",
+    "autonomous",
+    "goal"
+  ],
+  "homepage": "https://moxxy.ai",
+  "bugs": {
+    "url": "https://github.com/moxxy-ai/moxxy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moxxy-ai/moxxy.git",
+    "directory": "packages/mode-goal"
+  },
+  "author": "Michal Makowski <michal.makowski97@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "moxxy": {
+    "plugin": {
+      "entry": "./dist/index.js",
+      "kind": "mode"
+    }
+  },
+  "dependencies": {
+    "zod": "^3.24.0",
+    "@moxxy/sdk": "0.26.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8",
+    "@moxxy/tsconfig": "0.0.0",
+    "@moxxy/core": "0.26.0",
+    "@moxxy/vitest-preset": "0.0.0",
+    "@moxxy/testing": "0.0.44"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/completion.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import type { CollectedToolUse, MoxxyEvent } from '@moxxy/sdk';
+
+import { detectGoalTerminal } from './completion.js';
+import { GOAL_ABANDON_TOOL, GOAL_COMPLETE_TOOL } from './constants.js';
+
+// Minimal tool_result stand-in — detectGoalTerminal only reads type/ok/callId.
+function result(callId: string, ok: boolean): MoxxyEvent {
+  return { type: 'tool_result', callId, ok } as unknown as MoxxyEvent;
+}
+function use(id: string, name: string, input: unknown): CollectedToolUse {
+  return { id, name, input };
+}
+
+describe('detectGoalTerminal', () => {
+  it('returns null when the batch has no goal tools', () => {
+    const log = [result('c1', true)];
+    expect(detectGoalTerminal(log, [use('c1', 'Bash', {})])).toBeNull();
+  });
+
+  it('detects a successful goal_complete and parses summary + evidence', () => {
+    const batch = [use('c1', GOAL_COMPLETE_TOOL, { summary: 'shipped', evidence: ['tests pass', 'built'] })];
+    const out = detectGoalTerminal([result('c1', true)], batch);
+    expect(out).toEqual({ kind: 'complete', summary: 'shipped', evidence: ['tests pass', 'built'] });
+  });
+
+  it('detects goal_abandon with reason + needsFromUser', () => {
+    const batch = [use('c2', GOAL_ABANDON_TOOL, { reason: 'missing key', needsFromUser: 'set API_KEY' })];
+    const out = detectGoalTerminal([result('c2', true)], batch);
+    expect(out).toEqual({ kind: 'abandon', reason: 'missing key', needsFromUser: 'set API_KEY' });
+  });
+
+  it('ignores a goal tool whose result failed (e.g. hook-denied)', () => {
+    const batch = [use('c3', GOAL_COMPLETE_TOOL, { summary: 'x' })];
+    expect(detectGoalTerminal([result('c3', false)], batch)).toBeNull();
+  });
+
+  it('only reacts to its OWN call ids (not a same-name result from elsewhere)', () => {
+    const batch = [use('c4', GOAL_COMPLETE_TOOL, { summary: 'x' })];
+    // A successful result exists, but for a different callId.
+    expect(detectGoalTerminal([result('other', true)], batch)).toBeNull();
+  });
+
+  it('defaults summary/reason when the model omitted them', () => {
+    const out = detectGoalTerminal([result('c5', true)], [use('c5', GOAL_COMPLETE_TOOL, {})]);
+    expect(out).toEqual({ kind: 'complete', summary: 'Goal completed.', evidence: [] });
+  });
+
+  it('drops non-string evidence elements from raw (unvalidated) model input', () => {
+    // `input` is the RAW provider-emitted tool input — the model can put
+    // anything in `evidence`. Non-string elements must be filtered out, not
+    // unsafely cast to string[].
+    const batch = [
+      use('c6', GOAL_COMPLETE_TOOL, {
+        summary: 'done',
+        evidence: ['tests pass', 1, { a: 1 }, null, 'built'],
+      }),
+    ];
+    const out = detectGoalTerminal([result('c6', true)], batch);
+    expect(out).toEqual({ kind: 'complete', summary: 'done', evidence: ['tests pass', 'built'] });
+  });
+
+  it('coerces a non-string summary to the default', () => {
+    const batch = [use('c7', GOAL_COMPLETE_TOOL, { summary: 42, evidence: [] })];
+    const out = detectGoalTerminal([result('c7', true)], batch);
+    expect(out).toEqual({ kind: 'complete', summary: 'Goal completed.', evidence: [] });
+  });
+});

package/src/completion.ts

@@ -0,0 +1,55 @@
+import type { CollectedToolUse, MoxxyEvent } from '@moxxy/sdk';
+
+import { GOAL_ABANDON_TOOL, GOAL_COMPLETE_TOOL } from './constants.js';
+
+export type GoalTerminal =
+  | { kind: 'complete'; summary: string; evidence: string[] }
+  | { kind: 'abandon'; reason: string; needsFromUser?: string }
+  | null;
+
+/**
+ * Inspect a just-executed batch of tool uses for a terminal goal signal. We
+ * confirm against the event log that the goal tool's `tool_result` actually
+ * succeeded (`ok: true`) — a hook could in principle have denied the call — so
+ * a denied goal_complete doesn't silently end the run. Returns the parsed
+ * payload (pulled from the model's tool INPUT, which is what it intended) so
+ * the caller can surface a clean summary.
+ */
+export function detectGoalTerminal(
+  log: ReadonlyArray<MoxxyEvent>,
+  batch: ReadonlyArray<CollectedToolUse>,
+): GoalTerminal {
+  // Map callId -> the goal tool use, so we only react to OUR tools.
+  const goalCalls = new Map<string, CollectedToolUse>();
+  for (const t of batch) {
+    if (t.name === GOAL_COMPLETE_TOOL || t.name === GOAL_ABANDON_TOOL) goalCalls.set(t.id, t);
+  }
+  if (goalCalls.size === 0) return null;
+
+  // Walk the log tail for the most recent successful result of one of those.
+  for (let i = log.length - 1; i >= 0; i--) {
+    const e = log[i];
+    if (!e || e.type !== 'tool_result' || !e.ok) continue;
+    const call = goalCalls.get(String(e.callId));
+    if (!call) continue;
+    const input = (call.input ?? {}) as Record<string, unknown>;
+    if (call.name === GOAL_COMPLETE_TOOL) {
+      return {
+        kind: 'complete',
+        summary: typeof input.summary === 'string' ? input.summary : 'Goal completed.',
+        // `input` is the RAW provider-emitted tool input (pre-zod), so the model
+        // can put anything in `evidence`. Keep only the string elements rather
+        // than asserting the type with an unchecked cast.
+        evidence: Array.isArray(input.evidence)
+          ? input.evidence.filter((x): x is string => typeof x === 'string')
+          : [],
+      };
+    }
+    return {
+      kind: 'abandon',
+      reason: typeof input.reason === 'string' ? input.reason : 'Goal abandoned.',
+      ...(typeof input.needsFromUser === 'string' ? { needsFromUser: input.needsFromUser } : {}),
+    };
+  }
+  return null;
+}

package/src/constants.ts

@@ -0,0 +1,75 @@
+import { asPluginId } from '@moxxy/sdk';
+
+export const GOAL_MODE_NAME = 'goal';
+export const GOAL_PLUGIN_ID = asPluginId('@moxxy/mode-goal');
+
+/** Tool the model MUST call to declare the goal achieved (the terminator). */
+export const GOAL_COMPLETE_TOOL = 'goal_complete';
+/** Tool the model calls to give up gracefully (blocked, needs the user). */
+export const GOAL_ABANDON_TOOL = 'goal_abandon';
+
+/**
+ * Hard cap on autonomous iterations. Goal mode keeps re-prompting the model to
+ * continue until it calls {@link GOAL_COMPLETE_TOOL}; this is the backstop that
+ * guarantees the loop terminates even if the model never declares done. High
+ * enough for a substantial multi-step task, low enough to bound a runaway.
+ */
+export const GOAL_MAX_ITERATIONS = 150;
+
+/**
+ * Consecutive iterations where the model emits NO tool calls and hasn't
+ * completed. After this many we stop (a stall) rather than spin forever
+ * nudging a model that has decided it's done without saying so.
+ */
+export const GOAL_MAX_NOOP_ITERATIONS = 3;
+
+/**
+ * Cumulative token ceiling (full prompt — input + cacheRead + cacheCreation +
+ * output — across the whole goal run). A second backstop alongside the
+ * iteration cap: a few long-context iterations can burn a lot of tokens even
+ * under the iteration limit. Generous; the iteration cap is usually the binding
+ * guard.
+ */
+export const GOAL_TOKEN_BUDGET = 4_000_000;
+
+/**
+ * Max consecutive retryable provider errors before goal mode bails with a fatal
+ * error. Goal mode runs unattended with auto-approval, so a sustained retryable
+ * condition (429 / overloaded / transient 5xx / ECONNRESET) must NOT busy-loop
+ * the provider — back off exponentially and give up after this many in a row.
+ * The counter resets on any clean provider call, so a long run can still
+ * recover from transient blips.
+ */
+export const MAX_CONSECUTIVE_RETRIES = 6;
+
+/**
+ * Layered on top of any user system prompt for the whole goal run. The framing
+ * is the inverse of normal chat: stopping is NOT the signal to end — the model
+ * keeps going until it explicitly calls goal_complete. It runs unattended with
+ * tool calls auto-approved, so it must be conservative about irreversible
+ * actions and decisive about declaring done.
+ */
+export const GOAL_SYSTEM_PROMPT = `You are operating in GOAL MODE. The user has given you a goal and you will work on it AUTONOMOUSLY, across as many steps as it takes, until it is genuinely done. You are running unattended — the user is not watching each step and your tool calls are auto-approved — so act like a careful senior engineer who has been handed the keys.
+
+How goal mode ends — this is the most important rule:
+- The loop does NOT end when you stop talking. It ends ONLY when you call the \`${GOAL_COMPLETE_TOOL}\` tool. If you produce a message without tool calls, you will simply be prompted to continue.
+- When (and only when) the goal is FULLY achieved AND you have verified it, call \`${GOAL_COMPLETE_TOOL}\` with a short summary and concrete evidence (commands you ran and their results, files you changed, tests that passed).
+- If you become genuinely blocked — a missing credential, a destructive action you shouldn't take unattended, or a requirement too ambiguous to proceed on — call \`${GOAL_ABANDON_TOOL}\` with the reason and exactly what you need from the user. Do NOT spin on something you cannot resolve.
+
+While working:
+- Break the goal into steps and just do them — don't stop to ask for confirmation on routine work; you have autonomy for this run.
+- Verify your work as you go (run the project's tests / build / linter when relevant) before declaring the goal complete.
+- Be careful with irreversible or destructive operations (deleting data, force-pushing, external side effects). When something is high-stakes and reversible-only-by-the-user, prefer to \`${GOAL_ABANDON_TOOL}\` and ask rather than guess.
+- Don't repeat the same failing action. If an approach isn't working, change it; if nothing works, abandon with a clear explanation.
+- Don't declare the goal complete prematurely. "I think this should work" is not done — verify first.`;
+
+/** Trailing nudge appended when the model idles (no tool calls) without
+ *  completing — reminds it the loop only ends via the completion tool. */
+export const CONTINUE_NUDGE =
+  `You stopped without calling \`${GOAL_COMPLETE_TOOL}\`. If the goal is fully achieved AND verified, ` +
+  `call \`${GOAL_COMPLETE_TOOL}\` now. Otherwise, take the next concrete step toward it.`;
+
+/** Sharper nudge once the model has idled repeatedly. */
+export const STALL_NUDGE =
+  `You have produced no tool calls for several turns. Either take a concrete next action toward the goal, ` +
+  `or call \`${GOAL_COMPLETE_TOOL}\` (if done) / \`${GOAL_ABANDON_TOOL}\` (if blocked). Do not reply with only text again.`;