@aion0/forge 0.10.20 → 0.10.22

package/RELEASE_NOTES.md

@@ -1,8 +1,8 @@
-# Forge v0.10.20
+# Forge v0.10.22
 
 Released: 2026-05-31
 
-## Changes since v0.10.19
+## Changes since v0.10.20
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.19...v0.10.20
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.20...v0.10.22

package/app/api/connectors/route.ts

@@ -65,7 +65,7 @@ function deriveModeLabel(entries: ConnectorEntry[]): 'server-side' | 'browser-si
     }
   }
   if (ps.size === 0) return 'browser-side';
-  const allServer = [...ps].every((p) => p === 'http' || p === 'shell');
+  const allServer = [...ps].every((p) => p === 'http' || p === 'shell' || p === 'ssh');
   const allBrowser = [...ps].every((p) => p === 'browser');
   return allServer ? 'server-side' : allBrowser ? 'browser-side' : 'mixed';
 }

package/docs/forge-long-task-watch-design.md

@@ -0,0 +1,210 @@
+# Forge — Long-Task Watch（轻量独立后台轮询 + 回调编排）设计方案
+
+> 状态：**待审,未实现**。给 zliu 决策用。
+> 一句话定性(zliu)：watch = **在 chat 里支持的一个轻量化异步回调机制**。
+> 消费者:TP 升级、**NAC 直连升级(nac.upgrade → 轮询 nac.get_version 直到
+> build 匹配)**、pytest 跑——凡是"发起后要等、完成再回 chat"的都用它。
+> 起因：TP `upgrade_lab`(NAC 升级)同步阻塞 5-10 分钟。连接器已用
+> `detach` 让它不卡死,但"发起后盯到完成"这步若靠 AI 在对话里轮询,
+> **不可靠**。需要一个**轻量、独立、纯后台**的机制:发起后自动定期 poll,
+> 完成时**回调一个工具**(而非通知用户),全程不依赖 AI / 不依赖对话存活。
+
+## 0. 目标 & 非目标(按 zliu 最新意见收敛)
+
+**目标**
+- 发起即返回,不 hold 对话/标签页。
+- **轻量、独立**:自带一个小 ticker + 一张表,**不挂靠 Schedules**(那是用户
+  预定任务,语义不同),也不新增 standalone 进程。
+- 完成/失败 → **回灌到发起的那个 chat 会话**:把 poll 结果作为一条
+  tool-result/系统事件喂回该 session,**让助手吐一条消息**(并可顺势继续判断/
+  调用下一步工具)。这天然复用 chat:若该会话来自 telegram,消息就自然回到
+  telegram;来自 /chat 就在 /chat 冒出来——**不需要单独的 telegram/email 通道**。
+- (可选)纯编排:也支持声明式 `on_done` 直接调一个工具做链式(升级完→自动
+  run_pytest),不吐消息。两种模式按 manifest 选。
+- **每次 poll 可给轻量进度反馈,但不抢主对话**(zliu):进度走**独立的
+  状态通道**(`watch_status` push),在 chat 里渲染成一个**会就地更新的小状态条/
+  chip**——每 tick 替换、不追加,**不进消息历史、不触发 LLM**,完成即消失。
+  只有最终 `on_done`/`on_fail` 的终态消息才真正落进对话线程。即:
+  **过程 = 环境状态(ambient),结果 = 一条真消息**。
+- **防死循环是一等需求**:后台自动调度最怕失控,必须有硬上限。
+- **极简管理面**:不做常规 UI,但要**一个能看 active watch 列表 + 取消/删除**
+  的地方,避免 watch 堆积、占资源、跑飞。
+
+**非目标**
+- 不做"独立于 chat 之外"的新通知通道——完成消息走发起会话本身的 chat 流。
+- 不做复杂表达式引擎(done 判定走安全的点路径)。
+- 不进 Schedules UI、不算一种 Schedule 类型。
+
+## 1. 形态:独立 `watch` 模块
+
+```
+AI(在 session S)─call─> upgrade_lab ─(detach 25s, 返回 fired_at)─┐
+                                                                  ├─ dispatcher 见 async: registerWatch(..., session_id=S)
+            <── 立即返回 {dispatched, watch_id} ──────────────────┘
+                         …………(对话可结束)…………
+watch ticker(独立, ~30-60s)
+  └ 对每条 active watch,到点:
+      poll_tool ── done_path? ──┬─ 是 → 完成动作 → 终态 done
+                                 ├─ fail_path? → 失败动作 → 终态 failed
+                                 └─ 否 → polls++;超 max_polls / 过 timeout → 终态 timed_out(走失败动作)
+
+完成/失败动作(二选一,按 manifest):
+  • mode=chat(默认):把结果作为 tool-result 回灌 session S → resume 该会话 →
+    助手吐消息(走 chat-standalone 现有的 resume + bridgePush 流;telegram 会话则到 telegram)。
+  • mode=tool:派发声明的 on_done.tool(链式编排,不吐消息)。
+```
+
+- ticker 是一个 `setInterval`(随 **chat-standalone** 起,单实例守卫),**不是新
+  进程**,也**不复用 Schedules tick**——逻辑独立、好推理、好限流。放 chat-standalone
+  里还顺手:回灌 session 用的就是它自己的 resume 能力。
+- registerWatch 记下 `session_id`(发起工具的那个 chat 会话),完成时回灌。
+- watch 是**短生命周期**:到达终态(done/failed/timed_out/cancelled)即停轮询。
+
+## 2. Manifest 声明(连接器侧,新增 `async` 块)
+
+```yaml
+upgrade_lab:
+  destructive: true
+  async:
+    poll: check_lab_upgrade_status        # 同连接器内的查询工具
+    poll_args:                            # 用触发工具的 result/args 拼 poll 入参
+      deployinfo: "{args.deployinfo}"
+      lab: "{args.lab}"
+      since: "{result.fired_at}"          # {result.*}=触发工具返回值;{args.*}=触发入参
+    # 完成判定:二选一。
+    done_path: done                       # (A) poll 结果该路径 truthy = 完成(TP:连接器自己比好返回 done:true)
+    # done_match:                         # (B) 值比较(NAC:get_version 返回 build 号,跟目标比)
+    #   path: captured.build              #     poll 结果里的路径
+    #   equals: "{args.target_build}"     #     equals / contains,期望值从触发 args/result 模板取
+    fail_path: any_failure                # 可选:truthy = 失败
+    interval_sec: 60                      # 轮询间隔(下限 30s)
+    timeout_sec: 1200                     # 总时长上限(到点判 timed_out)
+    max_polls: 40                         # 轮询次数硬上限(防失控)
+    on_done:                              # 完成动作
+      mode: chat                          # chat(默认,回灌发起会话让助手吐消息) | tool(链式) | none(仅落库)
+      message: "升级完成,核对结果。"      # mode=chat 时注入会话的提示(可引用 {poll.*})
+      tool: ""                            # mode=tool 时要调的工具名
+      args: {}                            # mode=tool 入参,可引用 {poll.*}/{args.*}
+    on_fail:                              # 可选,同形(默认 mode=chat,把失败/超时也吐回会话)
+      mode: chat
+      message: "升级未在预期内完成,请手动核对。"
+    progress:                             # 每次 poll 的轻量反馈(不抢主对话)
+      show: true                          # 默认 true;false = 后台静默,只在终态出消息
+      message: "盯升级中… 第 {poll_count}/{max_polls} 次,build={poll.build}"  # 可引用 {poll.*}/{poll_count}
+```
+
+**两条输出通道(关键:进度不抢主对话)**
+- **进度通道**:每 tick 通过独立 push topic `watch_status` 推一条
+  `{watch_id, state, poll_count, text}`。chat 端渲染成一个**就地更新的小状态条/
+  chip**(按 watch_id 去重替换,不追加),**不写入消息历史、不触发 LLM、不计入
+  上下文**;watch 一到终态该状态条自动消失/收起。这样轮询再多也不污染对话。
+- **结果通道**:只有 `on_done`/`on_fail`(mode=chat)产出**一条真消息**进对话
+  线程。`progress.show:false` 则全程静默,只留终态。
+- 实现:进度走 `bridgePush('watch_status', …)`(extension/web 各加一个轻量
+  status-bar 组件订阅);结果走已有的 session resume 回灌(§1)。
+
+- **完成回灌 chat**:默认 `mode=chat`——把最后一次 poll 结果 + `message` 作为
+  tool-result 喂回发起的 session,助手据此吐一条消息(还能继续调用下一步)。
+  `mode=tool` 则纯链式派发工具、不吐消息;`mode=none` 只落库置终态(AI 下次
+  需要时可查)。tool 模式走和 chat 同一条 dispatcher,可链式。
+- **done 判定不用 eval**:`done_path`/`fail_path` 点路径取真值;`done_match`
+  做 equals/contains 比较(期望值模板取),都不跑 eval、零注入面。
+
+NAC 直连升级的 async 块(第二个消费者,用 done_match):
+```yaml
+upgrade:            # nac connector
+  async:
+    poll: get_version
+    poll_args: {}                 # get_version 无参,连 settings 里的 host 即可
+    done_match: { path: build, equals: "{args.target_build}" }  # build6957 → "6957"
+    interval_sec: 60
+    timeout_sec: 900              # 含 reboot,放宽
+    on_done: { mode: chat, message: "NAC {settings.host} 已升级到 build {poll.build}。" }
+```
+注:`nac.upgrade` 目前参数没有 target_build——接 watch 时给它加一个(或从
+镜像文件名 `build(\d+)` 自动解析),传给 watch 做比较。
+
+## 3. 防死循环(纯后台调度的核心约束)
+
+| 失控源 | 护栏 |
+|---|---|
+| 轮询永不停 | `max_polls`(默认 40)+ `timeout_sec`(默认 1200s),先到先终止 |
+| 同一 watch 并发重入 | **单飞**:每条 watch 有 `running` 锁,上一次 poll 没回来不发下一次 |
+| 回调再生回调(A→B→A) | 回调链 `chain_depth` 上限(默认 3)+ 已访问 watch 链路环检测 |
+| 回调本身又是 async 工具 | 允许,但继承并递减 `chain_depth`;到 0 则只跑、不再登记新 watch |
+| watch 越堆越多 | 全局 active watch 上限(默认 50);超了拒绝新登记并在触发工具结果里报错 |
+| poll 报错刷屏 | 连续 N 次错误(默认 5)→ 终态 `errored`,不再重试 |
+| 僵尸 watch | 任何 watch 硬性 `max_lifetime`(默认 2×timeout)兜底清理 |
+
+所有上限都有**默认值**且 manifest 可调小,不可调到无界。
+
+## 4. 重启不丢
+
+- watch **持久化在 SQLite**(`connector_watches`),不是内存。
+- Forge 重启/崩溃 → ticker 起来后扫 `state=active` 的 watch,凭存下的
+  `fired_at`/`next_poll_at`/`polls` 续轮询,**不靠 AI、不靠原对话**。
+- 宕机超过 `max_lifetime` 的 watch → 标 `timed_out`、跑 `on_fail`(若有),
+  绝不静默丢。
+
+## 5. 极简管理面(防资源占用 / 可取消)
+
+不做常规 UI,但提供**最小可观测+可控**:
+
+- **API**:`GET /api/watches`(列 active+近期终态)、`POST /api/watches/:id/cancel`、
+  `DELETE /api/watches/:id`。
+- **UI 落点**(二选一,倾向 A):
+  - **A. Settings → Monitor** 加一个 "Background Watches" 折叠区:每行显示
+    connector·poll_tool·polls/max·下次轮询·状态,带 Cancel/Delete。和已有
+    进程监控同处,零新页面。
+  - **B.** /chat 侧栏一个折叠小列表。
+- cancel = 立即置 `cancelled` 终态、停轮询;delete = 删行。
+
+## 6. 改动清单
+
+| 在哪 | 改什么 | 量 |
+|---|---|---|
+| 类型 | `lib/connectors/types.ts`:`ConnectorTool.async?: AsyncWatchSpec`(poll/poll_args/done_path/done_match/fail_path/interval/timeout/max_polls/on_done/on_fail/**progress**) | 小 |
+| 存储 | `lib/watch/watch-store.ts`(新):SQLite 表 + CRUD + 单实例守卫 | ~100 行 |
+| 轮询 | `lib/watch/watch-runner.ts`(新):独立 ticker，单飞、护栏、终态机、调 poll/回调、**每 tick `bridgePush('watch_status',…)`** | ~170 行 |
+| 派发 | `lib/chat/tool-dispatcher.ts`:跑完带 `async` 的工具 → `registerWatch`,返回附 `watch_id` | 小 |
+| API | `app/api/watches/route.ts` + `[id]`:list / cancel / delete | 小 |
+| UI(状态条) | extension + /chat 各加一个轻量组件,订阅 `watch_status` push → 渲染就地更新的 chip(不进消息流) | 小 |
+| UI(管理面) | Settings Monitor 加 Background Watches 折叠区(只读+cancel/delete) | 小 |
+| 连接器 | `upgrade_lab`/`upgrade_device` 加 `async:` 块 | 几行 |
+
+**主体在 Forge**(类型+store+runner+API+UI);连接器只加声明块。**不复用
+Schedules、不新增进程**——独立轻量,正合你要的形态。
+
+## 7. TP 落地体验(后台轮询 + 完成回灌 chat)
+
+```
+用户:升级 AT16_Combined_FSW 到 build6957
+AI  :upgrade_lab(command=…) → {dispatched, watch_id, fired_at}
+AI  :「已发起,后台盯到完成会在这里告诉你。」← 对话可结束/去忙别的
+（后台 ticker 每 60s poll check_lab_upgrade_status(since=fired_at)，无 AI 参与）
+done:true → 回灌 session S → 助手在原会话吐:
+  「✅ AT16_Combined_FSW 升级完成,FortiNAC(10.15.52.152)已到 build6957。」
+（若该会话是 telegram,这条就到 telegram;是 /chat 就在 /chat 冒出来。
+  若配了 on_done.mode=tool,则改为自动跑 run_pytest,不吐消息。）
+```
+
+## 8. 工作量
+
+- Forge:store + runner + dispatcher 钩子 + API + Monitor 区 ≈ **1~1.5 天**
+  (护栏/单飞/重启续跑要写稳)。
+- 连接器:几行。
+
+## 9. 待你决策
+
+- [x] UI:不做常规 UI,但有**极简管理面**(列表+cancel/delete),落点倾向
+      Settings→Monitor 的折叠区。
+- [x] 重启不丢:SQLite 持久化,续跑;超期回灌/回调,不静默丢。
+- [x] 完成动作:默认 **mode=chat 回灌发起会话让助手吐消息**(telegram 会话→telegram,
+      /chat→/chat);可选 mode=tool 纯链式、mode=none 仅落库。**不**另起独立通知通道。
+- [x] 进度反馈:每 tick 走独立 `watch_status` push,渲染成**就地更新的状态条/chip,
+      不进消息流、不触发 LLM**;只有终态出一条真消息。`progress.show` 可关。
+- [ ] **是否实现?**
+- [ ] 管理面落点 A(Settings→Monitor)还是 B(/chat 侧栏)? 右上角菜单下有个 watch 按钮
+- [ ] 回调链深度 / active 上限 / max_polls 默认值是否认可(3 / 50 / 40)?
+- [ ] mode=chat 回灌时,助手是"只吐一条总结消息"还是"可继续自主调用工具"(后者更强但要纳入防循环上限)? 
+  - 只回总结吧，终止，然后由 chat决定吧。不用做嵌套，因为本身就是异步跟踪了，就可以一直获取。如果真的需要嵌套就设置一个嵌套数量吧，

package/docs/tp-automation-api.md

@@ -0,0 +1,617 @@
+# TP `/automation` Page — API Reference
+
+Reference for the HTTP endpoints used by TP's Automation page
+(`/automation`, source: `frontend/src/pages/Automation/Automation.jsx`)
+and the related upgrade / testbed workflows the page invokes through
+shared infrastructure.
+
+All endpoints are mounted under the `adc` Django app:
+
+```
+<TP-base-url>/adc/<endpoint>
+```
+
+`<TP-base-url>` examples:
+- Production: `https://nac-tp.fortinet-us.com`
+- Test:       `http://10.15.33.25:8000`
+- Dev (.11):  `http://10.15.33.11:8000`
+
+## Authentication
+
+Every endpoint requires a JWT in the `Authorization` header:
+
+```
+Authorization: JWT <token>
+```
+
+Mint a token:
+
+```bash
+T=$(curl -s -X POST <TP-base-url>/token-auth/ \
+       -H 'Content-Type: application/json' \
+       -d '{"username":"<user>","password":"<pw>"}' | jq -r .token)
+```
+
+In the examples below, `$T` stands for the JWT. Tokens are
+short-lived; on 401 the frontend redirects to SSO, and scripts should
+re-mint.
+
+---
+
+## Endpoints called by the `/automation` page
+
+### `GET /adc/automation-verion/`
+
+Returns the FortiNAC versions the automation pipeline tracks.
+Populates the version dropdown.
+
+Response:
+```json
+{"versions": ["7.4.6", "7.4.7", "7.6.5", "7.6.6"]}
+```
+
+Backed by: `adc.views.dashboard.dashboardviews.get_automation_version`
+
+### `GET /adc/get_testcases`
+
+Walks the cloned test-framework repo on TP, parses every Python test
+file, and returns a hierarchical tree of modules → test cases.
+
+**Side-effect:** pulls latest commits on the `main` branch of the local
+clone before parsing. Calling from a script will rebase TP's local
+repo on `main` — fine in normal use, but worth knowing if a developer
+is hand-testing branches on the TP host.
+
+Response shape (truncated):
+```json
+{
+  "tests": {
+    "L2": {
+      "test_l2_radius.py": [
+        "test_basic_auth",
+        "test_radius_attributes"
+      ]
+    },
+    "L3": {}
+  }
+}
+```
+
+Backed by: `automationview.get_testcases`
+
+### `POST /adc/pytest_run`
+
+Kicks off a pytest execution on the chosen automation testbed. Creates
+a `PytestExecution` row and returns its id; the actual run is
+asynchronous.
+
+Body:
+```json
+{
+  "user":     "alice",
+  "lab":      "L2Mode_7",
+  "testcase": [
+    "tests/L2/test_l2_radius.py::test_basic_auth",
+    "tests/L2/test_l2_radius.py::test_radius_attributes"
+  ],
+  "argument": "-k 'radius and not flaky' --tb=short -vv"
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `user` | string | TP username of the caller. |
+| `lab` | string | AT lab name from `AutomationTBUser` (the same names returned by `get_automation_lab`). Comma-separate multiple labs (`"L2Mode_7,L2Mode_9"`). The caller must already own or be a member of `usedby` on the lab, and no other execution can be `Running`/`Initiating` against it. |
+| `testcase` | **list of strings** | Each entry is a pytest test-id path. The handler iterates the list, prefixes each with the test-framework repo path on TP, and joins them with spaces before invoking pytest. |
+| `argument` | string | **Raw pytest CLI arguments**, injected verbatim between the testcase paths and the framework's `--html=...`/`--rack-file ...` flags. Use this for filters, verbosity, fail-fast, collect-only, marker expressions, etc. |
+
+The handler also accepts any **extra** fields in the body — they're
+preserved on the execution record. You can attach tracking metadata
+(`mantis_id`, `jenkins_job`, etc.) without backend changes.
+
+#### What gets executed on the testbed
+
+The worker generates a shell script of the form:
+
+```bash
+git pull origin main
+cd <repo>
+source venv/bin/activate
+export PYTHONPATH=<test-framework>:<tests>
+export DISPLAY=:99
+pytest <testcase paths> <argument> --collect-only
+pytest <testcase paths> <argument> --html=<report> --rack-file <rack> <pytest_options>
+```
+
+So `argument` is literally the slot for any pytest flag. The worker
+runs `--collect-only` first as a dry-run check, then the real run.
+
+#### Examples
+
+**Run one test:**
+```json
+{
+  "user":     "alice",
+  "lab":      "L2Mode_7",
+  "testcase": ["tests/L2/test_l2_radius.py::test_basic_auth"],
+  "argument": ""
+}
+```
+
+**Run several specific tests, with verbose output and fail-fast:**
+```json
+{
+  "user":     "alice",
+  "lab":      "L2Mode_7",
+  "testcase": [
+    "tests/L2/test_l2_radius.py::test_basic_auth",
+    "tests/L3/test_l3_vpn.py::test_vpn_login"
+  ],
+  "argument": "-vv -x"
+}
+```
+
+**Run every test in a file, filtered by keyword:**
+```json
+{
+  "user":     "alice",
+  "lab":      "L2Mode_7",
+  "testcase": ["tests/L2/test_l2_radius.py"],
+  "argument": "-k 'radius and not flaky'"
+}
+```
+
+**Dry-run / list-only (no test bodies executed by the second pytest invocation):**
+```json
+{
+  "user":     "alice",
+  "lab":      "L2Mode_7",
+  "testcase": ["tests/L2/"],
+  "argument": "--collect-only"
+}
+```
+
+(Note: `--collect-only` runs twice in this case — once by the worker's
+hardcoded first-line check, once by your explicit flag. Functionally
+identical to a normal collect-only.)
+
+#### Response
+
+```json
+{"exec_id": "53"}
+```
+Or on error:
+```json
+{"error": "..."}
+```
+
+On lab conflict (someone else's run is in progress on that lab), the
+response contains `conflict_labs` and `usable_labs` instead of
+`exec_id`.
+
+Backed by: `automationview.pytest_run` → `PytestAction.create_execution_entry`
+
+### `POST /adc/get_automation_lab`
+
+Lists the automation testbeds the calling user can see (owned or
+shared). Each entry includes a live `status` field computed from
+in-progress executions.
+
+Body:
+```json
+{"user": "alice"}
+```
+
+Response (truncated):
+```json
+[
+  {
+    "name": "L2Mode_7",
+    "usedby": "alice,bob",
+    "status": "Available"
+  }
+]
+```
+
+`status` is `"Running"` when any `PytestExecution` for this lab has
+status `Running`, else `"Available"`.
+
+### `POST /adc/get_test_result`
+
+Returns the calling user's recent test executions with computed
+progress percentages.
+
+Body:
+```json
+{"user": "alice"}
+```
+
+Response:
+```json
+[
+  {
+    "id":               53,
+    "name":             "test001",
+    "report_file_path": "media/automation/53/report.html",
+    "log_file_path":    "media/automation/53/log.txt",
+    "status":           "Running",
+    "progress":         42
+  }
+]
+```
+
+`progress = (pass + fail + skip + error) / total * 100`, rounded.
+
+`report_file_path` and `log_file_path` are server-relative; open them
+by prepending `<TP-base-url>` and sending the JWT.
+
+### `POST /adc/get_test_execution_by_id`
+
+Returns one execution's full record (steps, counts, environment,
+timestamps) for the detail panel.
+
+Body:
+```json
+{"id": 53}
+```
+
+Response: serialized `PytestExecution`. Returns 404 if not found.
+
+### `POST /adc/test_exec_kill`
+
+Aborts a running execution. The row stays in the DB with a terminal
+status; the underlying pytest subprocess is sent SIGTERM.
+
+Body:
+```json
+{"id": 53}
+```
+
+### `POST /adc/test_exec_delete`
+
+Deletes one or many `PytestExecution` rows and their on-disk
+artifacts. Accepts either a single id or a list.
+
+Body (single):
+```json
+{"id": 53}
+```
+
+Body (bulk):
+```json
+{"historyresults": [50, 51, 52]}
+```
+
+### `POST /adc/automation_lock`
+
+Marks a testbed as in-use, or releases it. Used to serialize tests
+that need exclusive access to shared hardware.
+
+Body:
+```json
+{"action": "lock", "user": "alice", "name": "L2Mode_7"}
+```
+
+`action` is `"lock"` or `"unlock"`.
+
+### `POST /adc/automation_tb_set_viewers/`
+
+Edits who can *see* a testbed (separate from ownership/usage).
+
+Body:
+```json
+{
+  "action":  "add",
+  "tb_name": "L2Mode_7",
+  "viewers": ["bob", "carol"]
+}
+```
+
+`action` is `"add"`, `"remove"`, or `"set"`.
+
+### `GET /adc/status-check/`
+
+Generic shared-lab status payload used by the status widget rendered
+on the page. Not specific to automation but called from it.
+
+Backed by: `adc.views.sharedlab.tbviews.ClassicCombinedStatus`
+
+### `GET /user/get_user/<username>`
+
+Returns the calling user's profile (role, group, default project) so
+the page can decide what controls to render. Note: outside the `adc`
+namespace.
+
+---
+
+## NAC upgrade APIs
+
+The `/automation` page does not call these directly, but every
+automation run that targets a specific build relies on the testbed
+having been upgraded first. There are **two modes** of upgrade:
+
+| Mode | What it targets | Endpoints |
+|---|---|---|
+| **Device mode** | One specific `ip` | `nac-upgrade/`, `nac-upgrade-version-snapshot/`, `nac-upgrade-snapshot/`, `check-upgrade-status/` |
+| **Testbed mode** | Every NAC/NCM device in a testbed (discovered from `deployinfo`) | `nac-upgrade-testbed/` |
+
+Both modes share the same `upgrade_type` axis:
+
+| `upgrade_type` | Required extra field | Meaning |
+|---|---|---|
+| `GA`      | (none)              | Pull the latest GA image from the build server |
+| `build`   | `build_number`      | Download a specific build (e.g. `7.6.6.0123`) and install it |
+| `file`    | `file_uploaded` (multipart) | Install from an uploaded image |
+| `command` | `command`           | Run a raw upgrade CLI command (advanced/manual) |
+
+Upgrade work is **asynchronous** in both modes — the call returns once
+the job is queued. Use the device-mode status endpoint to poll.
+
+### Device mode
+
+#### `POST /adc/nac-upgrade/`
+
+Upgrade a single FortiNAC device. Accepts `multipart/form-data` so it
+can carry the uploaded image file.
+
+Form fields:
+- `ip` — target device IP (required)
+- `upgrade_type` — `GA` / `build` / `file` / `command`
+- `build_number` — when `upgrade_type=build`
+- `file_uploaded` — when `upgrade_type=file` (image file as multipart)
+- `command` — when `upgrade_type=command`
+
+Response:
+```json
+{"status": "success", "message": "..."}
+```
+HTTP `202` on success, `400` on failure.
+
+Backed by: `nacviews.nac_upgrade`
+
+#### `POST /adc/nac-upgrade-version-snapshot/`
+
+Take a pre-upgrade snapshot of the device's current image so it can be
+reverted later. Returns once the snapshot job has been queued.
+
+Body:
+```json
+{
+  "ip":            "10.15.40.42",
+  "dev_name":      "fortinac01",
+  "build_number":  "7.6.6.0123",
+  "upgrade_type":  "build",
+  "major_version": "7.6",
+  "minor_version": "6",
+  "rp_prefix":     "rp",
+  "command":       "<optional, when upgrade_type=command>"
+}
+```
+
+Backed by: `nacupgradeview.nac_upgrade_version_snapshot`
+
+#### `POST /adc/nac-upgrade-snapshot/`
+
+Upgrade *with* automatic snapshot/revert. Same payload as
+`nac-upgrade-version-snapshot/` plus:
+
+- `revert_snapshot` — `true` / `false`; when `true`, the device is
+  reverted to the snapshot if the upgrade fails.
+
+Backed by: `nacupgradeview.nac_upgrade_snapshot`
+
+#### `POST /adc/check-upgrade-status/`
+
+Poll the upgrade status of a single device.
+
+Body:
+```json
+{"ip": "10.15.40.42"}
+```
+
+Response: state of the most recent upgrade task for that IP. Shape:
+```json
+{
+  "is_upgrading":       false,
+  "last_task_status":   "SUCCESS",
+  "last_task_type":     "build",
+  "last_build_number":  "7.6.6.0123",
+  "last_image_name":    "FortiNAC-F-7.6.6.0123.out",
+  "last_major_version": "7.6",
+  "last_minor_version": "6",
+  "updated_at":         "2026-05-28T11:42:01.123456+00:00",
+  "log":                "...full log tail...",
+  "ip":                 "10.15.40.42"
+}
+```
+
+`is_upgrading` is `true` when `last_task_status` is `PENDING` or
+`PROGRESS`. The endpoint works for both modes — see the table at the
+top of the section for which testbed-mode `upgrade_type`s actually
+write to this table — but read the polling caveats below carefully.
+
+##### Polling caveat — testbed-mode `build`
+
+`run_download_async` (the worker that handles `upgrade_type=build` in
+testbed mode) does **not** set `last_task_status` to `PENDING` or
+`PROGRESS` while running. It only writes `SUCCESS` on completion.
+Effect: while a testbed-mode build upgrade is in flight,
+`is_upgrading` returns `false` even though the worker is actively
+downloading + restoring on the device.
+
+To get live progress mid-run for testbed-mode build upgrades, read
+the `log` field instead — `run_download_async` appends to it
+continuously (download start, restore start, VM CLI output, success).
+
+> **Known bug (worth fixing as a separate task):** `run_download_async`
+> in `backend/adc/views/sharedlab/nacviews.py` should set
+> `last_task_status = "PROGRESS"` immediately after `get_or_create`
+> at the start of the worker, and `"FAILURE"` in its `except` branch
+> (it currently only writes `"SUCCESS"` on the happy path). With that
+> fix, `check-upgrade-status/` would return an accurate `is_upgrading`
+> flag for testbed-mode build upgrades and surface failures without
+> requiring the caller to parse the log field.
+
+##### Polling caveat — testbed-mode `GA`
+
+`upgrade_type=GA` in `nac_upgrade_testbed` is a stub — it returns
+`{"upgrade_type": "GA"}` immediately and never touches `SingleDevice`.
+This endpoint will report `"Device not found"` (404) for IPs that have
+never been upgraded by another mode. There is no work to poll.
+
+##### Polling caveat — testbed-mode `file` and `command`
+
+These branches run synchronously inside the HTTP request and only
+write to `SingleDevice` *after* the work finishes. The request itself
+blocks until then (file restore can take minutes), so polling
+`check-upgrade-status/` for in-flight progress isn't useful for these
+types — by the time you can issue a separate poll, the upgrade is
+already done.
+
+Backed by: `nacupgradeview.check_upgrade_status`
+
+### Testbed mode
+
+#### `POST /adc/nac-upgrade-testbed/`
+
+Upgrade every NAC/NCM device in a testbed at once. Accepts
+`multipart/form-data` to carry an optional uploaded image.
+
+The handler reads `deployinfo` (JSON), finds every key matching
+`dev<N>` whose value contains `nac` or `ncm`, and pairs it with the
+corresponding `ip<N>` to build the upgrade list — then runs the
+chosen `upgrade_type` against each in parallel.
+
+Form fields:
+- `deployinfo` — JSON string with the testbed's device map. Shape:
+  `{"dev1":"fortinac01","ip1":"10.15.40.42","dev2":"ncm01","ip2":"10.15.40.43", ...}`
+  (same as `AutomationTBSerializer.deployinfo`)
+- `upgrade_type` — `GA` / `build` / `file` / `command`
+- `build_number` — when `upgrade_type=build`
+- `file_uploaded` — when `upgrade_type=file`
+- `command` — when `upgrade_type=command`
+
+Response:
+```json
+{"upgrade_type": "build"}
+```
+
+To monitor progress, poll `check-upgrade-status/` per-IP for each NAC
+in the testbed.
+
+Backed by: `nacviews.nac_upgrade_testbed`
+
+### Diagnostic
+
+#### `POST /adc/test_thread_db/`
+
+Diagnostic helper that exercises threaded DB writes against the
+`SingleDevice` model — used to verify upgrade-worker threading on a
+host. Not used by the UI; do not call in production.
+
+Backed by: `nacupgradeview.test_thread_db`
+
+---
+
+## Other related APIs the `/automation` workflow touches
+
+These belong to other pages (Shared Lab, Automation Testbed) but are
+part of the same domain. Listed here so the dev team can find them
+without spelunking.
+
+### Automation testbed management — `adc.views.automation.automation_tbview`
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/adc/create_automation_testbed/` | POST | Create a new automation testbed entry |
+| `/adc/automationtb-list/` | POST | List testbeds by `category` + `keyword` filter |
+| `/adc/automationtb-moduletitle/` | GET | Distinct module titles across testbeds (dropdown source) |
+| `/adc/automationtb-update/` | POST | Update a testbed's metadata, `deployinfo`, or `new_name` |
+
+### Performance lab (parallel of automation, used by `/performance`)
+
+Mirror endpoints exist for performance-test workflows; they share the
+same shape as the automation ones above. Listed for completeness in
+case the dev team needs to script performance runs the same way.
+
+| Endpoint | Method | Mirrors |
+|---|---|---|
+| `/adc/get_perf_testcases/` | GET | `get_testcases` |
+| `/adc/get_perf_testcases_module/` | GET | (module-level filter) |
+| `/adc/perf_robot_run/` | POST | `pytest_run` (Robot Framework instead of pytest) |
+| `/adc/get_perf_lab/` | POST | `get_automation_lab` |
+| `/adc/get_perf_test_result/` | POST | `get_test_result` |
+| `/adc/get_perf_test_execution_by_id/` | POST | `get_test_execution_by_id` |
+| `/adc/performance_lock/` | POST | `automation_lock` |
+| `/adc/perf_exec_kill/` | POST | `test_exec_kill` |
+| `/adc/perf_exec_delete/` | POST | `test_exec_delete` |
+
+---
+
+## Quick smoke test from the command line
+
+```bash
+T=$(curl -s -X POST http://10.15.33.11:8000/token-auth/ \
+       -H 'Content-Type: application/json' \
+       -d '{"username":"admin","password":"<your-pw>"}' | jq -r .token)
+
+# 1. Pull versions
+curl -s -H "Authorization: JWT $T" \
+     http://10.15.33.11:8000/adc/automation-verion/ | jq .
+
+# 2. List your testbeds
+curl -s -X POST -H "Authorization: JWT $T" \
+     -H 'Content-Type: application/json' \
+     -d '{"user":"admin"}' \
+     http://10.15.33.11:8000/adc/get_automation_lab | jq '.[] | {name, status}'
+
+# 3. Fire a pytest run
+EXEC_ID=$(curl -s -X POST -H "Authorization: JWT $T" \
+     -H 'Content-Type: application/json' \
+     -d '{
+           "user":"admin",
+           "lab":"L2Mode_7",
+           "testcase":["tests/L2/test_l2_radius.py::test_basic_auth"],
+           "argument":"-vv"
+         }' \
+     http://10.15.33.11:8000/adc/pytest_run | jq -r .exec_id)
+echo "Started exec $EXEC_ID"
+
+# 4. Poll progress
+curl -s -X POST -H "Authorization: JWT $T" \
+     -H 'Content-Type: application/json' \
+     -d "{\"id\":$EXEC_ID}" \
+     http://10.15.33.11:8000/adc/get_test_execution_by_id | jq .status,.progress
+
+# 5. Upgrade a NAC device to a specific build (out-of-band)
+curl -s -X POST -H "Authorization: JWT $T" \
+     -F "ip=10.15.40.42" \
+     -F "upgrade_type=build" \
+     -F "build_number=7.6.6.0123" \
+     http://10.15.33.11:8000/adc/nac-upgrade/
+
+# 6. Poll upgrade status
+curl -s -X POST -H "Authorization: JWT $T" \
+     -H 'Content-Type: application/json' \
+     -d '{"ip":"10.15.40.42"}' \
+     http://10.15.33.11:8000/adc/check-upgrade-status/ | jq .
+```
+
+---
+
+## Source files
+
+| Concern | File |
+|---|---|
+| URL routes | `backend/adc/urls.py` |
+| Run / lab / lock | `backend/adc/views/automation/automationview.py` |
+| Testbed management | `backend/adc/views/automation/automation_tbview.py` |
+| FortiNAC upgrade (single device + testbed) | `backend/adc/views/sharedlab/nacviews.py` |
+| Upgrade with snapshot / status polling | `backend/adc/views/sharedlab/nacupgradeview.py` |
+| Status widget | `backend/adc/views/sharedlab/tbviews.py` |
+| Version dropdown | `backend/adc/views/dashboard/dashboardviews.py` |
+| Frontend page | `frontend/src/pages/Automation/Automation.jsx` |
+
+When adding a new endpoint, follow the pattern: route in
+`adc/urls.py` → handler in the appropriate view module → serializer
+if returning a model → consumer in `Automation.jsx`.

package/lib/browser-bridge-standalone.ts

@@ -48,6 +48,11 @@ import { randomUUID, createHash } from 'node:crypto';
 const PORT = Number(process.env.BRIDGE_PORT) || 8407;
 const FORGE_PORT = Number(process.env.PORT) || 8403;
 const RPC_TIMEOUT_MS = 60_000;
+// Ceiling for per-call overrides. Kept just under undici's default 300s
+// headersTimeout on the loopback fetch in bridge-client.ts — past that the
+// client fetch dies first with an opaque error. Genuinely long backend work
+// (multi-minute NAC upgrades) should fire-and-poll, not hold the RPC open.
+const RPC_TIMEOUT_MAX_MS = 280_000;
 const TOKEN_CACHE_TTL_MS = 60_000;
 
 // ─── Forge-token validation (with short-lived cache) ──────
@@ -112,17 +117,21 @@ interface PendingRpc {
 
 const pendingRpcs = new Map<string, PendingRpc>(); // rpc_id → callbacks
 
-function callExtension(method: string, params: unknown): Promise<unknown> {
+function callExtension(method: string, params: unknown, timeoutMs?: number): Promise<unknown> {
   const client = pickAnyClient();
   if (!client) {
     return Promise.reject(new Error('No extension connected to the bridge.'));
   }
   const id = randomUUID();
+  const effectiveTimeout = Math.min(
+    Math.max(1000, Number(timeoutMs) || RPC_TIMEOUT_MS),
+    RPC_TIMEOUT_MAX_MS,
+  );
   return new Promise<unknown>((resolve, reject) => {
     const timer = setTimeout(() => {
       pendingRpcs.delete(id);
-      reject(new Error(`RPC ${method} timed out after ${RPC_TIMEOUT_MS / 1000}s`));
-    }, RPC_TIMEOUT_MS);
+      reject(new Error(`RPC ${method} timed out after ${effectiveTimeout / 1000}s`));
+    }, effectiveTimeout);
     pendingRpcs.set(id, { resolve, reject, timer });
     client.ws.send(JSON.stringify({ type: 'rpc_request', id, method, params }));
   });
@@ -248,7 +257,7 @@ async function handleHttp(req: IncomingMessage, res: ServerResponse): Promise<vo
   if (req.method === 'POST' && url.pathname === '/api/rpc') {
     try {
       const body = JSON.parse(await readBody(req));
-      const value = await callExtension(body.method, body.params);
+      const value = await callExtension(body.method, body.params, body.timeout_ms);
       return sendJson(res, 200, { ok: true, value });
     } catch (e) {
       return sendJson(res, 200, { ok: false, error: (e as Error).message });

package/lib/chat/agent-loop.ts

@@ -308,9 +308,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[] = [];

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,
@@ -522,6 +523,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
@@ -559,6 +572,8 @@ export async function dispatchTool(
         return await runHttp({ tool: located.tool, settings: effectiveSettings, args: argInput, connectorAuth: def.auth, noTruncation: opts.noTruncation });
       case 'shell':
         return await runShell({ tool: located.tool, settings: effectiveSettings, args: argInput });
+      case 'ssh':
+        return await runSsh({ tool: located.tool, settings: effectiveSettings, args: argInput });
       case 'browser': {
         // Hand the whole connector + tool spec + input + settings to the
         // extension's runner.ts via the bridge. The extension keeps owning
@@ -570,7 +585,7 @@ export async function dispatchTool(
           input: argInput,
           connector,
           settings: effectiveSettings,
-        })) as { content?: string; is_error?: boolean } | null;
+        }, located.tool.timeout_ms)) as { content?: string; is_error?: boolean } | null;
         return { content: result?.content ?? '(no content returned)', is_error: !!result?.is_error };
       }
       default:

package/lib/connectors/types.ts

@@ -14,7 +14,56 @@
 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;
+}
+
+/**
+ * `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 +219,18 @@ 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;
+
+  /**
+   * 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.10.20",
+  "version": "0.10.22",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {