@aion0/forge 0.10.90 → 0.11.0

package/lib/claude-process.ts

@@ -6,7 +6,10 @@
  */
 
 import { spawn, execSync, type ChildProcess } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { loadSettings } from './settings';
+import { getConfigDir } from './dirs';
 
 export interface ClaudeMessage {
   type: 'system' | 'assistant' | 'result';
@@ -93,6 +96,15 @@ export function sendToClaudeSession(
   const env = { ...process.env };
   delete env.CLAUDECODE;
 
+  // Corporate SSL: behind an intercepting proxy the spawned CLI fails with
+  // "SSL certificate verification failed" unless it trusts the corp CA. If the
+  // server was launched without NODE_EXTRA_CA_CERTS but a CA bundle is dropped
+  // at <configDir>/corporate-ca.pem, wire it through so the child inherits it.
+  if (!env.NODE_EXTRA_CA_CERTS) {
+    const corpCa = join(getConfigDir(), 'corporate-ca.pem');
+    if (existsSync(corpCa)) env.NODE_EXTRA_CA_CERTS = corpCa;
+  }
+
   // Resolve full path so spawn works without shell for PATH lookup.
   // Was a lazy require() — fired ReferenceError on Claude task spawn
   // under ESM concurrent loads. Now top-level imported.

package/lib/help-docs/14-kanban.md

@@ -0,0 +1,59 @@
+# Home Kanban
+
+The home page shows a collapsible **Kanban** board of connector-driven cards.
+Each card runs a prompt against one connector on its own schedule and renders the
+result as a compact widget. Nothing is hardcoded per connector — a card is just
+*connector + prompt + period*, and the prompt's output drives what's drawn.
+
+## Cards
+
+- **Compact + fixed-size**: cards are small previews so the board never dominates
+  the page. Click a card to open a floating modal with the full widget.
+- **Status dot**: grey idle · amber running · green ok · red error.
+- **⟳ refresh** runs the card now. **✕** deletes it. **↗** opens the connector site.
+- **+ defaults** seeds cards from your installed connectors' declared defaults
+  (idempotent — re-running won't duplicate).
+
+## Editing a card (no connector republish)
+
+A card's prompt and period live in Forge's local database, seeded from the
+connector manifest's `kanban:` block only on first install / `+ defaults`. To
+tune a card, open it and click **Edit prompt / period** — change the prompt text,
+the refresh interval, or the run mode, then **Save & run**. This only changes the
+local card; you never need to edit or republish the connector.
+
+## Run modes
+
+- **inline** (default): a fast single LLM turn using your default API profile.
+  Best for simple count/list cards.
+- **task**: the card is dispatched as a one-shot CLI task (the same backend as
+  normal Forge tasks) that can work over many steps, call the connector via the
+  Forge MCP tools, and write the final widget to
+  `<dataDir>/kanban/<cardId>/widget.json`. Best for heavy connectors (many tools)
+  or richer, multi-step content. The task may also write supplementary files
+  (e.g. `report.md`) into the same folder and link to them from the widget via
+  `href` `/api/kanban/<cardId>/artifact/<filename>`.
+
+Heavy connectors can declare `mode: task` per card in their manifest; you can
+also flip any card's mode in the Edit panel.
+
+## Declaring cards in a connector
+
+A connector manifest may carry kanban defaults (read by Forge's seeder, ignored
+by the connector loader — fully additive, old Forge versions skip it):
+
+```yaml
+kanban:
+  cards:
+    - title: "My widget"
+      icon: "📊"
+      prompt: |
+        What to gather + how to summarize.
+      period_sec: 1800     # refresh cadence (default 1800)
+      mode: task           # optional: 'inline' (default) | 'task'
+```
+
+## Refresh cadence
+
+Cards refresh on their own period via the same scheduler tick as Schedules, plus
+manual ⟳. Snapshots are stored, so a card shows its last result until the next run.

package/lib/kanban/artifacts.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-card artifact directory under <dataDir>/kanban/<cardId>/. A task-mode run
+ * writes its final widget to widget.json here, plus optional supplementary
+ * files (report.md, data, …) the widget can link to via the artifact route.
+ */
+
+import { join, normalize } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { getDataDir } from '../dirs';
+import type { WidgetSpec } from './types';
+
+const WIDGET_FILE = 'widget.json';
+
+export function cardArtifactDir(cardId: string): string {
+  return join(getDataDir(), 'kanban', cardId);
+}
+
+export function ensureArtifactDir(cardId: string): string {
+  const dir = cardArtifactDir(cardId);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function widgetFilePath(cardId: string): string {
+  return join(cardArtifactDir(cardId), WIDGET_FILE);
+}
+
+/** Remove a stale widget.json before a run so we never read a previous result. */
+export function clearWidgetFile(cardId: string): void {
+  try { rmSync(widgetFilePath(cardId), { force: true }); } catch { /* ignore */ }
+}
+
+/** Read + validate the widget.json a task wrote. Null if missing/invalid. */
+export function readWidgetFile(cardId: string): WidgetSpec | null {
+  const p = widgetFilePath(cardId);
+  if (!existsSync(p)) return null;
+  try {
+    const v = JSON.parse(readFileSync(p, 'utf-8'));
+    if (v && typeof v === 'object' && Array.isArray((v as any).blocks)) return v as WidgetSpec;
+  } catch { /* invalid */ }
+  return null;
+}
+
+/** Resolve a requested artifact name to an absolute path INSIDE the card dir,
+ *  or null on traversal / escape. Used by the artifact-serving route. */
+export function safeArtifactPath(cardId: string, name: string): string | null {
+  const base = cardArtifactDir(cardId);
+  const full = normalize(join(base, name));
+  if (full !== base && !full.startsWith(base + '/')) return null; // escaped the dir
+  if (!existsSync(full)) return null;
+  return full;
+}

package/lib/kanban/executor.ts

@@ -0,0 +1,141 @@
+/**
+ * Kanban card executor (P2). Runs a card's prompt as a headless,
+ * connector-scoped LLM turn: only the target connector's tools are exposed,
+ * the system prompt constrains output to a WidgetSpec JSON, and the loop
+ * dispatches any tool calls until the model returns a final widget.
+ *
+ * Reuses the chat primitives — streamLlm (LLM adapter), resolveProvider
+ * (default API profile), buildConnectorTools (tool specs), dispatchTool
+ * (connector execution) — so it stays consistent with the chat agent loop
+ * without dragging in the session machinery.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { streamLlm } from '../chat/llm';
+import { resolveProvider, buildConnectorTools } from '../chat/agent-loop';
+import { dispatchTool } from '../chat/tool-dispatcher';
+import type { Message, ContentBlock } from '../chat/types';
+import type { WidgetSpec } from './types';
+import { getCard, setCardRunning, setCardResult, setCardError } from './store';
+
+const MAX_TOOL_ROUNDS = 6;
+const MAX_TOKENS = 2000;
+
+/** The WidgetSpec schema, shared by the inline system prompt and the task-mode
+ *  contract prompt so both paths produce the same shape. */
+export const WIDGET_SCHEMA_TEXT = [
+  'A widget is a single JSON object matching:',
+  '{ "accent"?: Color, "blocks": Block[], "footer"?: string }',
+  'Color = "gray"|"red"|"amber"|"yellow"|"green"|"emerald"|"blue"|"violet"',
+  'Block is one of:',
+  '  {"type":"metric_row","items":[{"label":string,"value":string|number,"color"?:Color}]}',
+  '  {"type":"list","items":[{"text":string,"badge"?:string,"badgeColor"?:Color,"sub"?:string,"href"?:string,"avatar"?:string}]}',
+  '  {"type":"stat","value":string|number,"label":string,"delta"?:string,"deltaColor"?:Color}',
+  '  {"type":"progress","label":string,"value":number,"max":number,"color"?:Color}',
+  '  {"type":"table","columns":string[],"rows":string[][]}',
+  '  {"type":"badges","items":[{"text":string,"color"?:Color}]}',
+  '  {"type":"callout","text":string,"color"?:Color,"icon"?:string}   // highlighted alert box, e.g. "2 items overdue"',
+  '  {"type":"text","markdown":string}   // a short **bold** line works as a section header; supports bold/`code`/[links](url)/- bullets',
+  '',
+  'Guidance: lead with a metric_row (counts) and/or a callout for anything urgent. Use a progress block for "X of Y done / release readiness" — it renders as a nice bar. For people, set list item "avatar" to their initials (e.g. "YC"). Group long lists under short **bold** text headers.',
+  'BE TERSE: the card is small. List item "text" should be short (aim ≤ 6 words / fits one line — the compact card truncates the rest); put any extra detail in "sub", also short. Prefer keywords over sentences. metric labels ≤ 1-2 words.',
+].join('\n');
+
+function systemPrompt(): string {
+  return [
+    'You generate a Forge dashboard "kanban card". Use the available connector tools to gather exactly what the user prompt asks for, then summarize into a compact, glanceable widget.',
+    '',
+    'Output ONLY a single JSON object (no prose, no markdown fences) matching:',
+    WIDGET_SCHEMA_TEXT.split('\n').slice(1).join('\n'),
+    '',
+    'Keep it glanceable: short labels, at most ~6 list items. Choose block types that fit the data (e.g. counts → metric_row, items → list). If a tool errors or returns nothing, still return a valid widget (a text block explaining the state).',
+  ].join('\n');
+}
+
+function msg(role: 'user' | 'assistant', cardId: string, blocks: ContentBlock[]): Message {
+  return { id: randomUUID(), session_id: `kanban:${cardId}`, role, blocks, ts: Date.now() };
+}
+
+/** Run one card. Persists the result/error snapshot; never throws. */
+export async function runKanbanCard(cardId: string): Promise<{ ok: boolean; error?: string }> {
+  const card = getCard(cardId);
+  if (!card) return { ok: false, error: 'card not found' };
+
+  const provider = resolveProvider(null, null);
+  if ('error' in provider) {
+    setCardError(cardId, `provider: ${provider.error}`);
+    return { ok: false, error: provider.error };
+  }
+
+  const tools = buildConnectorTools().filter((t) => t.name.split('.')[0] === card.connectorId);
+  if (tools.length === 0) {
+    setCardError(cardId, `connector '${card.connectorId}' has no usable tools (installed + enabled?)`);
+    return { ok: false, error: 'no connector tools' };
+  }
+
+  setCardRunning(cardId);
+  const history: Message[] = [msg('user', cardId, [{ type: 'text', text: card.prompt }])];
+
+  try {
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+      const res = await streamLlm(
+        {
+          provider: provider.type,
+          apiKey: provider.apiKey,
+          baseUrl: provider.baseUrl,
+          model: provider.model,
+          system: systemPrompt(),
+          history,
+          tools,
+          maxTokens: MAX_TOKENS,
+        },
+        { onTextDelta: () => {}, onToolUse: () => {} },
+      );
+      history.push(msg('assistant', cardId, res.content));
+
+      const toolUses = res.content.filter(
+        (b): b is Extract<ContentBlock, { type: 'tool_use' }> => b.type === 'tool_use',
+      );
+      if (res.stopReason === 'tool_use' && toolUses.length > 0) {
+        const results: ContentBlock[] = [];
+        for (const tu of toolUses) {
+          const r = await dispatchTool({ id: tu.id, name: tu.name, input: tu.input });
+          results.push({ type: 'tool_result', tool_use_id: tu.id, content: r.content, is_error: r.is_error });
+        }
+        history.push(msg('user', cardId, results));
+        continue;
+      }
+
+      const text = res.content
+        .filter((b): b is Extract<ContentBlock, { type: 'text' }> => b.type === 'text')
+        .map((b) => b.text)
+        .join('')
+        .trim();
+      const spec = parseWidget(text);
+      if (!spec) {
+        setCardError(cardId, 'LLM did not return a valid widget JSON');
+        return { ok: false, error: 'invalid widget' };
+      }
+      setCardResult(cardId, spec);
+      return { ok: true };
+    }
+    setCardError(cardId, `exceeded ${MAX_TOOL_ROUNDS} tool rounds without a final widget`);
+    return { ok: false, error: 'max rounds' };
+  } catch (e) {
+    setCardError(cardId, (e as Error).message);
+    return { ok: false, error: (e as Error).message };
+  }
+}
+
+/** Tolerant extract: strip optional code fences, take the outermost {...}. */
+export function parseWidget(text: string): WidgetSpec | null {
+  const stripped = text.replace(/^```(?:json)?/i, '').replace(/```$/, '').trim();
+  const start = stripped.indexOf('{');
+  const end = stripped.lastIndexOf('}');
+  if (start === -1 || end === -1 || end <= start) return null;
+  try {
+    const v = JSON.parse(stripped.slice(start, end + 1));
+    if (v && typeof v === 'object' && Array.isArray((v as any).blocks)) return v as WidgetSpec;
+  } catch { /* not valid JSON */ }
+  return null;
+}

package/lib/kanban/seed.ts

@@ -0,0 +1,43 @@
+/**
+ * Seed kanban cards from connector-declared defaults. Each installed + enabled
+ * connector whose definition carries a `kanban` block (and isn't opted out via
+ * enabled:false) contributes its declared cards. Idempotent: a card is keyed by
+ * `<connectorId>#<index>` (seed_key) so re-seeding never duplicates, and a card
+ * the user later deleted stays deleted (its seed_key already exists only if the
+ * row exists — deleted rows are re-seeded; that's acceptable for a "restore
+ * defaults" action). The cards are DECLARATIVE — Forge core hardcodes nothing.
+ */
+
+import { listInstalledConnectors } from '../connectors/registry';
+import { createCard, existingSeedKeys } from './store';
+import type { KanbanCard, WithKanban } from './types';
+
+export function seedKanbanFromConnectors(): { created: KanbanCard[] } {
+  const have = existingSeedKeys();
+  const created: KanbanCard[] = [];
+
+  for (const inst of listInstalledConnectors()) {
+    if (!inst.enabled) continue;
+    // Read the kanban block structurally — the connector loader never parses it,
+    // so the core connector types stay free of any kanban coupling.
+    const def = inst.definition as unknown as WithKanban;
+    const kb = def.kanban;
+    if (!kb || kb.enabled === false) continue;
+    const cards = kb.cards || [];
+    cards.forEach((decl, i) => {
+      if (!decl?.prompt || !decl?.title) return;
+      const seedKey = `${def.id}#${i}`;
+      if (have.has(seedKey)) return;
+      created.push(createCard({
+        connectorId: def.id,
+        title: decl.title,
+        prompt: decl.prompt,
+        icon: decl.icon ?? def.icon ?? null,
+        periodSec: typeof decl.period_sec === 'number' && decl.period_sec > 0 ? decl.period_sec : undefined,
+        execMode: decl.mode === 'task' ? 'task' : 'inline',
+        seedKey,
+      }));
+    });
+  }
+  return { created };
+}

package/lib/kanban/store.ts

@@ -0,0 +1,219 @@
+/**
+ * Kanban dashboard SQLite store — table `kanban_cards`. Mirrors the
+ * lib/schedules/store.ts conventions (single workflow.db, ensureSchema guard,
+ * row mappers, ISO time). Card execution (connector-scoped LLM turn → WidgetSpec)
+ * lands in P2; this file is pure CRUD + result/status setters.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { getDb } from '../../src/core/db/database';
+import { getDbPath } from '../../src/config';
+import { toIsoUTC } from '../iso-time';
+import type {
+  KanbanCard,
+  KanbanCardStatus,
+  WidgetSpec,
+  CreateKanbanCardInput,
+  UpdateKanbanCardInput,
+} from './types';
+
+function db() { return getDb(getDbPath()); }
+
+let ensured = false;
+export function ensureSchema(): void {
+  if (ensured) return;
+  db().exec(`
+    CREATE TABLE IF NOT EXISTS kanban_cards (
+      id            TEXT PRIMARY KEY,
+      connector_id  TEXT NOT NULL,
+      title         TEXT NOT NULL,
+      icon          TEXT,
+      prompt        TEXT NOT NULL,
+      period_sec    INTEGER NOT NULL DEFAULT 1800,
+      card_order    INTEGER NOT NULL DEFAULT 0,
+      enabled       INTEGER NOT NULL DEFAULT 1,
+      last_result   TEXT,
+      last_run_at   TEXT,
+      last_error    TEXT,
+      status        TEXT NOT NULL DEFAULT 'idle',
+      created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at    TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_kanban_order ON kanban_cards(card_order ASC);
+  `);
+  // Idempotent add: seed_key marks a card auto-created from a connector's
+  // declared default (so re-seeding doesn't duplicate). NULL = user-created.
+  try { db().exec('ALTER TABLE kanban_cards ADD COLUMN seed_key TEXT'); } catch { /* exists */ }
+  // Execution mode (inline default | task) + the task it's tied to in task mode.
+  try { db().exec("ALTER TABLE kanban_cards ADD COLUMN exec_mode TEXT NOT NULL DEFAULT 'inline'"); } catch { /* exists */ }
+  try { db().exec('ALTER TABLE kanban_cards ADD COLUMN task_id TEXT'); } catch { /* exists */ }
+  ensured = true;
+}
+
+/** seed_keys already present — lets seeding skip cards it already created. */
+export function existingSeedKeys(): Set<string> {
+  ensureSchema();
+  const rows = db().prepare(
+    "SELECT seed_key FROM kanban_cards WHERE seed_key IS NOT NULL",
+  ).all() as { seed_key: string }[];
+  return new Set(rows.map((r) => r.seed_key));
+}
+
+// ─── Row mapper ───────────────────────────────────────────
+
+function safeWidget(raw: unknown): WidgetSpec | null {
+  if (!raw || typeof raw !== 'string') return null;
+  try {
+    const v = JSON.parse(raw);
+    return v && typeof v === 'object' && Array.isArray((v as any).blocks) ? (v as WidgetSpec) : null;
+  } catch { return null; }
+}
+
+function rowToCard(r: any): KanbanCard {
+  return {
+    id: r.id,
+    connectorId: r.connector_id,
+    title: r.title,
+    icon: r.icon ?? null,
+    prompt: r.prompt,
+    periodSec: typeof r.period_sec === 'number' ? r.period_sec : 1800,
+    order: typeof r.card_order === 'number' ? r.card_order : 0,
+    enabled: !!r.enabled,
+    execMode: r.exec_mode === 'task' ? 'task' : 'inline',
+    taskId: r.task_id ?? null,
+    lastResult: safeWidget(r.last_result),
+    lastRunAt: toIsoUTC(r.last_run_at),
+    lastError: r.last_error ?? null,
+    status: (r.status as KanbanCardStatus) || 'idle',
+    createdAt: toIsoUTC(r.created_at) || r.created_at,
+    updatedAt: toIsoUTC(r.updated_at) || r.updated_at,
+  };
+}
+
+// ─── CRUD ─────────────────────────────────────────────────
+
+export function listCards(): KanbanCard[] {
+  ensureSchema();
+  const rows = db().prepare(
+    'SELECT * FROM kanban_cards ORDER BY card_order ASC, created_at ASC',
+  ).all() as any[];
+  return rows.map(rowToCard);
+}
+
+export function getCard(id: string): KanbanCard | null {
+  ensureSchema();
+  const r = db().prepare('SELECT * FROM kanban_cards WHERE id = ?').get(id) as any;
+  return r ? rowToCard(r) : null;
+}
+
+export function createCard(input: CreateKanbanCardInput): KanbanCard {
+  ensureSchema();
+  const id = `kb_${randomUUID().slice(0, 12).replace(/-/g, '')}`;
+  // Default order = append to the end.
+  const maxOrder = (db().prepare('SELECT MAX(card_order) AS m FROM kanban_cards').get() as { m: number | null }).m;
+  const order = typeof input.order === 'number' ? input.order : (maxOrder ?? -1) + 1;
+  db().prepare(`
+    INSERT INTO kanban_cards (id, connector_id, title, icon, prompt, period_sec, card_order, enabled, seed_key, exec_mode)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    input.connectorId,
+    input.title,
+    input.icon ?? null,
+    input.prompt,
+    input.periodSec ?? 1800,
+    order,
+    input.enabled === false ? 0 : 1,
+    input.seedKey ?? null,
+    input.execMode === 'task' ? 'task' : 'inline',
+  );
+  return getCard(id)!;
+}
+
+export function updateCard(id: string, patch: UpdateKanbanCardInput): boolean {
+  ensureSchema();
+  const sets: string[] = [];
+  const vals: any[] = [];
+  if (patch.title !== undefined)     { sets.push('title = ?');      vals.push(patch.title); }
+  if (patch.prompt !== undefined)    { sets.push('prompt = ?');     vals.push(patch.prompt); }
+  if (patch.icon !== undefined)      { sets.push('icon = ?');       vals.push(patch.icon ?? null); }
+  if (patch.periodSec !== undefined) { sets.push('period_sec = ?'); vals.push(patch.periodSec); }
+  if (patch.order !== undefined)     { sets.push('card_order = ?'); vals.push(patch.order); }
+  if (patch.enabled !== undefined)   { sets.push('enabled = ?');    vals.push(patch.enabled ? 1 : 0); }
+  if (patch.execMode !== undefined)  { sets.push('exec_mode = ?');  vals.push(patch.execMode === 'task' ? 'task' : 'inline'); }
+  if (sets.length === 0) return false;
+  sets.push("updated_at = datetime('now')");
+  vals.push(id);
+  return db().prepare(`UPDATE kanban_cards SET ${sets.join(', ')} WHERE id = ?`).run(...vals).changes > 0;
+}
+
+export function deleteCard(id: string): boolean {
+  ensureSchema();
+  return db().prepare('DELETE FROM kanban_cards WHERE id = ?').run(id).changes > 0;
+}
+
+/** Persist a batch of {id, order} — used by drag-to-reorder. */
+export function reorderCards(order: { id: string; order: number }[]): void {
+  ensureSchema();
+  const stmt = db().prepare("UPDATE kanban_cards SET card_order = ?, updated_at = datetime('now') WHERE id = ?");
+  const tx = db().transaction((rows: { id: string; order: number }[]) => {
+    for (const row of rows) stmt.run(row.order, row.id);
+  });
+  tx(order);
+}
+
+/** Cards due to run: enabled, not already running, and either never run or
+ *  past their period. Used by the kanban tick. */
+export function listDueCards(): KanbanCard[] {
+  ensureSchema();
+  const rows = db().prepare(`
+    SELECT * FROM kanban_cards
+     WHERE enabled = 1 AND status != 'running'
+       AND (last_run_at IS NULL
+            OR datetime(last_run_at, '+' || period_sec || ' seconds') <= datetime('now'))
+     ORDER BY (last_run_at IS NULL) DESC, last_run_at ASC
+  `).all() as any[];
+  return rows.map(rowToCard);
+}
+
+// ─── Run status / result (used by P2 executor + manual refresh) ──
+
+export function setCardRunning(id: string): void {
+  ensureSchema();
+  db().prepare("UPDATE kanban_cards SET status = 'running', updated_at = datetime('now') WHERE id = ?").run(id);
+}
+
+/** Mark a card running AND tie it to the dispatched task (task mode). */
+export function setCardTask(id: string, taskId: string): void {
+  ensureSchema();
+  db().prepare("UPDATE kanban_cards SET task_id = ?, status = 'running', updated_at = datetime('now') WHERE id = ?").run(taskId, id);
+}
+
+/** Find the card a task was dispatched for (used by the terminal listener). */
+export function getCardByTaskId(taskId: string): KanbanCard | null {
+  ensureSchema();
+  const r = db().prepare('SELECT * FROM kanban_cards WHERE task_id = ?').get(taskId) as any;
+  return r ? rowToCard(r) : null;
+}
+
+/** Store a successful run's WidgetSpec snapshot. */
+export function setCardResult(id: string, result: WidgetSpec): void {
+  ensureSchema();
+  db().prepare(`
+    UPDATE kanban_cards
+       SET last_result = ?, last_run_at = datetime('now'), last_error = NULL,
+           status = 'ok', updated_at = datetime('now')
+     WHERE id = ?
+  `).run(JSON.stringify(result), id);
+}
+
+/** Record a failed run — keep the previous snapshot (last_result) intact. */
+export function setCardError(id: string, error: string): void {
+  ensureSchema();
+  db().prepare(`
+    UPDATE kanban_cards
+       SET last_error = ?, last_run_at = datetime('now'), status = 'error',
+           updated_at = datetime('now')
+     WHERE id = ?
+  `).run(error, id);
+}

package/lib/kanban/task-executor.ts

@@ -0,0 +1,71 @@
+/**
+ * Kanban task-mode executor. For heavy / multi-step cards the inline streamLlm
+ * turn (executor.ts) chokes on big tool schemas; instead we dispatch a one-shot
+ * CLI task (the relay backend) that can work over many steps, then writes the
+ * final widget to <dataDir>/kanban/<cardId>/widget.json. The terminal listener
+ * (task-listener.ts) reads that file back into the card. Mirrors the Schedules
+ * V3 prompt-body dispatch pattern.
+ */
+
+import { createTask } from '../task-manager';
+import { ensureScratchProject, getProjectInfo, SCRATCH_PROJECT_NAME } from '../projects';
+import { WIDGET_SCHEMA_TEXT } from './executor';
+import { getCard, setCardTask, setCardError } from './store';
+import { ensureArtifactDir, clearWidgetFile, widgetFilePath } from './artifacts';
+
+/** Compose the task prompt: the card's own prompt + a fixed contract telling the
+ *  agent how to reach the connector and where to write the widget. */
+function composePrompt(connectorId: string, cardId: string, userPrompt: string): string {
+  const outFile = widgetFilePath(cardId);
+  return [
+    `You are generating a Forge home "kanban card" for the connector "${connectorId}".`,
+    '',
+    'TASK:',
+    userPrompt,
+    '',
+    'HOW TO GET DATA:',
+    `- Call connector tools with mcp__forge__call_connector, passing plugin_id="${connectorId}", tool="<toolName>", and the tool's args. The TASK above names the tools + args to use.`,
+    '- Do NOT call mcp__forge__list_connectors — its output is huge and will waste the run. You already know plugin_id; call the named tools directly.',
+    '- You may work in multiple steps and refine. Take the time to produce accurate, well-organized content.',
+    '',
+    'OUTPUT (required):',
+    `- Write the FINAL widget as a single JSON object to this exact path: ${outFile}`,
+    '- The JSON MUST match this schema (no markdown fences inside the file):',
+    WIDGET_SCHEMA_TEXT,
+    '- Keep it glanceable: short labels, group with the block types that fit the data.',
+    `- You MAY also write supplementary files into the same directory (e.g. report.md) and link to them from list/badge "href" as "/api/kanban/${cardId}/artifact/<filename>".`,
+    '- If a tool errors or returns nothing, still write a valid widget (a text block explaining the state).',
+    '',
+    `Success = ${outFile} exists and is valid JSON. Write it as your final action.`,
+  ].join('\n');
+}
+
+/** Dispatch a task-mode run. Returns the task id, or sets card error + returns
+ *  null on dispatch failure. Never throws. */
+export function runKanbanCardViaTask(cardId: string): string | null {
+  const card = getCard(cardId);
+  if (!card) return null;
+
+  try {
+    ensureScratchProject();
+    const project = getProjectInfo(SCRATCH_PROJECT_NAME);
+    if (!project) { setCardError(cardId, 'scratch project unavailable'); return null; }
+
+    ensureArtifactDir(cardId);
+    clearWidgetFile(cardId); // never read a stale widget from a prior run
+
+    const task = createTask({
+      projectName: project.name,
+      projectPath: project.path,
+      prompt: composePrompt(card.connectorId, cardId, card.prompt),
+      conversationId: '',           // one-shot, fresh conversation
+      // agent omitted → default CLI agent (the working relay backend)
+    });
+
+    setCardTask(cardId, task.id);
+    return task.id;
+  } catch (e) {
+    setCardError(cardId, `task dispatch failed: ${(e as Error).message}`);
+    return null;
+  }
+}