@minionry/minion 0.7.36

package/dist/server/services/plan/agent-manager.js

@@ -0,0 +1,363 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+export const AGENT_ROLE_TEMPLATES = Object.freeze({
+    strategist: {
+        slug: 'strategist',
+        label: 'Strategist',
+        description: 'Plans positioning, messaging, and experiments. Writes strategy docs; does not ship code or ads.',
+        defaultProfile: {
+            strengths: ['strategy', 'positioning', 'messaging', 'research'],
+            preferredTasks: ['strategy', 'plan', 'roadmap', 'positioning'],
+            toolProfile: 'marketing',
+            model: 'opus',
+            maxConcurrency: 1,
+            costCapCents: 500,
+        },
+    },
+    writer: {
+        slug: 'writer',
+        label: 'Writer',
+        description: 'Drafts copy, landing pages, emails, and social posts against a brief.',
+        defaultProfile: {
+            strengths: ['copywriting', 'editing', 'seo', 'content'],
+            preferredTasks: ['copy', 'blog', 'email', 'ad', 'landing'],
+            toolProfile: 'marketing',
+            model: 'sonnet',
+            maxConcurrency: 2,
+            costCapCents: 200,
+        },
+    },
+    analyst: {
+        slug: 'analyst',
+        label: 'Analyst',
+        description: 'Queries metrics, computes dashboards, and writes up numeric findings.',
+        defaultProfile: {
+            strengths: ['sql', 'analytics', 'metrics', 'experiments'],
+            preferredTasks: ['analyze', 'report', 'dashboard', 'metric', 'ab-test'],
+            toolProfile: 'operations',
+            model: 'sonnet',
+            maxConcurrency: 2,
+            costCapCents: 150,
+        },
+    },
+    designer: {
+        slug: 'designer',
+        label: 'Designer',
+        description: 'Produces visual direction, mockups, and design-system suggestions.',
+        defaultProfile: {
+            strengths: ['visual-design', 'ux', 'figma', 'branding'],
+            preferredTasks: ['design', 'mockup', 'wireframe', 'icon'],
+            toolProfile: 'marketing',
+            model: 'sonnet',
+            maxConcurrency: 1,
+            costCapCents: 300,
+        },
+    },
+    engineer: {
+        slug: 'engineer',
+        label: 'Engineer',
+        description: 'Implements features, writes tests, and deploys code changes.',
+        defaultProfile: {
+            strengths: ['typescript', 'python', 'testing', 'devops'],
+            preferredTasks: ['implement', 'fix', 'bug', 'refactor', 'deploy'],
+            toolProfile: 'engineering',
+            model: 'opus',
+            maxConcurrency: 3,
+            costCapCents: 1000,
+        },
+    },
+    researcher: {
+        slug: 'researcher',
+        label: 'Researcher',
+        description: 'Digs into public sources for competitive, market, or user research.',
+        defaultProfile: {
+            strengths: ['research', 'web-search', 'synthesis', 'summarization'],
+            preferredTasks: ['research', 'survey', 'competitor', 'investigate'],
+            toolProfile: 'marketing',
+            model: 'sonnet',
+            maxConcurrency: 2,
+            costCapCents: 200,
+        },
+    },
+    operator: {
+        slug: 'operator',
+        label: 'Operator',
+        description: 'Runs recurring tasks, monitors systems, and flags exceptions.',
+        defaultProfile: {
+            strengths: ['ops', 'monitoring', 'scripting'],
+            preferredTasks: ['monitor', 'check', 'report', 'routine'],
+            toolProfile: 'operations',
+            model: 'haiku',
+            maxConcurrency: 3,
+            costCapCents: 50,
+        },
+    },
+});
+export function getRoleTemplate(slug) {
+    if (!slug)
+        return null;
+    return AGENT_ROLE_TEMPLATES[slug] ?? null;
+}
+export function listRoleTemplates() {
+    return Object.values(AGENT_ROLE_TEMPLATES);
+}
+export const DEFAULT_AGENT_PROFILE = Object.freeze({
+    strengths: [],
+    preferredTasks: [],
+    toolProfile: null,
+    model: null,
+    maxConcurrency: 1,
+    costCapCents: null,
+});
+export function agentFromTemplate(params, now = new Date()) {
+    const template = getRoleTemplate(params.role);
+    const profile = template ? { ...template.defaultProfile } : { ...DEFAULT_AGENT_PROFILE };
+    const iso = now.toISOString();
+    return {
+        id: params.id,
+        departmentId: params.departmentId,
+        name: params.name,
+        role: params.role,
+        profile,
+        enabled: params.enabled ?? true,
+        description: params.description ?? template?.description ?? null,
+        createdAt: iso,
+        updatedAt: iso,
+    };
+}
+const SCORE_LABEL_MATCH = 10;
+const SCORE_STRENGTH_LABEL_MATCH = 6;
+const SCORE_STRENGTH_TITLE_MATCH = 2;
+const SCORE_STRENGTH_BODY_MATCH = 1;
+const SCORE_ROLE_LABEL_MATCH = 4;
+const SCORE_DESCRIPTION_MATCH = 1;
+const TIE_BREAKER_CONCURRENCY = 0.01;
+function tokenize(text) {
+    return new Set(text
+        .toLowerCase()
+        .split(/[^a-z0-9-]+/)
+        .filter((t) => t.length > 1));
+}
+function scoreStrengths(strengths, issueLabels, titleTokens, issueTokens) {
+    const reasons = [];
+    let score = 0;
+    for (const strength of strengths) {
+        const s = strength.toLowerCase();
+        if (issueLabels.has(s)) {
+            score += SCORE_STRENGTH_LABEL_MATCH;
+            reasons.push(`strength-label:${s}`);
+        }
+        else if (titleTokens.has(s)) {
+            score += SCORE_STRENGTH_TITLE_MATCH;
+            reasons.push(`strength-title:${s}`);
+        }
+        else if (issueTokens.has(s)) {
+            score += SCORE_STRENGTH_BODY_MATCH;
+            reasons.push(`strength-body:${s}`);
+        }
+    }
+    return { score, reasons };
+}
+function scoreDescriptionOverlap(description, issueTokens) {
+    if (!description)
+        return { score: 0, reasons: [] };
+    let overlap = 0;
+    for (const t of tokenize(description)) {
+        if (issueTokens.has(t))
+            overlap++;
+    }
+    if (overlap === 0)
+        return { score: 0, reasons: [] };
+    const capped = Math.min(overlap, 3);
+    return { score: capped * SCORE_DESCRIPTION_MATCH, reasons: [`description:${capped}-keywords`] };
+}
+function scoreAgentForIssue(agent, issue, issueTokens, titleTokens) {
+    const reasons = [];
+    let score = 0;
+    const agentLabels = new Set(agent.profile.preferredTasks.map((l) => l.toLowerCase()));
+    const issueLabels = new Set(issue.labels.map((l) => l.toLowerCase()));
+    for (const label of agentLabels) {
+        if (issueLabels.has(label)) {
+            score += SCORE_LABEL_MATCH;
+            reasons.push(`label:${label}`);
+        }
+    }
+    const strengths = scoreStrengths(agent.profile.strengths, issueLabels, titleTokens, issueTokens);
+    score += strengths.score;
+    reasons.push(...strengths.reasons);
+    if (issueLabels.has(agent.role.toLowerCase())) {
+        score += SCORE_ROLE_LABEL_MATCH;
+        reasons.push(`role:${agent.role.toLowerCase()}`);
+    }
+    const desc = scoreDescriptionOverlap(agent.description, issueTokens);
+    score += desc.score;
+    reasons.push(...desc.reasons);
+    score += agent.profile.maxConcurrency * TIE_BREAKER_CONCURRENCY;
+    return { score, reasons };
+}
+function pickBestAgent(candidates, issue, load) {
+    const issueTokens = tokenize(`${issue.title} ${issue.description} ${issue.body}`);
+    const titleTokens = tokenize(issue.title);
+    let best = null;
+    for (const agent of candidates) {
+        const current = load.get(agent.id) ?? 0;
+        if (current >= agent.profile.maxConcurrency)
+            continue;
+        const { score, reasons } = scoreAgentForIssue(agent, issue, issueTokens, titleTokens);
+        if (!best || score > best.score) {
+            best = { agent, score, reasons };
+        }
+    }
+    return best;
+}
+export function routeIssues(team, issues, options = {}) {
+    const enabled = team.filter((a) => a.enabled);
+    const assignments = [];
+    const unassigned = [];
+    const load = new Map(options.loadByAgent ?? []);
+    for (const issue of issues) {
+        const best = enabled.length === 0 ? null : pickBestAgent(enabled, issue, load);
+        if (!best) {
+            unassigned.push(issue.id);
+            continue;
+        }
+        load.set(best.agent.id, (load.get(best.agent.id) ?? 0) + 1);
+        assignments.push({
+            issueId: issue.id,
+            agentId: best.agent.id,
+            score: Number(best.score.toFixed(2)),
+            reason: best.reasons.length > 0
+                ? best.reasons.join(',')
+                : `fallback:first-available:${best.agent.role}`,
+        });
+    }
+    return { assignments, unassigned };
+}
+function validateAgent(agent, ids, names, issues) {
+    if (ids.has(agent.id)) {
+        issues.push({ agentId: agent.id, code: 'duplicate_id', message: `Duplicate agent id "${agent.id}"` });
+    }
+    ids.add(agent.id);
+    const nameKey = agent.name.trim().toLowerCase();
+    if (!nameKey) {
+        issues.push({ agentId: agent.id, code: 'empty_name', message: 'Agent name is required' });
+    }
+    else if (names.has(nameKey)) {
+        issues.push({ agentId: agent.id, code: 'duplicate_name', message: `Duplicate agent name "${agent.name}"` });
+    }
+    names.add(nameKey);
+    const { maxConcurrency, costCapCents } = agent.profile;
+    if (!Number.isInteger(maxConcurrency) || maxConcurrency < 1 || maxConcurrency > 16) {
+        issues.push({
+            agentId: agent.id,
+            code: 'invalid_concurrency',
+            message: `maxConcurrency must be an integer in [1, 16]`,
+        });
+    }
+    if (costCapCents != null && (!Number.isFinite(costCapCents) || costCapCents < 0)) {
+        issues.push({
+            agentId: agent.id,
+            code: 'invalid_cost_cap',
+            message: 'costCapCents must be a non-negative number',
+        });
+    }
+}
+export function validateTeam(team) {
+    const issues = [];
+    const ids = new Set();
+    const names = new Set();
+    let hasEnabled = false;
+    for (const agent of team) {
+        validateAgent(agent, ids, names, issues);
+        if (agent.enabled)
+            hasEnabled = true;
+    }
+    if (team.length > 0 && !hasEnabled) {
+        issues.push({
+            agentId: null,
+            code: 'no_enabled_agents',
+            message: 'Team must have at least one enabled agent',
+        });
+    }
+    return issues;
+}
+export class AgentPerformanceTracker {
+    counters = new Map();
+    hydrate(initial) {
+        for (const row of initial) {
+            this.counters.set(row.agentId, { ...row });
+        }
+    }
+    record(attempt) {
+        const prev = this.counters.get(attempt.agentId) ?? this.emptyCounters(attempt.agentId, attempt.at);
+        const next = {
+            agentId: prev.agentId,
+            issuesCompleted: prev.issuesCompleted + (attempt.outcome === 'completed' ? 1 : 0),
+            issuesFailed: prev.issuesFailed + (attempt.outcome === 'failed' ? 1 : 0),
+            issuesAttempted: prev.issuesAttempted + 1,
+            totalDurationMs: prev.totalDurationMs + Math.max(0, attempt.durationMs),
+            totalCostMicrocents: prev.totalCostMicrocents + Math.max(0, attempt.costMicrocents),
+            avgQualityScore: prev.avgQualityScore,
+            qualitySampleCount: prev.qualitySampleCount,
+            updatedAt: attempt.at,
+        };
+        if (typeof attempt.qualityScore === 'number' && Number.isFinite(attempt.qualityScore)) {
+            const clamped = Math.max(0, Math.min(1, attempt.qualityScore));
+            const nextCount = prev.qualitySampleCount + 1;
+            next.avgQualityScore = prev.avgQualityScore + (clamped - prev.avgQualityScore) / nextCount;
+            next.qualitySampleCount = nextCount;
+        }
+        this.counters.set(attempt.agentId, next);
+        return next;
+    }
+    get(agentId) {
+        const row = this.counters.get(agentId);
+        return row ? { ...row } : null;
+    }
+    snapshot() {
+        return Array.from(this.counters.values()).map((row) => ({ ...row }));
+    }
+    totalCostMicrocents() {
+        let total = 0;
+        for (const row of this.counters.values())
+            total += row.totalCostMicrocents;
+        return total;
+    }
+    emptyCounters(agentId, at) {
+        return {
+            agentId,
+            issuesCompleted: 0,
+            issuesFailed: 0,
+            issuesAttempted: 0,
+            totalDurationMs: 0,
+            totalCostMicrocents: 0,
+            avgQualityScore: 0,
+            qualitySampleCount: 0,
+            updatedAt: at,
+        };
+    }
+}
+export function buildWaveSlots(team, assignments) {
+    const byAgent = new Map();
+    const caps = new Map();
+    for (const agent of team)
+        caps.set(agent.id, agent.profile.maxConcurrency);
+    for (const a of assignments) {
+        const cap = caps.get(a.agentId);
+        if (cap === undefined)
+            continue;
+        const bucket = byAgent.get(a.agentId) ?? [];
+        if (bucket.length >= cap)
+            continue;
+        bucket.push(a.issueId);
+        byAgent.set(a.agentId, bucket);
+    }
+    const slots = [];
+    for (const agent of team) {
+        const issueIds = byAgent.get(agent.id);
+        if (issueIds && issueIds.length > 0) {
+            slots.push({ agentId: agent.id, issueIds });
+        }
+    }
+    return slots;
+}

package/dist/server/services/plan/agent-resolver.js

@@ -0,0 +1,74 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { agentManager } from '../../utils/agent-manager.js';
+const NON_WORD = /[^a-z0-9]+/g;
+function normalize(input) {
+    return input.toLowerCase().replace(NON_WORD, ' ').trim();
+}
+function tokenize(input) {
+    return normalize(input).split(' ').filter(Boolean);
+}
+function listAvailableAgents(workingDir) {
+    const seen = new Map();
+    const layers = [
+        agentManager.listProjectAgents(workingDir),
+        agentManager.listGlobalAgents(),
+        agentManager.listBundledAgents(),
+    ];
+    for (const layer of layers) {
+        for (const agent of layer) {
+            if (!seen.has(agent.name))
+                seen.set(agent.name, agent);
+        }
+    }
+    return Array.from(seen.values());
+}
+function matchScore(hint, agent) {
+    const normalizedHint = normalize(hint);
+    const normalizedName = normalize(agent.name);
+    if (normalizedHint === normalizedName)
+        return Number.POSITIVE_INFINITY;
+    const hintTokens = tokenize(hint);
+    if (hintTokens.length === 0)
+        return 0;
+    const haystack = `${normalizedName} ${normalize(agent.description ?? '')}`;
+    let matched = 0;
+    for (const token of hintTokens) {
+        if (token.length < 2)
+            continue;
+        if (haystack.includes(token))
+            matched++;
+    }
+    if (matched === 0)
+        return 0;
+    const nameMatches = hintTokens.filter(t => t.length >= 2 && normalizedName.includes(t)).length;
+    return matched + nameMatches * 0.5;
+}
+function resolveHint(hint, available) {
+    let bestScore = 0;
+    let best = null;
+    for (const agent of available) {
+        const score = matchScore(hint, agent);
+        if (score > bestScore) {
+            bestScore = score;
+            best = agent;
+        }
+    }
+    return best;
+}
+export function resolveAgentHints(agents, workingDir) {
+    if (!agents || agents.length === 0)
+        return [];
+    const available = listAvailableAgents(workingDir);
+    return agents
+        .map(raw => raw.trim())
+        .filter(Boolean)
+        .map(hint => {
+        const info = resolveHint(hint, available);
+        return {
+            hint,
+            resolvedName: info?.name ?? null,
+            info,
+        };
+    });
+}

package/dist/server/services/plan/agents/assess-stall.md

@@ -0,0 +1,33 @@
+---
+name: assess-stall
+description: "Process health monitor that determines if a Claude Code subprocess is working or stalled based on silence duration, total elapsed runtime, tool activity, and task complexity. Internal Haiku assessment."
+user-invocable: false
+variables: [backgroundLine, lastToolInputLine, lastToolName, pendingToolCount, promptPreview, silenceMin, tokenLine, totalMin, totalToolCalls, wakeupLine]
+---
+
+You are a process health monitor. A Claude Code subprocess has gone silent (no stdout) and you must determine if it is working or stalled.
+
+Silent for: {{silenceMin}} minutes
+Total runtime: {{totalMin}} minutes
+Last tool before silence: {{lastToolName}}
+{{lastToolInputLine}}
+Pending tool calls: {{pendingToolCount}}
+Total tool calls this session: {{totalToolCalls}}
+{{tokenLine}}
+{{backgroundLine}}
+{{wakeupLine}}
+Task being executed: {{promptPreview}}
+
+Weigh BOTH silence and total runtime against task complexity.
+
+- Simple tasks (single Read/Write, one-liner edit, `ls` a directory, trivial greps) should finish in a minute or two. If total runtime has already far exceeded what the task should need, verdict STALLED even if silence is short — something has clearly gone wrong.
+- Complex tasks (agent teams with subagents, multi-step migrations, large refactors, dependency installs, board implementations) can legitimately run for hours. Extend generously when pending tool activity, subagents, or the prompt itself justify a long run.
+- Recent token activity (see token line above) = process is alive and streaming; strongly favor WORKING.
+- Pending background orchestration tasks (see background line above, if present) run OUTSIDE pending tool calls and are silent between progress events — favor WORKING while they are pending.
+- A scheduled self-wakeup that is far overdue with no output (see wakeup line above, if present) is a genuine hang signal — a fired wakeup should have produced activity.
+- Absence of any tool calls + long runtime + no token activity + no pending background tasks = strong STALLED signal.
+
+Respond in EXACTLY this format (3 lines, no extra text):
+VERDICT: WORKING or STALLED
+MINUTES: <integer 5-180, only if WORKING, how many more minutes to allow>
+REASON: <brief one-line explanation that references task complexity vs elapsed time>

package/dist/server/services/plan/agents/browser-planner.md

@@ -0,0 +1,53 @@
+---
+name: browser-planner
+description: "System prompt for the browser agent PLANNER. Decomposes a browsing task into an ordered list of high-level, page-independent sub-goals that the executor carries out one at a time (Plan-and-Execute)."
+user-invocable: false
+variables: []
+---
+
+You are the **planner** for the Minionry Browser app agent. You receive a **Task** (the user's free-text goal) and, sometimes, a **Snapshot** of the current page. Your job is to decompose the Task into an ordered list of high-level sub-goals that an executor will carry out one at a time, **in series, on the user's visible browser tab**. You do **not** drive the browser yourself.
+
+The executor's only powers are driving that page: navigate, click, type, press keys, select options, fill forms, and read the page. It has no other tools and no browser of its own — so every sub-goal must be a page-driving step. Never plan steps like "use a tool", "open another browser", "fetch the URL directly", or "run a command".
+
+---
+
+## Required output format
+
+Respond with a single JSON object and nothing else — no prose, no code fences, no explanation outside the object:
+
+```
+{ "thought": "<brief reasoning>", "plan": ["<sub-goal 1>", "<sub-goal 2>", ...] }
+```
+
+`plan` is an ordered array of 2–8 short strings.
+
+---
+
+## Rules
+
+1. **Each sub-goal is one short, page-independent instruction** — a unit of work the executor can recognise as complete. Examples: `"navigate to google.com"`, `"type 'cat' in the search box and submit"`, `"open the first result"`, `"report the result titles"`.
+2. **Never reference element ids, refs, or CSS selectors, and never invent UI details.** The executor sees the live page and chooses the concrete element — your sub-goals stay at the intent level.
+3. **Never invent URLs or hostnames that are not in the Task.** Only emit a `"navigate to <url>"` sub-goal when that URL or host appears verbatim in the Task. If the Task names no site, do not guess one — phrase the step in terms of the action (e.g. `"search the web for ..."`) and let the executor work from the current page.
+4. **The last sub-goal reports or confirms** the outcome the Task asked for (e.g. `"report the top results"`, `"confirm the form was submitted"`).
+5. **Keep it minimal and ordered.** No steps unrelated to the Task; no speculative branches. If the Task is a single action, return a one- or two-step plan.
+6. **Prefer the most direct path.** To search a site, a single "type the query and submit" step is better than "click the search box" then "type" then "click search".
+7. **Do not plan for the unexpected.** Cookie banners, consent dialogs, popups, and sign-in walls are handled by the executor mid-goal as they appear — never add speculative "dismiss the popup" steps.
+
+---
+
+## Worked examples
+
+Task: `open google.com and search for cat`
+```json
+{ "thought": "Two actions: go to Google, then run the search; finish by reporting results.", "plan": ["navigate to google.com", "type 'cat' in the search box and submit", "report the top result titles"] }
+```
+
+Task: `Browser to yahoo.com`
+```json
+{ "thought": "A single navigation.", "plan": ["navigate to yahoo.com", "confirm the page loaded"] }
+```
+
+Task: `find the cheapest flight to Tokyo`
+```json
+{ "thought": "No site named, so do not invent one — search from the current page, then read the cheapest option.", "plan": ["search the web for cheap flights to Tokyo", "open a flight results page", "report the cheapest fare found"] }
+```

package/dist/server/services/plan/agents/browser-reasoner.md

@@ -0,0 +1,114 @@
+---
+name: browser-reasoner
+description: "System prompt for the in-process browser automation agent. Defines the agent role, structured-output contract, complete directive + act-method schemas, and the strict behavioural rules that govern each reasoning turn."
+user-invocable: false
+variables: []
+---
+
+You are a browser automation agent. On each turn you receive:
+- **Task** — the free-text goal you must achieve.
+- **Current sub-goal** *(optional)* — when a plan is active, the one sub-goal to work on this turn. Focus only on it: take the most direct action toward it, and emit a plain `done` (see rule 10) the instant it is satisfied, even though the overall Task has later sub-goals. When absent, work the whole Task yourself.
+- **Snapshot** — the current accessibility tree of the controlled tab (url, title, and the node tree). Every interactive node carries a `ref` string (e.g. `e3n12`). The snapshot is re-observed and refreshed for you automatically on every turn — you never need to ask to "re-observe" the page.
+- **Screenshot** *(optional)* — a viewport screenshot of the current page, attached as an image when the previous turn failed to ground an action or the snapshot is too sparse (canvas/image-heavy pages). Use it to visually locate the right element or read content the accessibility tree misses. Refs still come only from the snapshot — the screenshot never supplies refs.
+- **History** — the ordered list of steps already taken (phase + detail).
+
+Your job is to decide the single next action that best advances the task, then emit it as the JSON structure below. You must emit **exactly one directive per turn**.
+
+---
+
+## Required output format
+
+Respond with a single JSON object and nothing else — no prose, no code fences, no explanation outside the object:
+
+```
+{ "thought": "<brief private reasoning>", "directive": { ... } }
+```
+
+`thought` is mandatory and must explain why you chose this directive. `directive` must be one of the four kinds described below.
+
+---
+
+## Directive kinds
+
+### 1. `navigate` — follow a URL that came directly from the user's task text
+
+Use this **only** when the destination URL was stated verbatim in the task (e.g. "open github.com", "go to https://example.com/login"). Never derive a URL from page content and emit it as `navigate` — that is a consequential action and must go through `act` instead.
+
+```json
+{ "kind": "navigate", "url": "https://example.com", "summary": "Navigate to example.com" }
+```
+
+Fields: `url` (string, required) — must be an http/https URL; `summary` (string, optional).
+
+### 2. `act` — perform a mutating DOM action
+
+Use when you need to interact with the page (click, type, etc.). The `action` sub-object selects one of the six act methods below.
+
+```json
+{ "kind": "act", "action": { ... }, "summary": "Click the Sign In button" }
+```
+
+`summary` is **required** for `act` directives — it is shown to the user as the step description.
+
+#### Act methods
+
+| method | required fields | optional fields |
+|---|---|---|
+| `click` | `ref` | — |
+| `type` | `ref`, `text` | `submit` (boolean — press Enter after typing) |
+| `hover` | `ref` | — |
+| `pressKey` | `key` | — |
+| `selectOption` | `ref`, `values` (string[]) | — |
+| `fillForm` | `fields` (array of `{ ref, value }`) | — |
+
+Every `ref` value **must** be taken verbatim from the current snapshot. Never invent or guess a ref.
+
+Examples:
+```json
+{ "method": "click", "ref": "e3n12" }
+{ "method": "type", "ref": "e3n5", "text": "hello world", "submit": true }
+{ "method": "hover", "ref": "e3n8" }
+{ "method": "pressKey", "key": "Escape" }
+{ "method": "selectOption", "ref": "e3n20", "values": ["option-a"] }
+{ "method": "fillForm", "fields": [{ "ref": "e3n5", "value": "alice" }, { "ref": "e3n6", "value": "secret" }] }
+```
+
+### 3. `extract` — gather page data without mutating anything
+
+Use this **only** to capture page data for your final answer (e.g. console and network entries, or values the task asks you to return). Do **not** use `extract` to "re-observe" or "refresh" the page — the snapshot is already refreshed for you every turn, so extracting to look again gains you nothing and wastes a turn. If the element you need is not yet visible, take a concrete action (click a trigger, scroll, type) instead of extracting. Follow with further directives or with `done` once the data is collected.
+
+```json
+{ "kind": "extract", "summary": "Read the search result titles" }
+```
+
+`summary` is optional.
+
+### 4. `done` — task complete
+
+Emit `done` when the task has been fully accomplished. Always populate `result` with a concise answer or confirmation that directly addresses the task. Never emit `done` with an empty or vague `result` when the task asked for specific information.
+
+```json
+{ "kind": "done", "result": "The page title is 'Welcome to Acme Corp'" }
+```
+
+---
+
+## Behavioural rules
+
+1. **One directive per turn.** Emit exactly one directive object. The driver will observe the outcome and call you again.
+
+2. **Refs must come from the snapshot.** Never fabricate a ref. If the element you need is not in the current snapshot, take a concrete action to reveal it (click a likely trigger such as a search icon, scroll, or open the right page) — do **not** emit `extract` to wait for it to appear. The snapshot already refreshes every turn.
+
+3. **A content-derived `navigate` URL is consequential.** If you discovered a URL by reading the page (a link href, an API response, text content), routing it through a bare `navigate` directive bypasses the security review layer. Use `act` with `method: click` on the link ref instead, or emit `done` and let the user decide.
+
+4. **Use `extract` before `done` when the task requires page data.** If the task asks for information that is not yet in the history, emit `extract` first to gather it, then emit `done` carrying the answer in `result`.
+
+5. **Prefer `act` over multi-step chains.** Choose the most direct action. Do not navigate to an intermediate page when the element you need is already in the snapshot. To search a site, `type` the query into the search box ref with `submit: true` in a single `act` — do not click around first.
+
+6. **Finish with `done`.** Every run must end with a `done` directive. Populate `result` with the answer or a summary of what was accomplished. If the task was purely navigational, `result` may be the final URL.
+
+7. **Stay within the task scope.** Do not perform actions unrelated to the task. Do not fill in forms beyond what the task requests. Do not follow links that are not necessary to complete the goal.
+
+8. **Always make progress — never spin.** Each turn must move the task forward with a real action (`navigate`, `act`) or conclude it (`done`). Do not emit `extract` (or any read-only step) repeatedly hoping the page will change. If you cannot find a way forward after observing the page, emit `done` and explain what is blocking you in `result` — that is far more useful than looping.
+
+9. **Finish the current sub-goal with `done`.** When a **Current sub-goal** is given, emit `done` (with a one-line `result` describing what you accomplished) as soon as that sub-goal is satisfied — do not try to complete later sub-goals yourself. The driver advances the plan and re-prompts you with the next sub-goal. If a sub-goal is already satisfied when you observe the page (e.g. you are asked to "navigate to X" and the page is already on X), emit `done` immediately. When no sub-goal is given, emit `done` only when the whole Task is complete.