@aion0/forge 0.10.20 → 0.10.23

package/lib/chat/agent-loop.ts

@@ -26,6 +26,7 @@ import {
 import { getMemoryStore } from './memory-store';
 import { buildMemoryContext } from './build-memory-context';
 import { buildMemoryTools } from './memory-tools';
+import { buildStartWatchTool } from '../watch/start-watch-tool';
 import { estimateTokens } from '../memory/token-estimate';
 import {
   listInstalledConnectors,
@@ -48,10 +49,25 @@ const MAX_TOKENS = 16000;
 // and recalled via buildMemoryContext as compact blocks instead.
 const HISTORY_MSG_BUDGET = 60;
 const HISTORY_TOKEN_BUDGET = 8000;
+// Hard cap on a single tool_result stored into the conversation (chars).
+// A giant result (e.g. a connector returning a full test tree) would
+// otherwise blow the whole HISTORY_TOKEN_BUDGET, push its paired
+// assistant tool_use out of the window, and leave an orphan tool_result
+// that trimOrphanToolResults strips — yielding an empty history and an
+// "messages must not be empty" provider error. ~16k chars ≈ 4k tokens,
+// half the budget, so a complete tool_use+result pair always survives.
+const MAX_TOOL_RESULT_CHARS = 16000;
 
 // After clipping to last N, the first kept message may be a tool_result
 // whose tool_use was cut. Anthropic/OpenAI both reject that, so drop
 // leading tool_result-bearing user messages until the slice starts clean.
+function truncateToolResult(s: string): string {
+  if (s.length <= MAX_TOOL_RESULT_CHARS) return s;
+  return s.slice(0, MAX_TOOL_RESULT_CHARS) +
+    `\n\n[… tool result truncated: ${s.length} chars total, showing first ${MAX_TOOL_RESULT_CHARS}. ` +
+    `Refine the call (filter / paginate / flatten) to get a smaller, complete result.]`;
+}
+
 function trimOrphanToolResults(history: Message[]): Message[] {
   let i = 0;
   while (i < history.length) {
@@ -73,6 +89,7 @@ export interface AgentEvent {
     | 'message_saved'   // a full message persisted (assistant or tool-results carrier)
     | 'memory_status'   // pinned/blocks/hits snapshot from Temper for the UI strip
     | 'turn_done'       // loop finished
+    | 'watch_status'    // ambient background-watch progress (status chip, NOT a message)
     | 'error';          // unrecoverable
   message_id?: string;
   data?: any;
@@ -308,9 +325,9 @@ function buildConnectorTools(): LlmTool[] {
     for (const entry of getConnectorEntries(def)) {
       for (const [toolName, tool] of Object.entries(entry.tools || {})) {
         // Executable if it has a script (browser protocol) OR a non-browser
-        // protocol that runs server-side (http / shell).
+        // protocol that runs server-side (http / shell / ssh).
         const protocol = (tool as any).protocol;
-        const isServerSide = protocol === 'http' || protocol === 'shell';
+        const isServerSide = protocol === 'http' || protocol === 'shell' || protocol === 'ssh';
         if (!tool.script && !isServerSide) continue;
         const properties: Record<string, unknown> = {};
         const required: string[] = [];
@@ -392,6 +409,11 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
   const memHandlers: Record<string, BuiltinHandler> = {};
   for (const t of memTools) memHandlers[t.def.name] = t.handle;
 
+  // start_watch — LLM-driven background watch (always available). Bound
+  // to this session so completion reports back here.
+  const watchTool = buildStartWatchTool(args.sessionId);
+  memHandlers[watchTool.def.name] = watchTool.handle;
+
   if (memStore.enabled) {
     // Inspector strip (memory_status event) wants the full inventory —
     // keep its own listBlocks call. The prompt-injection text comes
@@ -466,6 +488,7 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
   const builtinDefsAll = [
     ...BUILTIN_TOOL_DEFS,
     ...memTools.map((m) => m.def),
+    watchTool.def,
   ];
   const allTools: LlmTool[] = [
     ...builtinDefsAll.map((t) => ({
@@ -500,6 +523,13 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
       const history = trimOrphanToolResults(
         listMessagesCapped(args.sessionId, HISTORY_MSG_BUDGET, HISTORY_TOKEN_BUDGET, estimateTokens),
       );
+      // Belt-and-suspenders: tool_result truncation should keep a complete
+      // pair in-window, but if history is somehow empty, fail clearly
+      // instead of letting the provider throw "messages must not be empty".
+      if (history.length === 0) {
+        cb({ type: 'error', data: { error: 'Conversation context is empty after trimming an oversized result. Clear the chat or retry with a narrower query.' } });
+        return { ok: false, error: 'empty history' };
+      }
 
       assistantBlocksAccum = [];
       let currentTextBuf = '';
@@ -543,11 +573,11 @@ export async function runTurn(args: RunTurnArgs): Promise<{ ok: boolean; error?:
       const toolUses = result.content.filter((b): b is ToolUseBlock => b.type === 'tool_use');
       const toolResults: ToolResultBlock[] = [];
       for (const t of toolUses) {
-        const r = await dispatchTool({ id: t.id, name: t.name, input: t.input }, memHandlers);
+        const r = await dispatchTool({ id: t.id, name: t.name, input: t.input }, { extraBuiltins: memHandlers, sessionId: args.sessionId });
         const block: ToolResultBlock = {
           type: 'tool_result',
           tool_use_id: t.id,
-          content: r.content,
+          content: truncateToolResult(r.content),
           is_error: r.is_error,
         };
         toolResults.push(block);

package/lib/chat/bridge-client.ts

@@ -13,13 +13,13 @@ const BRIDGE_PORT = Number(process.env.BRIDGE_PORT) || 8407;
 interface BridgeRpcOk { ok: true; value: unknown }
 interface BridgeRpcErr { ok: false; error: string }
 
-export async function bridgeRpc(method: string, params: unknown): Promise<unknown> {
+export async function bridgeRpc(method: string, params: unknown, timeoutMs?: number): Promise<unknown> {
   let res: Response;
   try {
     res = await fetch(`http://127.0.0.1:${BRIDGE_PORT}/api/rpc`, {
       method: 'POST',
       headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ method, params }),
+      body: JSON.stringify({ method, params, ...(timeoutMs ? { timeout_ms: timeoutMs } : {}) }),
     });
   } catch (e) {
     throw new Error(`browser bridge unreachable on port ${BRIDGE_PORT}: ${(e as Error).message}`);

package/lib/chat/protocols/ssh.ts

@@ -0,0 +1,206 @@
+/**
+ * SSH protocol runtime for connector tools (`protocol: ssh`).
+ *
+ * Drives the system `ssh` binary through a PTY (node-pty) so it can
+ * handle interactive flows the plain `shell` protocol can't: password
+ * auth and mid-command confirmations like `(y/N)`. Built for network
+ * devices — e.g. FortiNAC `execute restore image scp …` which prompts
+ * twice for `y` then streams a multi-minute restore before rebooting.
+ *
+ * Declarative, expect-style: the manifest's `ssh` block says what to
+ * send, what to auto-answer, the success/failure markers, and which
+ * regexes to capture from the transcript. Nothing here is FortiNAC-
+ * specific.
+ *
+ * Safety: connectors are user-installed. An ssh-protocol tool can run
+ * arbitrary remote commands — review at install time. The password is
+ * fed silently (ssh doesn't echo it) so it never lands in the captured
+ * transcript; we also never log it.
+ */
+
+import type { ConnectorTool, SshSpec } from '../../connectors/types';
+import { expandAllTokens } from '../../plugins/templates';
+import * as pty from 'node-pty';
+
+export interface SshProtocolArgs {
+  tool: ConnectorTool;
+  settings: Record<string, any>;
+  args: Record<string, any>;
+}
+
+export interface SshProtocolResult {
+  content: string;
+  is_error?: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const MAX_TIMEOUT_MS = 280_000;
+const MAX_OUTPUT_BYTES = 24 * 1024;
+
+function truncate(s: string): string {
+  const buf = Buffer.from(s, 'utf-8');
+  if (buf.byteLength <= MAX_OUTPUT_BYTES) return s;
+  // Keep the tail — the interesting markers (done/reboot) are at the end.
+  return `(…truncated, total ${buf.byteLength} bytes)\n` +
+    buf.subarray(buf.byteLength - MAX_OUTPUT_BYTES).toString('utf-8');
+}
+
+function rx(pattern: string | undefined): RegExp | null {
+  if (!pattern) return null;
+  try { return new RegExp(pattern, 'i'); } catch { return null; }
+}
+
+/**
+ * Resolve what to actually type for an auto-answer. If the rule's value is
+ * the intent `yes`/`no`, pick the token the prompt itself offers — `(yes/no)`
+ * → `yes`/`no`, otherwise `y`/`n`. We always send an EXPLICIT token (never
+ * rely on the prompt's default: `(y/N)` defaults to N, so "continue" must
+ * send `y` outright). Any other value is sent literally.
+ */
+function resolveAnswer(send: string, promptChunk: string): string {
+  const intent = String(send || '').trim().toLowerCase();
+  if (intent !== 'yes' && intent !== 'no') return send; // literal passthrough
+  const offersWords = /\byes\s*\/\s*no\b/i.test(promptChunk);
+  if (intent === 'yes') return offersWords ? 'yes' : 'y';
+  return offersWords ? 'no' : 'n';
+}
+
+export async function runSsh({ tool, settings, args }: SshProtocolArgs): Promise<SshProtocolResult> {
+  const specRaw = tool.ssh;
+  if (!specRaw) return { content: 'ssh tool missing `ssh` block', is_error: true };
+
+  const exp = (s: string | undefined) => (s == null ? '' : expandAllTokens(String(s), settings, args));
+
+  const spec: SshSpec = specRaw;
+
+  // Resolve connection params: chat arg > connector setting > literal in
+  // the ssh block > built-in default. (IP comes from chat; port/user/
+  // password fall back to the connector's saved defaults.)
+  const pickConn = (
+    argKeys: string[], settingKey: string, specVal: unknown, dflt: string, secret: boolean,
+  ): string => {
+    for (const k of argKeys) {
+      const v = args?.[k];
+      if (v != null && String(v) !== '') return secret ? String(v) : String(v).trim();
+    }
+    const sv = settings?.[settingKey];
+    if (sv != null && String(sv) !== '') return secret ? String(sv) : String(sv).trim();
+    if (specVal != null && specVal !== '') {
+      const r = exp(String(specVal));
+      if (r && !r.includes('{')) return secret ? r : r.trim();  // skip unresolved templates
+    }
+    return dflt;
+  };
+  const host = pickConn(['host'], 'host', spec.host, '', false);
+  const port = pickConn(['port'], 'port', spec.port, '22', false);
+  const user = pickConn(['username', 'user'], 'username', spec.user, '', false);
+  const password = pickConn(['password'], 'password', spec.password, '', true);
+  if (!host) return { content: 'ssh: host is required (pass it from chat, e.g. host=10.15.52.152)', is_error: true };
+  if (!user) return { content: 'ssh: user is required (pass username, or set a connector default)', is_error: true };
+
+  const commands = (spec.commands || []).map((c) => exp(c));
+  const autoAnswer = (spec.auto_answer || []).map((r) => ({ re: rx(r.match), send: exp(r.send) }));
+  const promptRe = rx(spec.prompt_regex) || /[#$>]\s*$/;
+  const doneRe = rx(spec.done_when);
+  const failRe = rx(spec.fail_when);
+  const passwordRe = /password:\s*$/i;
+  const timeoutMs = Math.min(MAX_TIMEOUT_MS, Math.max(2_000, Number(spec.timeout_sec || 0) * 1000 || DEFAULT_TIMEOUT_MS));
+
+  const sshArgs = [
+    '-tt',                                       // force PTY for interactive prompts
+    '-p', port,
+    '-o', 'StrictHostKeyChecking=accept-new',    // no yes/no host-key prompt
+    '-o', 'UserKnownHostsFile=/dev/null',        // don't pollute known_hosts
+    '-o', 'GlobalKnownHostsFile=/dev/null',
+    '-o', 'ConnectTimeout=15',
+    '-o', 'NumberOfPasswordPrompts=2',
+    `${user}@${host}`,
+  ];
+
+  return new Promise<SshProtocolResult>((resolve) => {
+    let term: pty.IPty;
+    try {
+      term = pty.spawn('ssh', sshArgs, {
+        name: 'xterm-color',
+        cols: 200, rows: 50,
+        cwd: process.env.HOME || process.cwd(),
+        env: process.env as Record<string, string>,
+      });
+    } catch (e) {
+      return resolve({ content: `ssh spawn failed: ${(e as Error).message}`, is_error: true });
+    }
+
+    let full = '';
+    let cmdIndex = 0;
+    let pwSent = 0;
+    let settled = false;
+    const captured: Record<string, string> = {};
+
+    const finish = (is_error: boolean, note: string) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { term.kill(); } catch {}
+      // Run captures over the full transcript.
+      if (spec.capture) {
+        for (const [name, pat] of Object.entries(spec.capture)) {
+          const m = full.match(rx(pat) || /$^/);
+          if (m && m[1] != null) captured[name] = m[1];
+        }
+      }
+      const payload = {
+        ok: !is_error,
+        note,
+        ...(Object.keys(captured).length ? { captured } : {}),
+        output_tail: truncate(full).slice(-4000),
+      };
+      resolve({ content: JSON.stringify(payload), is_error });
+    };
+
+    const timer = setTimeout(() => finish(true, `timed out after ${timeoutMs / 1000}s`), timeoutMs);
+
+    term.onData((chunk: string) => {
+      full += chunk;
+      // 1) success / failure markers (check on a trailing window so a
+      //    marker split across chunks still matches).
+      const tail = full.slice(-2000);
+      if (doneRe && doneRe.test(tail)) return finish(false, 'done marker matched');
+      if (failRe && failRe.test(tail)) return finish(true, 'failure marker matched');
+
+      // 2) password prompt → feed password silently.
+      if (password && passwordRe.test(chunk)) {
+        if (pwSent >= 2) return finish(true, 'authentication failed (password rejected)');
+        pwSent++;
+        term.write(`${password}\r`);
+        return;
+      }
+
+      // 3) interactive confirmations — resolve the correct token (y/yes/
+      //    n/no) from THIS prompt's offered options (intent `yes`/`no`).
+      for (const rule of autoAnswer) {
+        if (rule.re && rule.re.test(chunk)) {
+          term.write(`${resolveAnswer(rule.send, chunk)}\r`);
+          return;
+        }
+      }
+
+      // 4) shell prompt → send the next queued command.
+      if (promptRe.test(chunk) && cmdIndex < commands.length) {
+        const next = commands[cmdIndex++];
+        term.write(`${next}\r`);
+        return;
+      }
+    });
+
+    term.onExit(({ exitCode }) => {
+      if (settled) return;
+      // Connection closed. Success only if explicitly allowed, or a done
+      // marker already landed (covered above). Otherwise treat as error.
+      if (spec.success_on_close && cmdIndex >= commands.length) {
+        return finish(false, `connection closed (exit ${exitCode})`);
+      }
+      const sawDone = doneRe ? doneRe.test(full) : false;
+      finish(!sawDone, sawDone ? 'done before close' : `connection closed unexpectedly (exit ${exitCode})`);
+    });
+  });
+}

package/lib/chat/tool-dispatcher.ts

@@ -12,6 +12,7 @@
 import { bridgeRpc } from './bridge-client';
 import { runHttp } from './protocols/http';
 import { runShell } from './protocols/shell';
+import { runSsh } from './protocols/ssh';
 import {
   getConnector,
   getInstalledConnector,
@@ -482,6 +483,12 @@ export interface DispatchOptions {
    * therefore don't need an LLM-friendly truncation.
    */
   noTruncation?: boolean;
+  /** Chat session that triggered this call — used to register a watch
+   *  (async tools) bound to the right session for completion callbacks. */
+  sessionId?: string;
+  /** Remaining chain budget for async watch callbacks. Defaults to the
+   *  full depth at the top level; decremented when a watch chains a tool. */
+  chainDepth?: number;
 }
 
 export async function dispatchTool(
@@ -522,6 +529,18 @@ export async function dispatchTool(
   const protocol = located.tool.protocol || 'browser';
   const argInput = (call.input ?? {}) as Record<string, any>;
 
+  // Apply each parameter's `default` for keys the model omitted, so
+  // template tokens like {args.scp_host} resolve instead of staying
+  // literal. JSON-schema defaults are only advisory to the model — it
+  // routinely drops optional fields — so fill them here. Only sets
+  // missing/null; never overrides a value the model actually passed.
+  for (const [pname, pdef] of Object.entries(located.tool.parameters || {})) {
+    if (pdef && typeof pdef === 'object' && 'default' in (pdef as any)
+        && (argInput[pname] === undefined || argInput[pname] === null)) {
+      argInput[pname] = (pdef as any).default;
+    }
+  }
+
   // Multi-instance overlay: when a connector's settings carry a
   // `instances` array of `{name, ...}` objects, the tool's `instance`
   // arg picks one and its fields are merged into the top-level settings
@@ -554,28 +573,64 @@ export async function dispatchTool(
   }
 
   try {
+    let result: ToolResult;
     switch (protocol) {
       case 'http':
-        return await runHttp({ tool: located.tool, settings: effectiveSettings, args: argInput, connectorAuth: def.auth, noTruncation: opts.noTruncation });
+        result = await runHttp({ tool: located.tool, settings: effectiveSettings, args: argInput, connectorAuth: def.auth, noTruncation: opts.noTruncation });
+        break;
       case 'shell':
-        return await runShell({ tool: located.tool, settings: effectiveSettings, args: argInput });
+        result = await runShell({ tool: located.tool, settings: effectiveSettings, args: argInput });
+        break;
+      case 'ssh':
+        result = await runSsh({ tool: located.tool, settings: effectiveSettings, args: argInput });
+        break;
       case 'browser': {
         // Hand the whole connector + tool spec + input + settings to the
         // extension's runner.ts via the bridge. The extension keeps owning
         // the runner logic (tab acquire, navigate, executeScript).
         const connector = buildConnectorPayload(def, located.entry, effectiveSettings);
-        const result = (await bridgeRpc('connector.run', {
+        const r = (await bridgeRpc('connector.run', {
           pluginId: located.connectorId,       // wire-name kept for extension
           toolName: located.toolName,
           input: argInput,
           connector,
           settings: effectiveSettings,
-        })) as { content?: string; is_error?: boolean } | null;
-        return { content: result?.content ?? '(no content returned)', is_error: !!result?.is_error };
+        }, located.tool.timeout_ms)) as { content?: string; is_error?: boolean } | null;
+        result = { content: r?.content ?? '(no content returned)', is_error: !!r?.is_error };
+        break;
       }
       default:
         return { content: `unknown protocol "${protocol}" on tool ${call.name}`, is_error: true };
     }
+
+    // Async (long-task watch): if the tool declared an `async` block and
+    // it ran without error, register a background watch that polls to
+    // completion and reports back to the originating chat session. The
+    // tool's own result is returned to the caller immediately (detach).
+    if (located.tool.async && !result.is_error) {
+      try {
+        const { registerWatch, DEFAULT_CHAIN_DEPTH } = await import('../watch/register');
+        let parsed: unknown = result.content;
+        try { parsed = JSON.parse(result.content); } catch { /* keep string */ }
+        const reg = registerWatch({
+          spec: located.tool.async,
+          connectorId: located.connectorId,
+          toolName: located.toolName,
+          args: argInput,
+          result: parsed,
+          settings: effectiveSettings,
+          sessionId: opts.sessionId ?? null,
+          chainDepth: opts.chainDepth ?? DEFAULT_CHAIN_DEPTH,
+        });
+        const note = reg.ok
+          ? `\n\n[watch ${reg.watch_id} registered — polling in the background; you'll get a chat update on completion.]`
+          : `\n\n[watch not registered: ${reg.reason}]`;
+        result = { ...result, content: result.content + note };
+      } catch (e) {
+        console.warn('[dispatch] registerWatch failed', (e as Error).message);
+      }
+    }
+    return result;
   } catch (e) {
     return { content: `connector tool failed: ${(e as Error).message}`, is_error: true };
   }

package/lib/chat-standalone.ts

@@ -37,6 +37,7 @@ import {
 } from './chat/session-store';
 import { runTurn, type AgentEvent } from './chat/agent-loop';
 import { bridgePush } from './chat/bridge-client';
+import { startWatchRunner } from './watch/watch-runner';
 
 const PORT = Number(process.env.CHAT_PORT) || 8408;
 const startTime = Date.now();
@@ -302,6 +303,17 @@ httpServer.listen(PORT, '127.0.0.1', () => {
     const main = ensureMainSession();
     console.log(`[chat] Main session: ${main.id.slice(0, 8)} "${main.title}"`);
   } catch (e) { console.warn('[chat] ensureMainSession failed:', (e as Error).message); }
+
+  // Background long-task watches: poll to completion, then feed the
+  // result back into the originating session (assistant replies) or push
+  // ambient progress (status chip, not a message).
+  startWatchRunner({
+    onProgress: (sessionId, payload) => fanoutEvent(sessionId, { type: 'watch_status', data: payload }),
+    runChat: (sessionId, text) => {
+      void runTurn({ sessionId, userText: text, callbacks: { onEvent: (e) => fanoutEvent(sessionId, e) } })
+        .catch((err) => console.error('[watch] runChat failed', (err as Error).message));
+    },
+  });
 });
 
 function shutdown(): void {

package/lib/connectors/types.ts

@@ -14,7 +14,101 @@
 export type ConnectorRunner = 'main' | 'isolated';
 
 /** Where a tool's execution lives. */
-export type ConnectorProtocol = 'browser' | 'http' | 'shell';
+export type ConnectorProtocol = 'browser' | 'http' | 'shell' | 'ssh';
+
+/** One expect rule for `protocol: ssh`: when output matches `match`
+ *  (a regex, tested per output chunk), send `send` + Enter. Used to
+ *  auto-answer interactive prompts like `(y/N)`.
+ *
+ *  `send` may be the INTENT `yes`/`no` — the runner then picks the token
+ *  the prompt actually offers (`(y/N)` → `y`/`n`, `(yes/no)` → `yes`/`no`)
+ *  and always sends it explicitly (never relies on the prompt's default).
+ *  Any other value is sent literally. */
+export interface SshExpectRule {
+  match: string;
+  send: string;
+}
+
+/** One completion/failure action for an async watch. */
+export interface WatchAction {
+  /** chat = feed result back to the originating session (assistant replies);
+   *  tool = dispatch a tool (chaining); none = just record terminal state. */
+  mode?: 'chat' | 'tool' | 'none';
+  /** mode=chat: text injected into the session (templated with {poll.*}). */
+  message?: string;
+  /** mode=tool: `<connector>.<tool>` to dispatch. */
+  tool?: string;
+  /** mode=tool: args (templated with {poll.*}/{args.*}). */
+  args?: Record<string, unknown>;
+}
+
+/**
+ * `async` block — declares a tool as a long-running task that Forge
+ * watches in the background. Templating in poll_args / done_match.equals /
+ * action args / progress.message: {args.*} = the trigger's input,
+ * {result.*} = the trigger's return value (resolved once at register
+ * time), {poll.*} = the latest poll result (resolved per use).
+ */
+export interface AsyncWatchSpec {
+  /** Tool to poll (same connector), bare tool name e.g. `get_version`. */
+  poll: string;
+  /** Args for each poll call (templated against trigger args/result). */
+  poll_args?: Record<string, unknown>;
+  /** (A) poll-result path that, when truthy, means done. */
+  done_path?: string;
+  /** (B) value comparison on a poll-result path. */
+  done_match?: { path: string; equals?: string; contains?: string };
+  /** poll-result path that, when truthy, means failed. */
+  fail_path?: string;
+  /** Seconds between polls (default 60, min 30). */
+  interval_sec?: number;
+  /** Overall deadline in seconds (default 1200). */
+  timeout_sec?: number;
+  /** Hard cap on poll count (default 40). */
+  max_polls?: number;
+  /** Completion action (default {mode:'chat'}). */
+  on_done?: WatchAction;
+  /** Failure/timeout action (default {mode:'chat'}). */
+  on_fail?: WatchAction;
+  /** Per-poll ambient progress (does not enter the message thread). */
+  progress?: { show?: boolean; message?: string };
+}
+
+/**
+ * `protocol: ssh` spec — drives an interactive SSH session via a PTY
+ * (the system `ssh` binary). Built for devices whose CLI needs a
+ * password + interactive confirmations (e.g. FortiNAC firmware restore).
+ * All string fields are templated with {settings.*}/{args.*}.
+ */
+export interface SshSpec {
+  // Connection params are resolved by the runner with this precedence:
+  //   tool arg (host/port/username/password) > connector setting
+  //   (host/port/username/password) > the literal here > built-in default.
+  // So chat can pass them per-call and the connector holds defaults; the
+  // IP typically comes from chat only (no setting). All optional here.
+  host?: string;
+  /** Default 22. */
+  port?: string | number;
+  user?: string;
+  /** Password fed when a `password:` prompt appears (sent silently). */
+  password?: string;
+  /** Commands sent one-per-shell-prompt, in order (e.g. the upgrade cmd, then exit). */
+  commands?: string[];
+  /** Auto-answers applied throughout the session (e.g. `(y/N)` → `y`). */
+  auto_answer?: SshExpectRule[];
+  /** Shell-prompt regex that gates sending the next command. Default `[#$>]\s*$`. */
+  prompt_regex?: string;
+  /** Success marker regex — when seen, the session resolves ok and ssh is closed. */
+  done_when?: string;
+  /** Failure marker regex — when seen, resolves is_error. */
+  fail_when?: string;
+  /** name → regex(1 capture group) pulled from the full transcript into the result. */
+  capture?: Record<string, string>;
+  /** Overall timeout. Default 120s, max 280s. */
+  timeout_sec?: number;
+  /** Treat the remote closing the connection as success (e.g. after `exit`). */
+  success_on_close?: boolean;
+}
 
 /** Schema for one settings or parameter field. */
 export interface ConnectorFieldSchema {
@@ -170,7 +264,29 @@ export interface ConnectorTool {
   /** Extra env vars (values templated). */
   env?: Record<string, string>;
 
-  /** shell/http: timeout in milliseconds. Default 30000, max 300000. */
+  // ── protocol: 'ssh' ───────────────────────────────────────
+  /** Interactive SSH session spec (PTY-driven). See SshSpec. */
+  ssh?: SshSpec;
+
+  // ── async (long-task watch) ───────────────────────────────
+  /**
+   * Marks this tool as a long-running task. After it runs (and detaches
+   * quickly), Forge registers a background **watch** that periodically
+   * polls `async.poll` until done/failed/timeout, then feeds the result
+   * back into the originating chat session (or chains a tool). See
+   * AsyncWatchSpec + lib/watch/. The lightweight async-callback primitive
+   * for chat-driven background tasks (NAC upgrade, pytest runs, …).
+   */
+  async?: AsyncWatchSpec;
+
+  /**
+   * Timeout in milliseconds.
+   *  - shell/http: request timeout (default 30000, max 300000).
+   *  - browser: how long the bridge waits for the extension to return the
+   *    RPC result (default 60000, capped at 900000). Raise it for tools
+   *    whose script issues a long synchronous backend call (e.g. a NAC
+   *    upgrade that blocks for minutes).
+   */
   timeout_ms?: number;
 
   /**

package/lib/help-docs/21-build-connector.md

@@ -451,3 +451,45 @@ When the user reports a bug ("the list_my_issues tool returned 0 rows"):
   `script` body needs to change. Bump version, save, retry — the
   registry-based update path is for connectors that came from a
   shared `forge-connectors` repo.
+
+## Long-running tools — the `async` block (background watch)
+
+A tool that kicks off work which finishes minutes later (a firmware
+upgrade, a test run) should NOT hold the chat open. Declare an `async`
+block: the tool runs and returns immediately (detach), and Forge
+registers a background **watch** that polls until done, then reports
+back into the originating chat session — no AI babysitting.
+
+```yaml
+upgrade:
+  protocol: ssh
+  async:
+    poll: get_version              # another tool in THIS connector to poll
+    poll_args:                     # built once from the trigger's args/result
+      host: "{args.host}"          # {args.*}=trigger input, {result.*}=trigger return
+    # completion test — one of:
+    done_path: done                #   (a) poll-result path is truthy
+    done_match:                    #   (b) value compare
+      path: captured.build
+      equals: "{result.captured.target_build}"
+    fail_path: error               # optional: truthy = failed
+    interval_sec: 60               # poll cadence (min 30)
+    timeout_sec: 900               # overall deadline
+    max_polls: 15                  # hard cap
+    on_done: { mode: chat, message: "Done — build {poll.captured.build}." }
+    on_fail: { mode: chat, message: "Not confirmed — check manually." }
+    progress: { show: true, message: "Working… {poll_count}/{max_polls}" }
+```
+
+- `on_done`/`on_fail.mode`: `chat` (default — assistant replies in the
+  session; a telegram-origin session replies on telegram), `tool`
+  (chain another tool — `tool` + `args`, depth-limited), or `none`.
+- `progress` shows an ambient status chip per poll — it does NOT enter
+  the message thread or trigger the LLM.
+- Templating: `{poll.*}` = latest poll result; `{poll_count}`/`{max_polls}`.
+- Guards (not overridable to unbounded): max_polls, timeout,
+  max_lifetime, consecutive-error cutoff, chain depth, global active cap.
+- Watches persist in SQLite (survive restart) and are listed/cancelable
+  in /chat's "Background watches" panel.
+- Secrets: don't put a password in `poll_args` (it persists in the watch
+  row). Rely on the connector's saved default credential instead.