opencode-dux 1.0.0

package/src/hooks/context-pressure-reminder/index.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, test } from 'bun:test';
+import type { TuiSnapshot } from '../../tui-state';
+import { SLIM_INTERNAL_INITIATOR_MARKER } from '../../utils';
+import {
+  applyContextPressureReminder,
+  CONTEXT_PRESSURE_HEADING,
+} from './index';
+
+function snapshotWithOrchestratorUsage(
+  sessionID: string,
+  contextUsed: number,
+  contextLimit: number,
+): TuiSnapshot {
+  return {
+    version: 6,
+    updatedAt: Date.now(),
+    sessions: {
+      bundle: {
+        rootSessionId: 'bundle',
+        lastActivityAt: Date.now(),
+        tree: {
+          [sessionID]: {
+            title: 'orch',
+            agent: 'orchestrator',
+            model: 'anthropic/claude-sonnet',
+            childIds: [],
+            status: 'idle',
+            usage: {
+              contextUsed,
+              contextLimit,
+              contextPct: (contextUsed / contextLimit) * 100,
+              input: 0,
+              output: 0,
+              reasoning: 0,
+              cacheRead: 0,
+              cacheWrite: 0,
+              updatedAt: Date.now(),
+            },
+          },
+        },
+        orchestrationUsageLastSeen: {},
+      },
+    },
+    subscriptionUsage: {},
+    activeSubscriptionByProvider: {},
+  };
+}
+
+describe('applyContextPressureReminder', () => {
+  test('appends reminder when context is at threshold', () => {
+    const sid = 'main-orchestrator';
+    const snap = snapshotWithOrchestratorUsage(sid, 220_000, 262_144);
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'orchestrator', sessionID: sid },
+        parts: [{ type: 'text' as const, text: 'next step' }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: true,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toContain(CONTEXT_PRESSURE_HEADING);
+    expect(messages[0].parts[0].text).toContain('/compact');
+    expect(messages[0].parts[0].text).toMatch(/84%/);
+  });
+
+  test('skips when below threshold', () => {
+    const sid = 's1';
+    const snap = snapshotWithOrchestratorUsage(sid, 190_000, 262_144);
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'orchestrator', sessionID: sid },
+        parts: [{ type: 'text' as const, text: 'ok' }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: true,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toBe('ok');
+  });
+
+  test('respects enabled false', () => {
+    const sid = 's2';
+    const snap = snapshotWithOrchestratorUsage(sid, 260_000, 262_144);
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'orchestrator', sessionID: sid },
+        parts: [{ type: 'text' as const, text: 'x' }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: false,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toBe('x');
+  });
+
+  test('skips non-orchestrator last user message', () => {
+    const sid = 's3';
+    const snap = snapshotWithOrchestratorUsage(sid, 260_000, 262_144);
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'explorer', sessionID: sid },
+        parts: [{ type: 'text' as const, text: 'find X' }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: true,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toBe('find X');
+  });
+
+  test('skips without sessionID', () => {
+    const sid = 's4';
+    const snap = snapshotWithOrchestratorUsage(sid, 260_000, 262_144);
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'orchestrator' },
+        parts: [{ type: 'text' as const, text: 'y' }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: true,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toBe('y');
+  });
+
+  test('does not mutate internal notification turns', () => {
+    const sid = 's5';
+    const snap = snapshotWithOrchestratorUsage(sid, 260_000, 262_144);
+    const text = `[Background task "x" completed]\n${SLIM_INTERNAL_INITIATOR_MARKER}`;
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'orchestrator', sessionID: sid },
+        parts: [{ type: 'text' as const, text }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: true,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toBe(text);
+  });
+
+  test('does not duplicate reminder', () => {
+    const sid = 's6';
+    const snap = snapshotWithOrchestratorUsage(sid, 260_000, 262_144);
+    const prior = `hello\n\n---\n\n${CONTEXT_PRESSURE_HEADING}\n\nstub`;
+    const messages = [
+      {
+        info: { role: 'user' as const, agent: 'orchestrator', sessionID: sid },
+        parts: [{ type: 'text' as const, text: prior }],
+      },
+    ];
+
+    applyContextPressureReminder(messages, snap, {
+      enabled: true,
+      warnThresholdPct: 75,
+    });
+
+    expect(messages[0].parts[0].text).toBe(prior);
+  });
+});

package/src/hooks/context-pressure-reminder/index.ts

@@ -0,0 +1,137 @@
+/**
+ * Injects a /compact heads-up into the orchestrator's latest user turn when
+ * sidebar-style context telemetry shows the session is near the model window.
+ */
+import {
+  deriveSessionContextPct,
+  mergedSessionUsage,
+  readTuiSnapshot,
+  type TuiSnapshot,
+} from '../../tui-state';
+import { SLIM_INTERNAL_INITIATOR_MARKER } from '../../utils';
+
+/** Marker in the injected block; keep in sync with orchestrator prompt guidance. */
+export const CONTEXT_PRESSURE_HEADING = '### Context budget (plugin telemetry)';
+
+interface MessageInfo {
+  role: string;
+  agent?: string;
+  sessionID?: string;
+}
+
+interface MessagePart {
+  type: string;
+  text?: string;
+  [key: string]: unknown;
+}
+
+interface MessageWithParts {
+  info: MessageInfo;
+  parts: MessagePart[];
+}
+
+export interface ContextPressureReminderOptions {
+  enabled: boolean;
+  warnThresholdPct: number;
+}
+
+function buildReminderText(
+  roundedPct: number,
+  contextUsed: number,
+  contextLimit: number,
+): string {
+  return [
+    CONTEXT_PRESSURE_HEADING,
+    '',
+    `Telemetry for this orchestrator session is about **${roundedPct}%** full ` +
+      `(${contextUsed.toLocaleString('en-US')} / ${contextLimit.toLocaleString('en-US')} tokens in the model context window). ` +
+      'Further turns may fail with no context left.',
+    '',
+    'Before starting heavy new delegation or large tool payloads:',
+    '1. Ask the user to run **`/compact`** (or continue the next phase in a **new session**).',
+    '2. If a blocking delegation is mid-flight, finish the smallest safe step first, then compact.',
+    '',
+    'Do not assume unlimited context remains.',
+  ].join('\n');
+}
+
+/** @internal Exported for tests */
+export function applyContextPressureReminder(
+  messages: MessageWithParts[],
+  snapshot: TuiSnapshot,
+  options: ContextPressureReminderOptions,
+): void {
+  if (!options.enabled || messages.length === 0) {
+    return;
+  }
+
+  let lastUserMessageIndex = -1;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].info.role === 'user') {
+      lastUserMessageIndex = i;
+      break;
+    }
+  }
+
+  if (lastUserMessageIndex === -1) {
+    return;
+  }
+
+  const lastUserMessage = messages[lastUserMessageIndex];
+  const agent = lastUserMessage.info.agent;
+  if (agent && agent !== 'orchestrator') {
+    return;
+  }
+
+  const sessionID = lastUserMessage.info.sessionID;
+  if (!sessionID) {
+    return;
+  }
+
+  const textPartIndex = lastUserMessage.parts.findIndex(
+    (p) => p.type === 'text' && p.text !== undefined,
+  );
+
+  if (textPartIndex === -1) {
+    return;
+  }
+
+  const originalText = lastUserMessage.parts[textPartIndex].text ?? '';
+  if (originalText.includes(SLIM_INTERNAL_INITIATOR_MARKER)) {
+    return;
+  }
+  if (originalText.includes(CONTEXT_PRESSURE_HEADING)) {
+    return;
+  }
+
+  const usageBySession = mergedSessionUsage(snapshot);
+  const usage = usageBySession[sessionID];
+  const limit = usage?.contextLimit ?? 0;
+  if (!(limit > 0)) {
+    return;
+  }
+
+  const used = usage?.contextUsed ?? 0;
+  const roundedPct = Math.round(deriveSessionContextPct(used, limit));
+
+  if (roundedPct < options.warnThresholdPct) {
+    return;
+  }
+
+  const block = buildReminderText(roundedPct, used, limit);
+  lastUserMessage.parts[textPartIndex].text =
+    `${originalText}\n\n---\n\n${block}`;
+}
+
+export function createContextPressureReminderHook(
+  options: ContextPressureReminderOptions,
+) {
+  return {
+    'experimental.chat.messages.transform': async (
+      _input: Record<string, never>,
+      output: { messages: MessageWithParts[] },
+    ): Promise<void> => {
+      applyContextPressureReminder(output.messages, readTuiSnapshot(), options);
+    },
+  };
+}

package/src/hooks/delegate-task-retry/guidance.ts

@@ -0,0 +1,41 @@
+import { DELEGATE_TASK_ERROR_PATTERNS, type DetectedError } from './patterns';
+
+function extractAvailableList(output: string): string | null {
+  const match = output.match(/Allowed agents:\s*(.+)$/m);
+  if (match) return match[1].trim();
+
+  const available = output.match(/Available[^:]*:\s*(.+)$/m);
+  if (available) return available[1].trim();
+
+  return null;
+}
+
+export function buildRetryGuidance(errorInfo: DetectedError): string {
+  const pattern = DELEGATE_TASK_ERROR_PATTERNS.find(
+    (p) => p.errorType === errorInfo.errorType,
+  );
+
+  if (!pattern) {
+    return '\n[delegate-task retry] Fix parameters and retry with corrected arguments.';
+  }
+
+  const available = extractAvailableList(errorInfo.originalOutput);
+
+  const lines = [
+    '',
+    '[delegate-task retry suggestion]',
+    `Error type: ${errorInfo.errorType}`,
+    `Fix: ${pattern.fixHint}`,
+  ];
+
+  if (available) {
+    lines.push(`Available: ${available}`);
+  }
+
+  lines.push(
+    'Retry now with corrected parameters. Example:',
+    'task(description="...", prompt="...", category="unspecified-low", run_in_background=false, load_skills=[])',
+  );
+
+  return lines.join('\n');
+}

package/src/hooks/delegate-task-retry/hook.ts

@@ -0,0 +1,23 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import { buildRetryGuidance } from './guidance';
+import { detectDelegateTaskError } from './patterns';
+
+export function createDelegateTaskRetryHook(_ctx: PluginInput) {
+  return {
+    'tool.execute.after': async (
+      input: { tool: string },
+      output: { output: unknown },
+    ): Promise<void> => {
+      const toolName = input.tool.toLowerCase();
+      const isDelegateTool = toolName === 'task';
+      if (!isDelegateTool) return;
+
+      if (typeof output.output !== 'string') return;
+
+      const detected = detectDelegateTaskError(output.output);
+      if (!detected) return;
+
+      output.output += `\n${buildRetryGuidance(detected)}`;
+    },
+  };
+}

package/src/hooks/delegate-task-retry/index.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { createDelegateTaskRetryHook } from './hook';
+
+describe('delegate-task-retry hook', () => {
+  test('appends guidance for task argument errors', async () => {
+    const hook = createDelegateTaskRetryHook({} as never);
+    const output = {
+      output:
+        '[ERROR] Invalid arguments: Must provide either category or subagent_type. Available categories: quick, unspecified-low',
+    };
+
+    await hook['tool.execute.after']({ tool: 'task' }, output);
+
+    expect(output.output).toContain('[delegate-task retry suggestion]');
+    expect(output.output).toContain('missing_category_or_agent');
+  });
+
+  test('appends guidance for task agent allowlist errors', async () => {
+    const hook = createDelegateTaskRetryHook({} as never);
+    const output = {
+      output: "Agent 'oracle' is not allowed. Allowed agents: explorer, fixer",
+    };
+
+    await hook['tool.execute.after']({ tool: 'task' }, output);
+
+    expect(output.output).toContain('background_agent_not_allowed');
+    expect(output.output).toContain('Available: explorer, fixer');
+  });
+
+  test('does nothing for unrelated tool output', async () => {
+    const hook = createDelegateTaskRetryHook({} as never);
+    const output = { output: 'all good' };
+
+    await hook['tool.execute.after']({ tool: 'read' }, output);
+
+    expect(output.output).toBe('all good');
+  });
+});

package/src/hooks/delegate-task-retry/index.ts

@@ -0,0 +1,7 @@
+export { buildRetryGuidance } from './guidance';
+export { createDelegateTaskRetryHook } from './hook';
+export type { DelegateTaskErrorPattern, DetectedError } from './patterns';
+export {
+  DELEGATE_TASK_ERROR_PATTERNS,
+  detectDelegateTaskError,
+} from './patterns';

package/src/hooks/delegate-task-retry/patterns.ts

@@ -0,0 +1,79 @@
+export interface DelegateTaskErrorPattern {
+  pattern: string;
+  errorType: string;
+  fixHint: string;
+}
+
+export const DELEGATE_TASK_ERROR_PATTERNS: DelegateTaskErrorPattern[] = [
+  {
+    pattern: 'run_in_background',
+    errorType: 'missing_run_in_background',
+    fixHint:
+      'Add run_in_background=false (delegation) or run_in_background=true (parallel exploration).',
+  },
+  {
+    pattern: 'load_skills',
+    errorType: 'missing_load_skills',
+    fixHint: 'Add load_skills=[] (empty array when no skill is needed).',
+  },
+  {
+    pattern: 'category OR subagent_type',
+    errorType: 'mutual_exclusion',
+    fixHint:
+      'Provide only one: category (e.g., "unspecified-low") OR subagent_type (e.g., "explorer").',
+  },
+  {
+    pattern: 'Must provide either category or subagent_type',
+    errorType: 'missing_category_or_agent',
+    fixHint:
+      'Add either category="unspecified-low" or subagent_type="explorer".',
+  },
+  {
+    pattern: 'Unknown category',
+    errorType: 'unknown_category',
+    fixHint: 'Use a valid category listed in the error output.',
+  },
+  {
+    pattern: 'Unknown agent',
+    errorType: 'unknown_agent',
+    fixHint: 'Use a valid agent name from the available list.',
+  },
+  {
+    pattern: 'Skills not found',
+    errorType: 'unknown_skills',
+    fixHint: 'Use valid skill names listed in the error output.',
+  },
+  {
+    pattern: 'is not allowed. Allowed agents:',
+    errorType: 'background_agent_not_allowed',
+    fixHint:
+      'Use one of the allowed agents shown in the error or delegate from a parent agent that can call this subagent.',
+  },
+];
+
+export interface DetectedError {
+  errorType: string;
+  originalOutput: string;
+}
+
+export function detectDelegateTaskError(output: string): DetectedError | null {
+  if (!output || typeof output !== 'string') return null;
+
+  const hasErrorSignal =
+    output.includes('[ERROR]') ||
+    output.includes('Invalid arguments') ||
+    output.includes('is not allowed. Allowed agents:');
+
+  if (!hasErrorSignal) return null;
+
+  for (const pattern of DELEGATE_TASK_ERROR_PATTERNS) {
+    if (output.includes(pattern.pattern)) {
+      return {
+        errorType: pattern.errorType,
+        originalOutput: output,
+      };
+    }
+  }
+
+  return null;
+}