@aion0/forge 0.10.22 → 0.10.23

package/lib/chat/tool-dispatcher.ts

@@ -483,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(
@@ -567,30 +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':
-        return await runSsh({ tool: located.tool, settings: effectiveSettings, args: argInput });
+        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,
         }, located.tool.timeout_ms)) as { content?: string; is_error?: boolean } | null;
-        return { content: result?.content ?? '(no content returned)', is_error: !!result?.is_error };
+        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

@@ -29,6 +29,51 @@ export interface SshExpectRule {
   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
@@ -223,6 +268,17 @@ export interface ConnectorTool {
   /** 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).

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.

package/lib/help-docs/24-watch.md

@@ -0,0 +1,77 @@
+# Background Watches
+
+A **watch** is Forge's lightweight async primitive for long-running jobs:
+you (or the assistant) kick something off that finishes minutes later —
+a device firmware upgrade, a Jenkins build, a test run — and instead of
+the assistant sitting in the conversation polling (burning tokens,
+getting stuck), Forge polls it in the **background** and posts the result
+back into this chat when it's done.
+
+You don't manage watches directly most of the time — they appear when a
+long job is started and clear themselves when it finishes.
+
+## What you see
+
+- **Progress chip** — while a watch runs, a small status pill shows
+  above the chat composer (e.g. "Upgrading NAC 10.15.52.152… poll 3/15,
+  build 6956"). It updates in place, is **not** a chat message (doesn't
+  clutter the thread), and disappears when the job finishes.
+- **Completion message** — when the job reaches its goal (or fails /
+  times out), a normal assistant message lands in the chat:
+  "NAC … upgrade confirmed — now running build 6957." If your session
+  came from Telegram, that message arrives in Telegram.
+- **Watch list** — see and control active watches in two places:
+  - **/chat** web: the "Background watches" panel in the left sidebar.
+  - **Forge web**: user menu → **Monitor** → "Background Watches".
+  Each entry shows status (active / done / failed / timed_out), poll
+  count, and **Cancel** / **Delete** buttons.
+
+Watches survive a Forge restart (persisted in SQLite) — an in-flight
+upgrade keeps being watched after a restart, no chat needed.
+
+## Two ways a watch starts
+
+**1. Connector built-in (`async` block).** Some connector tools are
+pre-declared as long tasks by their author — e.g. `nac.upgrade`
+automatically registers a watch that polls `nac.get_version` until the
+new build is running. Nothing for you to do; it just works.
+
+**2. The assistant decides (`start_watch`).** For long jobs that aren't
+pre-declared — a Jenkins build, a one-off cross-connector flow — the
+assistant calls the `start_watch` builtin on the fly: it triggers the
+job, registers a watch to poll the right status tool, and then stops
+talking. You get the result later in chat.
+
+Both use the same background machinery; you experience them identically.
+
+## `start_watch` (for the assistant)
+
+When you've just started a long job and have a tool that reports its
+status, register a watch instead of polling in the conversation:
+
+```
+start_watch({
+  poll: "jenkins.get_build",                       // <connector>.<status tool>
+  poll_args: { job_path: "job/foo", build_number: 18 },
+  done_match: { path: "result", equals: "SUCCESS" },  // or done_path (truthy)
+  interval_sec: 60, timeout_sec: 1800,
+  message: "Build 18 finished: {poll.result}"      // {poll.<path>} = latest result
+})
+```
+
+Then **stop** — do not keep calling get_build in the conversation. A
+completion message arrives in chat; the user can cancel it from the watch
+list. Pick `done_match`/`done_path` from a field you saw in the status
+tool's output (you usually called it once already). Queue/startup errors
+(e.g. a build number 404 while still queued) are tolerated for a while.
+Guards (max polls, timeout, lifetime, active cap) keep it from running
+away; worst case it times out and reports that.
+
+## Limits
+
+- Watches are short-lived; they end at done / failed / timed_out /
+  cancelled and stop polling.
+- `start_watch` reports back only via chat — it doesn't open a separate
+  notification channel. Telegram-origin sessions reply on Telegram.
+- A watch can't *fix* a job that's stuck waiting for human action (a
+  build needing approval); it only watches to a final state and reports.

package/lib/help-docs/CLAUDE.md

@@ -50,6 +50,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `21-build-connector.md` | **Authoring** a custom connector — interview script, manifest template (browser / http / shell protocols), how to install locally via the Forge data dir or a zip upload. Use this when the user asks to BUILD a connector, not when they ask about an existing one. |
 | `18-chrome-mcp.md` | Connect Forge Claude Code sessions to a real Chrome via chrome-devtools-mcp — dev-time browser access for connector authoring |
 | `23-automation-states.md` | Fortinet pipeline automation: GitLab MR stage labels, Mantis status flow, Teams notify policy |
+| `24-watch.md` | Background watches — async polling of long jobs (device upgrade, Jenkins build, test run) that report back in chat. Two triggers: connectors' declarative `async` block, and the `start_watch` builtin the assistant calls on the fly. Where to see/cancel them. |
 
 ## Matching questions to docs
 
@@ -83,3 +84,4 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Job / scheduled job / connector poll / "Jobs tab" → tell user: **Jobs is deprecated**; use Schedules (`13-schedules.md`) instead.
 - Recipe / "From recipe" form / parameterized job → tell user: **recipes deprecated** along with Jobs; fire pipelines manually or via Schedules.
 - Mantis bug fix / fortinet-mantis-bug-fix / open MR for Mantis bug / fortinet-mr-review / pre-review / GitLab stage labels → `23-automation-states.md` (kept Fortinet pipelines)
+- Background watch / "watch this build" / "tell me when the upgrade is done" / progress chip / start_watch / async long job / why is the assistant polling → `24-watch.md`

package/lib/watch/register.ts

@@ -0,0 +1,108 @@
+/**
+ * registerWatch — turn a just-run `async` tool into a background watch.
+ *
+ * Called by the tool-dispatcher right after a tool with an `async` block
+ * runs (and detaches). Resolves the spec's templates against the
+ * trigger's args/result, enforces the global active cap and chain-depth
+ * guard, and persists a watch row. The watch-runner (chat-standalone)
+ * picks it up on the next tick. No dependency on the runner or
+ * tool-dispatcher → no import cycle.
+ */
+
+import type { AsyncWatchSpec } from '../connectors/types';
+import { resolveDeep, resolveTemplate } from './template';
+import { createWatch, countActive, type WatchAction } from './watch-store';
+
+export const MAX_ACTIVE_WATCHES = 50;
+export const DEFAULT_CHAIN_DEPTH = 3;
+const MIN_INTERVAL_SEC = 30;
+const DEFAULT_INTERVAL_SEC = 60;
+const DEFAULT_TIMEOUT_SEC = 1200;
+const DEFAULT_MAX_POLLS = 40;
+
+export interface RegisterWatchCtx {
+  spec: AsyncWatchSpec;
+  connectorId: string;
+  toolName: string;
+  args: Record<string, unknown>;          // trigger tool input
+  result: unknown;                          // trigger tool result (parsed)
+  settings: Record<string, unknown>;
+  sessionId: string | null;
+  chainDepth: number;                       // remaining chain budget
+}
+
+export type RegisterResult =
+  | { ok: true; watch_id: string; label: string }
+  | { ok: false; reason: string };
+
+function num(v: unknown, dflt: number): number {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+export function registerWatch(ctx: RegisterWatchCtx): RegisterResult {
+  const { spec } = ctx;
+  if (!spec || !spec.poll) return { ok: false, reason: 'no async.poll declared' };
+  if (ctx.chainDepth <= 0) return { ok: false, reason: 'chain depth exhausted' };
+  if (countActive() >= MAX_ACTIVE_WATCHES) {
+    return { ok: false, reason: `active watch limit reached (${MAX_ACTIVE_WATCHES})` };
+  }
+
+  // Templating context for register-time resolution.
+  const regCtx = { args: ctx.args, result: ctx.result, settings: ctx.settings };
+
+  const pollArgs = (resolveDeep(spec.poll_args || {}, regCtx) as Record<string, unknown>) || {};
+
+  let doneMatch: { path: string; equals?: string; contains?: string } | null = null;
+  if (spec.done_match && spec.done_match.path) {
+    doneMatch = {
+      path: spec.done_match.path,
+      ...(spec.done_match.equals != null ? { equals: resolveTemplate(String(spec.done_match.equals), regCtx) } : {}),
+      ...(spec.done_match.contains != null ? { contains: resolveTemplate(String(spec.done_match.contains), regCtx) } : {}),
+    };
+  }
+
+  const interval = Math.max(MIN_INTERVAL_SEC, num(spec.interval_sec, DEFAULT_INTERVAL_SEC));
+  const timeout = num(spec.timeout_sec, DEFAULT_TIMEOUT_SEC);
+  const maxPolls = num(spec.max_polls, DEFAULT_MAX_POLLS);
+
+  // Label: connector.tool + a hint (host/lab/ip) pulled from args if present.
+  const hint = ['host', 'lab', 'ip', 'name'].map((k) => ctx.args[k]).find((v) => typeof v === 'string' && v);
+  const label = `${ctx.connectorId}.${ctx.toolName}${hint ? ` ${hint}` : ''}`;
+
+  // Pre-resolve {args.*}/{result.*}/{settings.*} in messages/action-args NOW
+  // (they're fixed at register time). {poll.*}/{poll_count}/{max_polls} are
+  // left literal for the runner to fill per poll — resolveTemplate keeps
+  // tokens whose namespace isn't in the context, so the two passes compose.
+  const preAction = (a: WatchAction | undefined): WatchAction | null => {
+    if (!a) return null;
+    return {
+      ...a,
+      ...(a.message ? { message: resolveTemplate(a.message, regCtx) } : {}),
+      ...(a.args ? { args: resolveDeep(a.args, regCtx) as Record<string, unknown> } : {}),
+    };
+  };
+  const preProgress = spec.progress
+    ? { ...spec.progress, ...(spec.progress.message ? { message: resolveTemplate(spec.progress.message, regCtx) } : {}) }
+    : null;
+
+  const w = createWatch({
+    session_id: ctx.sessionId,
+    label,
+    connector_id: ctx.connectorId,
+    poll_tool: spec.poll,
+    poll_args: pollArgs,
+    done_path: spec.done_path ?? null,
+    done_match: doneMatch,
+    fail_path: spec.fail_path ?? null,
+    on_done: preAction(spec.on_done as WatchAction),
+    on_fail: preAction(spec.on_fail as WatchAction),
+    progress: preProgress,
+    interval_sec: interval,
+    timeout_sec: timeout,
+    max_polls: maxPolls,
+    chain_depth: ctx.chainDepth,
+    now: Date.now(),
+  });
+  return { ok: true, watch_id: w.id, label };
+}

package/lib/watch/start-watch-tool.ts

@@ -0,0 +1,116 @@
+/**
+ * `start_watch` — a builtin tool that lets the LLM register a background
+ * watch on the fly, instead of relying on a connector author's static
+ * `async` block. Use case: the model just triggered a long job (jenkins
+ * build, a test run) and, rather than polling in-conversation (burning
+ * tokens, getting stuck), it calls start_watch to have Forge poll a
+ * given tool until a done/fail condition, then report back in chat.
+ *
+ * This is the dynamic counterpart to manifest `async` blocks — same
+ * watch backend (store + runner + chip), just driven by the model. The
+ * handler closes over the originating session id so completion routes to
+ * the right conversation.
+ */
+
+import type { BuiltinToolDef } from '../chat/tool-dispatcher';
+import { createWatch, countActive } from './watch-store';
+import { MAX_ACTIVE_WATCHES, DEFAULT_CHAIN_DEPTH } from './register';
+
+const MIN_INTERVAL_SEC = 30;
+const DEFAULT_INTERVAL_SEC = 60;
+const DEFAULT_TIMEOUT_SEC = 1800;
+const DEFAULT_MAX_POLLS = 40;
+
+export interface StartWatchTool {
+  def: BuiltinToolDef;
+  handle: (input: unknown) => Promise<string>;
+}
+
+function num(v: unknown, dflt: number): number {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+export function buildStartWatchTool(sessionId: string | null): StartWatchTool {
+  const def: BuiltinToolDef = {
+    name: 'start_watch',
+    description:
+      'Register a BACKGROUND WATCH that polls a tool until done, then posts the result back here — for long-running jobs you just kicked off (a Jenkins build, a test run, a device upgrade). Use this INSTEAD of polling in conversation: call the trigger tool, then call start_watch and STOP — Forge polls in the background and a completion message arrives in this chat. ' +
+      'Pick `poll` = the read tool that reports status (e.g. "jenkins.get_build") and `poll_args` to call it with (e.g. the build number you predicted via get_next_build_number). Give a done condition: `done_match` {path, equals} on the poll result (e.g. path "result" equals "SUCCESS"), or `done_path` (a result path that becomes truthy). You usually already saw the poll tool\'s output once, so you know the right field. Optional `fail_path` (truthy = failed). Tune `interval_sec`/`timeout_sec` to the job (build ≈ 60s / 1800s).',
+    input_schema: {
+      type: 'object',
+      properties: {
+        poll: { type: 'string', description: 'Tool to poll, "<connector>.<tool>" e.g. "jenkins.get_build". Must be a read/status tool.' },
+        poll_args: { type: 'object', description: 'Args to call the poll tool with each tick, e.g. {"job_path":"job/foo","build_number":18}. Concrete values, not templates.' },
+        done_match: {
+          type: 'object',
+          description: 'Done when poll-result <path> equals/contains this. e.g. {"path":"result","equals":"SUCCESS"}.',
+          properties: {
+            path: { type: 'string' },
+            equals: { type: 'string' },
+            contains: { type: 'string' },
+          },
+        },
+        done_path: { type: 'string', description: 'Alternative to done_match: done when this poll-result path is truthy.' },
+        fail_path: { type: 'string', description: 'Optional: poll-result path that, when truthy, means failed.' },
+        message: { type: 'string', description: 'Message posted to chat on completion. May reference {poll.<path>}, e.g. "Build 18 finished: {poll.result}".' },
+        fail_message: { type: 'string', description: 'Optional message on failure/timeout.' },
+        progress_message: { type: 'string', description: 'Optional per-poll status chip text (ambient, not a chat message). e.g. "Build 18 — {poll.result}".' },
+        interval_sec: { type: 'number', description: 'Seconds between polls (default 60, min 30).' },
+        timeout_sec: { type: 'number', description: 'Overall deadline in seconds (default 1800).' },
+        max_polls: { type: 'number', description: 'Hard cap on poll count (default 40).' },
+      },
+      required: ['poll'],
+    },
+  };
+
+  const handle = async (input: unknown): Promise<string> => {
+    const a = (input ?? {}) as Record<string, any>;
+    const poll = String(a.poll || '').trim();
+    const dot = poll.indexOf('.');
+    if (dot < 1) return JSON.stringify({ ok: false, error: 'poll must be "<connector>.<tool>", e.g. jenkins.get_build' });
+    const connectorId = poll.slice(0, dot);
+    const pollTool = poll.slice(dot + 1);
+
+    const doneMatch = a.done_match && typeof a.done_match === 'object' && a.done_match.path
+      ? { path: String(a.done_match.path), ...(a.done_match.equals != null ? { equals: String(a.done_match.equals) } : {}), ...(a.done_match.contains != null ? { contains: String(a.done_match.contains) } : {}) }
+      : null;
+    const donePath = typeof a.done_path === 'string' && a.done_path ? a.done_path : null;
+    if (!doneMatch && !donePath) {
+      return JSON.stringify({ ok: false, error: 'give a done condition: done_match {path,equals} or done_path' });
+    }
+    if (countActive() >= MAX_ACTIVE_WATCHES) {
+      return JSON.stringify({ ok: false, error: `active watch limit reached (${MAX_ACTIVE_WATCHES})` });
+    }
+
+    const hint = ['build_number', 'host', 'ip', 'lab', 'id', 'name'].map((k) => a.poll_args?.[k]).find((v) => v != null && v !== '');
+    const label = `${connectorId}.${pollTool}${hint != null ? ` ${hint}` : ''}`;
+
+    const w = createWatch({
+      session_id: sessionId,
+      label,
+      connector_id: connectorId,
+      poll_tool: pollTool,
+      poll_args: (a.poll_args && typeof a.poll_args === 'object') ? a.poll_args : {},
+      done_path: donePath,
+      done_match: doneMatch,
+      fail_path: typeof a.fail_path === 'string' && a.fail_path ? a.fail_path : null,
+      on_done: { mode: 'chat', message: String(a.message || `${label}: done.`) },
+      on_fail: { mode: 'chat', message: String(a.fail_message || `${label}: did not complete in time — please check.`) },
+      progress: { show: true, ...(a.progress_message ? { message: String(a.progress_message) } : {}) },
+      interval_sec: Math.max(MIN_INTERVAL_SEC, num(a.interval_sec, DEFAULT_INTERVAL_SEC)),
+      timeout_sec: num(a.timeout_sec, DEFAULT_TIMEOUT_SEC),
+      max_polls: num(a.max_polls, DEFAULT_MAX_POLLS),
+      chain_depth: DEFAULT_CHAIN_DEPTH,
+      now: Date.now(),
+    });
+    return JSON.stringify({
+      ok: true,
+      watch_id: w.id,
+      polling: poll,
+      note: 'Background watch registered. STOP polling in conversation — a completion message will arrive in this chat. The user can see/cancel it in the watch list.',
+    });
+  };
+
+  return { def, handle };
+}

package/lib/watch/template.ts

@@ -0,0 +1,40 @@
+/**
+ * Tiny namespaced template resolver for watch specs. Replaces tokens
+ * like {args.x}, {result.fired_at}, {poll.build}, {settings.host} from a
+ * context of namespaces. Dot paths supported. Unknown tokens are left
+ * literal (so a typo is visible rather than silently empty). No eval.
+ */
+
+export function getPath(obj: unknown, path: string): unknown {
+  let v: any = obj;
+  for (const p of path.split('.')) {
+    if (v == null || typeof v !== 'object') return undefined;
+    v = v[p];
+  }
+  return v;
+}
+
+export function resolveTemplate(str: string, ctx: Record<string, unknown>): string {
+  return str.replace(/\{([^{}]+)\}/g, (full, raw) => {
+    const key = String(raw).trim();
+    const dot = key.indexOf('.');
+    const ns = dot < 0 ? key : key.slice(0, dot);
+    const rest = dot < 0 ? '' : key.slice(dot + 1);
+    if (!(ns in ctx)) return full;
+    const v = rest ? getPath(ctx[ns], rest) : ctx[ns];
+    if (v == null) return full;
+    return typeof v === 'object' ? JSON.stringify(v) : String(v);
+  });
+}
+
+/** Resolve templates throughout a value (strings, arrays, plain objects). */
+export function resolveDeep(val: unknown, ctx: Record<string, unknown>): unknown {
+  if (typeof val === 'string') return resolveTemplate(val, ctx);
+  if (Array.isArray(val)) return val.map((v) => resolveDeep(v, ctx));
+  if (val && typeof val === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(val)) out[k] = resolveDeep(v, ctx);
+    return out;
+  }
+  return val;
+}