Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

14.7 KB
Raw Blame
// Code-agent delegation voice tools: dispatch an autonomous coding agent (runs
// in an isolated worktree, opens a PR) and check the status of in-flight
// dispatched tasks. Heavy collaborators (cos.js, providers.js, apps.js) are
// imported lazily inside execute() to keep this module's load graph light.

import { getVoiceConfig } from '../config.js';
import { isCallerModeEligible } from '../../../lib/callerModePolicy.js';

// Code-agent delegation — software-engineering requests and explicit
// "have <agent> …" phrasing. The ambiguous verbs (implement/debug/rewrite/
// patch) require a following code-domain object within ~40 chars, so
// "implement my morning routine" / "debug my relationship" / "add a feature
// to my calendar" do NOT match; `refactor` stays standalone (rarely non-code
// in speech). A false positive only OFFERS the tool to the LLM (which still
// has to choose it), and the tool is a no-op unless codeAgent.enabled
// (pipeline.js strips it from the spec list when off).
export const CODE_INTENT_RE = /\b(?:have (?:claude|codex|antigravity|gemini|the agent|an agent)\b|dispatch (?:a |an )?(?:coding |code )?agent|spin up an agent|code (?:it )?up|open a pr|pull request|refactor|(?:implement|debug|rewrite|patch)\b[^.!?\n]{0,40}\b(?:bug|tests?|function|method|build|lint|type ?error|error|code|file|module|endpoint|route|component|class|api|schema|migration|script|flag|regression|handler|parser|service|hook|query|registry|config)\b|fix (?:the |a |an |my )?(?:bug|test|tests|failing|function|method|build|lint|type|error|code|file|module|endpoint|route|component)|write (?:a |the |some )?(?:unit |integration )?tests?|add (?:a |an |the )?(?:flag|function|method|endpoint|route|test|migration)\b|(?:how(?:'s| is| are)?|status of|progress on|what(?:'s| is)? happening (?:with|on)|where (?:are|is) (?:we|it|that|the))\b[^.!?\n]{0,40}\b(?:coding (?:task|agent|job)|code agent|dispatched (?:task|job|agent)|pull request|the agent|the pr|that pr|my pr|the task)\b|\bis (?:the |that |my )?(?:coding |code )?(?:agent|task) (?:still |yet )?(?:running|going|working|done|finished))/i;

export const CODE_TOOLS = [
  {
    name: 'dispatch_code_agent',
    hostControl: true,
    description:
      'Hand a software-engineering task to an autonomous coding agent that works in an isolated git worktree and opens a pull request for review. Use when the user asks you to write, fix, refactor, debug, or test CODE — e.g. "fix the failing test in X", "add a --dry-run flag to the backup script", "refactor the widget registry". Do NOT use for capturing notes/ideas (that is brain_capture) or for clicking/navigating the UI. The work runs in the background and the user is told when it finishes — do not wait for it. State the task in the user\'s own words with enough detail to act on it. When the user names a managed app to work in ("…in BookLoom", "fix the bug in the finance tracker"), pass that name as `app`; omit `app` for tasks on PortOS itself. The coding agent and model come from the user\'s configured default; never put a provider or model in this call.',
    parameters: {
      type: 'object',
      properties: {
        task: {
          type: 'string',
          description: 'The coding task to perform, phrased as a clear, self-contained instruction (file/feature names, the desired outcome). The agent reads this verbatim as its prompt.',
        },
        app: {
          type: 'string',
          description: 'Optional managed-app target ("BookLoom", "finance tracker"). Server fuzzy-matches against the user\'s configured apps; omit to run against PortOS itself.',
        },
      },
      required: ['task'],
    },
    execute: async ({ task, app } = {}) => {
      const text = typeof task === 'string' ? task.trim() : '';
      if (!text) {
        return { ok: false, error: 'task is required', summary: "I didn't catch what you want the coding agent to do." };
      }
      const appPhrase = typeof app === 'string' ? app.trim() : '';

      // Backstop for the palette path — pipeline.js already strips this tool
      // from the LLM's spec list when codeAgent is disabled, but the command
      // palette dispatches by id regardless, so re-check here.
      const cfg = await getVoiceConfig();
      const codeAgent = cfg?.llm?.codeAgent || {};
      if (!codeAgent.enabled) {
        return { ok: false, error: 'code-agent disabled', summary: 'Coding-agent dispatch is off — turn it on under Settings, Voice, Coding agent.' };
      }

      // Reject an explicit-but-unknown app rather than silently falling
      // through to the PortOS workspace — that's the whole point of asking.
      let resolvedAppId = null;
      let resolvedAppName = null;
      if (appPhrase) {
        const { getActiveApps } = await import('../../apps.js');
        const { resolveAppByPhrase } = await import('../../../lib/appResolver.js');
        const apps = await getActiveApps().catch(() => []);
        const match = resolveAppByPhrase(appPhrase, apps);
        if (!match) {
          const names = (apps || []).map((a) => a?.name).filter(Boolean);
          const hint = names.length ? ` Try one of: ${names.slice(0, 4).join(', ')}.` : '';
          return {
            ok: false,
            error: `unknown app "${appPhrase}"`,
            summary: `I don't see a managed app called ${appPhrase}.${hint}`,
          };
        }
        resolvedAppId = match.id;
        resolvedAppName = match.name || match.id;
      }

      // Dynamic import: cos.js is a large module with its own import graph;
      // importing it lazily keeps tools.js load-time light and dodges any
      // cos → voice cycle.
      const { addTask, reviveBlockedTask } = await import('../../cosTaskStore.js');
      const { isRunning } = await import('../../cos.js');
      const provider = typeof codeAgent.provider === 'string' ? codeAgent.provider.trim() : '';
      const model = typeof codeAgent.model === 'string' ? codeAgent.model.trim() : '';

      // Resolve a code-capable provider. A coding agent must run a CLI/TUI
      // provider (Claude Code, Codex, Antigravity CLI, …); an API backend (LM Studio
      // / Ollama / OpenAI-compatible) can't, and the spawner would otherwise
      // fall through to the Claude CLI spawn config with a non-Claude model name
      // (buildCliSpawnConfig defaults to claude). Validate BOTH the inherited
      // system default AND an explicit pin — the Voice settings UI only lists
      // CLI/TUI providers for the code agent, but a hand-edited config can still
      // pin an API one. When the effective provider isn't code-capable,
      // substitute the first enabled CLI/TUI provider, or fail with actionable
      // copy if none exists. A pin that doesn't resolve to a known provider is
      // left as-is (the spawner surfaces the unknown-provider error).
      const { getActiveProvider, getAllProviders, getProviderById } = await import('../../providers.js');
      // Same named policy the CoS agent resolver and the fallback chain apply,
      // so "can this route run agent work?" has one answer across all three.
      const isCodeCapable = (p) => isCallerModeEligible(p, 'agent-harness');
      const candidate = provider
        ? await getProviderById(provider).catch(() => null)
        : await getActiveProvider().catch(() => null);
      const needsSwap = provider
        ? (candidate != null && !isCodeCapable(candidate)) // known pin that's API-only
        : !isCodeCapable(candidate);                        // default (incl. none) not capable
      let resolvedProvider = provider;
      let substituted = false;
      if (needsSwap) {
        const { providers = [] } = await getAllProviders().catch(() => ({ providers: [] }));
        const codeProvider = providers.find((p) => p?.enabled && isCodeCapable(p));
        if (!codeProvider) {
          return {
            ok: false,
            error: 'no code-capable provider',
            summary: "Your AI provider can't run a coding agent. Enable a CLI provider like Claude Code, Codex, or Antigravity under Settings, AI Providers, then try again.",
          };
        }
        resolvedProvider = codeProvider.id;
        substituted = true;
      }

      const created = await addTask({
        description: text,
        priority: 'HIGH',
        position: 'top',
        voiceDispatch: true,
        ...(resolvedAppId ? { app: resolvedAppId } : {}),
        // The promise of this tool (and the changelog / spoken copy) is
        // isolated work that opens a PR and never touches the user's working
        // tree. spawnAgentForTask only honors that when the task explicitly
        // opts in — without these flags it runs in the shared workspace and
        // auto-merges. Set both so the dispatched agent always works in a
        // worktree and surfaces a PR for review.
        useWorktree: true,
        openPR: true,
        // Pin the configured (or substituted code-capable) provider. Omitting
        // it lets the CoS spawner inherit the system default — only done when
        // that default is itself code-capable (see resolution above). A pinned
        // model belongs to a specific provider, so drop it when we substituted
        // a different provider than the (empty) configured one.
        ...(resolvedProvider ? { provider: resolvedProvider } : {}),
        ...(model && !substituted ? { model } : {}),
      }, 'user');

      // addTask auto-spawns user tasks, but only while the CoS runner is up.
      // isRunning() is a synchronous daemon-state check. Surface a stopped
      // runner on BOTH paths so a re-issue of an already-queued task isn't
      // falsely reassuring when nothing is actually running it.
      const running = isRunning();
      const stoppedNote = ' — but the Chief-of-Staff runner is stopped, so start it to run it';

      const appSuffix = resolvedAppName ? ` in ${resolvedAppName}` : '';

      if (created?.duplicate) {
        // A blocked twin means "already queued" would be a lie — it will never
        // run on its own. A repeated voice dispatch is an explicit retry, so
        // revive it with a fresh retry budget (#2614).
        if (created.status === 'blocked') {
          await reviveBlockedTask(created.id, {}, 'user');
          return {
            ok: true,
            taskId: created.id,
            revived: true,
            app: resolvedAppId,
            summary: `That coding task${appSuffix} previously failed and was blocked — I restarted it${running ? '.' : stoppedNote + '.'}`,
          };
        }
        return {
          ok: true,
          taskId: created.id,
          duplicate: true,
          app: resolvedAppId,
          summary: `That coding task${appSuffix} is already queued${running ? ', so I left it as is.' : `${stoppedNote}.`}`,
        };
      }

      const summary = running
        ? `Queued a coding task${appSuffix} — I'll let you know when it's done.`
        : `Queued the coding task${appSuffix}${stoppedNote}.`;
      return { ok: true, taskId: created?.id, running, app: resolvedAppId, summary };
    },
  },

  {
    name: 'code_agent_status',
    description:
      "Report the status of in-flight coding tasks the user dispatched by voice (via dispatch_code_agent). Use when the user asks how a coding agent / dispatched task is doing — e.g. \"how's that coding task going?\", \"is the agent still running?\", \"status of the PR\", \"what's happening with the refactor?\". Reads live agent state and reports phase + elapsed per running task. The completion announcement covers the done case proactively; this tool is for mid-task check-ins. Returns an empty-but-ok result when nothing is running — speak the summary verbatim.",
    parameters: {
      type: 'object',
      properties: {},
    },
    execute: async () => {
      const { loadState } = await import('../../cosState.js');
      const { getAllTasks } = await import('../../cosTaskStore.js');
      const { isTruthyMeta } = await import('../../agentState.js');

      const state = await loadState();
      const runningAgents = Object.values(state?.agents || {}).filter((a) => a?.status === 'running');
      if (runningAgents.length === 0) {
        return { ok: true, count: 0, agents: [], summary: 'No coding tasks are running right now.' };
      }

      // Read TASKS.md once and index by id, not getTaskById in a loop — that
      // re-reads both task files per call.
      const { user, cos } = await getAllTasks();
      const tasksById = new Map();
      for (const t of user.tasks || []) tasksById.set(t.id, t);
      for (const t of cos.tasks || []) tasksById.set(t.id, t);

      const matched = [];
      for (const agent of runningAgents) {
        if (!agent?.taskId) continue;
        const task = tasksById.get(agent.taskId);
        if (!task) continue;
        if (!isTruthyMeta(task.metadata?.voiceDispatch)) continue;
        const startedAt = agent.startedAt ? Date.parse(agent.startedAt) : NaN;
        const elapsedMs = Number.isFinite(startedAt) ? Math.max(0, Date.now() - startedAt) : null;
        matched.push({
          taskId: task.id,
          agentId: agent.id,
          description: (task.description || '').split('\n')[0].trim(),
          phase: agent.metadata?.phase || 'working',
          app: agent.metadata?.taskAppName || agent.metadata?.taskApp || null,
          elapsedMs,
        });
      }

      if (matched.length === 0) {
        return { ok: true, count: 0, agents: [], summary: 'No coding tasks are running right now.' };
      }

      const phaseText = (phase) => (phase === 'initializing' ? 'spinning up' : 'working');
      const elapsedSpoken = (ms) => {
        if (!Number.isFinite(ms) || ms < 60_000) return 'less than a minute';
        const mins = Math.floor(ms / 60_000);
        if (mins < 60) return `${mins} minute${mins === 1 ? '' : 's'}`;
        const hours = Math.floor(mins / 60);
        const rem = mins % 60;
        const h = `${hours} hour${hours === 1 ? '' : 's'}`;
        return rem === 0 ? h : `${h} ${rem} minute${rem === 1 ? '' : 's'}`;
      };
      const clipDesc = (s) => (s.length > 80 ? `${s.slice(0, 77)}…` : s);

      let summary;
      if (matched.length === 1) {
        const a = matched[0];
        const appSuffix = a.app ? ` in ${a.app}` : '';
        const descPart = a.description ? `: ${clipDesc(a.description)}` : '';
        summary = `One coding task is ${phaseText(a.phase)}${appSuffix} — ${elapsedSpoken(a.elapsedMs)} in${descPart}.`;
      } else {
        const lines = matched.map((a) => {
          const appSuffix = a.app ? ` in ${a.app}` : '';
          const descPart = a.description ? ` "${clipDesc(a.description)}"` : '';
          return `${phaseText(a.phase)}${appSuffix}${descPart}, ${elapsedSpoken(a.elapsedMs)} elapsed`;
        });
        summary = `${matched.length} coding tasks are running: ${lines.join('; ')}.`;
      }

      return { ok: true, count: matched.length, agents: matched, summary };
    },
  },
];