agent-steward 0.0.0-stage → 0.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +376 -0
- package/CROSS_PLATFORM.md +149 -0
- package/LICENSE +21 -0
- package/README.md +314 -2
- package/ROADMAP-STRATEGY.md +147 -0
- package/ROADMAP.md +1069 -0
- package/dist/core/analytics.d.ts +132 -0
- package/dist/core/analytics.d.ts.map +1 -0
- package/dist/core/analytics.js +290 -0
- package/dist/core/audit.d.ts +96 -0
- package/dist/core/audit.d.ts.map +1 -0
- package/dist/core/audit.js +297 -0
- package/dist/core/cron-to-schtasks.d.ts +20 -0
- package/dist/core/cron-to-schtasks.d.ts.map +1 -0
- package/dist/core/cron-to-schtasks.js +250 -0
- package/dist/core/dry-run.d.ts +102 -0
- package/dist/core/dry-run.d.ts.map +1 -0
- package/dist/core/dry-run.js +447 -0
- package/dist/core/file-watcher.d.ts +31 -0
- package/dist/core/file-watcher.d.ts.map +1 -0
- package/dist/core/file-watcher.js +186 -0
- package/dist/core/git-trigger.d.ts +82 -0
- package/dist/core/git-trigger.d.ts.map +1 -0
- package/dist/core/git-trigger.js +312 -0
- package/dist/core/glob.d.ts +38 -0
- package/dist/core/glob.d.ts.map +1 -0
- package/dist/core/glob.js +233 -0
- package/dist/core/local-ai.d.ts +52 -0
- package/dist/core/local-ai.d.ts.map +1 -0
- package/dist/core/local-ai.js +119 -0
- package/dist/core/lock.d.ts +57 -0
- package/dist/core/lock.d.ts.map +1 -0
- package/dist/core/lock.js +195 -0
- package/dist/core/matrix.d.ts +167 -0
- package/dist/core/matrix.d.ts.map +1 -0
- package/dist/core/matrix.js +724 -0
- package/dist/core/native-notify.d.ts +36 -0
- package/dist/core/native-notify.d.ts.map +1 -0
- package/dist/core/native-notify.js +113 -0
- package/dist/core/one-shot.d.ts +68 -0
- package/dist/core/one-shot.d.ts.map +1 -0
- package/dist/core/one-shot.js +139 -0
- package/dist/core/otel.d.ts +4 -0
- package/dist/core/otel.d.ts.map +1 -0
- package/dist/core/otel.js +98 -0
- package/dist/core/permissions.d.ts +69 -0
- package/dist/core/permissions.d.ts.map +1 -0
- package/dist/core/permissions.js +143 -0
- package/dist/core/prometheus.d.ts +23 -0
- package/dist/core/prometheus.d.ts.map +1 -0
- package/dist/core/prometheus.js +146 -0
- package/dist/core/ps-wrapper.d.ts +73 -0
- package/dist/core/ps-wrapper.d.ts.map +1 -0
- package/dist/core/ps-wrapper.js +1071 -0
- package/dist/core/record-history.d.ts +25 -0
- package/dist/core/record-history.d.ts.map +1 -0
- package/dist/core/record-history.js +471 -0
- package/dist/core/retention.d.ts +29 -0
- package/dist/core/retention.d.ts.map +1 -0
- package/dist/core/retention.js +98 -0
- package/dist/core/savings.d.ts +70 -0
- package/dist/core/savings.d.ts.map +1 -0
- package/dist/core/savings.js +87 -0
- package/dist/core/schedule-gate.d.ts +2 -0
- package/dist/core/schedule-gate.d.ts.map +1 -0
- package/dist/core/schedule-gate.js +211 -0
- package/dist/core/schedule-v2.d.ts +116 -0
- package/dist/core/schedule-v2.d.ts.map +1 -0
- package/dist/core/schedule-v2.js +586 -0
- package/dist/core/scheduler/index.d.ts +32 -0
- package/dist/core/scheduler/index.d.ts.map +1 -0
- package/dist/core/scheduler/index.js +63 -0
- package/dist/core/scheduler/linux.d.ts +44 -0
- package/dist/core/scheduler/linux.d.ts.map +1 -0
- package/dist/core/scheduler/linux.js +225 -0
- package/dist/core/scheduler/logs.d.ts +11 -0
- package/dist/core/scheduler/logs.d.ts.map +1 -0
- package/dist/core/scheduler/logs.js +34 -0
- package/dist/core/scheduler/mac.d.ts +40 -0
- package/dist/core/scheduler/mac.d.ts.map +1 -0
- package/dist/core/scheduler/mac.js +207 -0
- package/dist/core/scheduler/posix.d.ts +40 -0
- package/dist/core/scheduler/posix.d.ts.map +1 -0
- package/dist/core/scheduler/posix.js +89 -0
- package/dist/core/scheduler/registry.d.ts +41 -0
- package/dist/core/scheduler/registry.d.ts.map +1 -0
- package/dist/core/scheduler/registry.js +57 -0
- package/dist/core/scheduler/types.d.ts +86 -0
- package/dist/core/scheduler/types.d.ts.map +1 -0
- package/dist/core/scheduler/types.js +1 -0
- package/dist/core/scheduler/windows.d.ts +99 -0
- package/dist/core/scheduler/windows.d.ts.map +1 -0
- package/dist/core/scheduler/windows.js +596 -0
- package/dist/core/secrets.d.ts +66 -0
- package/dist/core/secrets.d.ts.map +1 -0
- package/dist/core/secrets.js +433 -0
- package/dist/core/self-analysis.d.ts +117 -0
- package/dist/core/self-analysis.d.ts.map +1 -0
- package/dist/core/self-analysis.js +539 -0
- package/dist/core/self-analysis.test.d.ts +2 -0
- package/dist/core/self-analysis.test.d.ts.map +1 -0
- package/dist/core/self-analysis.test.js +219 -0
- package/dist/core/session.d.ts +42 -0
- package/dist/core/session.d.ts.map +1 -0
- package/dist/core/session.js +134 -0
- package/dist/core/shutdown.d.ts +26 -0
- package/dist/core/shutdown.d.ts.map +1 -0
- package/dist/core/shutdown.js +49 -0
- package/dist/core/structured-log.d.ts +84 -0
- package/dist/core/structured-log.d.ts.map +1 -0
- package/dist/core/structured-log.js +146 -0
- package/dist/core/summary.d.ts +69 -0
- package/dist/core/summary.d.ts.map +1 -0
- package/dist/core/summary.js +250 -0
- package/dist/core/telegram.d.ts +55 -0
- package/dist/core/telegram.d.ts.map +1 -0
- package/dist/core/telegram.js +344 -0
- package/dist/core/triage-chain.d.ts +40 -0
- package/dist/core/triage-chain.d.ts.map +1 -0
- package/dist/core/triage-chain.js +80 -0
- package/dist/core/triage-compare.d.ts +68 -0
- package/dist/core/triage-compare.d.ts.map +1 -0
- package/dist/core/triage-compare.js +184 -0
- package/dist/core/triage-rules.d.ts +23 -0
- package/dist/core/triage-rules.d.ts.map +1 -0
- package/dist/core/triage-rules.js +196 -0
- package/dist/core/triage-shadow.d.ts +91 -0
- package/dist/core/triage-shadow.d.ts.map +1 -0
- package/dist/core/triage-shadow.js +160 -0
- package/dist/core/triage-worker.d.ts +55 -0
- package/dist/core/triage-worker.d.ts.map +1 -0
- package/dist/core/triage-worker.js +314 -0
- package/dist/core/triage.d.ts +76 -0
- package/dist/core/triage.d.ts.map +1 -0
- package/dist/core/triage.js +271 -0
- package/dist/core/watch-paths.d.ts +6 -0
- package/dist/core/watch-paths.d.ts.map +1 -0
- package/dist/core/watch-paths.js +62 -0
- package/dist/core/wrappers/bash.d.ts +95 -0
- package/dist/core/wrappers/bash.d.ts.map +1 -0
- package/dist/core/wrappers/bash.js +413 -0
- package/dist/db/git-state-repo.d.ts +16 -0
- package/dist/db/git-state-repo.d.ts.map +1 -0
- package/dist/db/git-state-repo.js +38 -0
- package/dist/db/history-repo.d.ts +110 -0
- package/dist/db/history-repo.d.ts.map +1 -0
- package/dist/db/history-repo.js +300 -0
- package/dist/db/index.d.ts +47 -0
- package/dist/db/index.d.ts.map +1 -0
- package/dist/db/index.js +120 -0
- package/dist/db/metrics-repo.d.ts +46 -0
- package/dist/db/metrics-repo.d.ts.map +1 -0
- package/dist/db/metrics-repo.js +103 -0
- package/dist/db/migrate.d.ts +24 -0
- package/dist/db/migrate.d.ts.map +1 -0
- package/dist/db/migrate.js +244 -0
- package/dist/db/recovery.d.ts +11 -0
- package/dist/db/recovery.d.ts.map +1 -0
- package/dist/db/recovery.js +38 -0
- package/dist/db/schema.d.ts +24 -0
- package/dist/db/schema.d.ts.map +1 -0
- package/dist/db/schema.js +170 -0
- package/dist/db/settings-repo.d.ts +8 -0
- package/dist/db/settings-repo.d.ts.map +1 -0
- package/dist/db/settings-repo.js +27 -0
- package/dist/db/tasks-repo.d.ts +26 -0
- package/dist/db/tasks-repo.d.ts.map +1 -0
- package/dist/db/tasks-repo.js +120 -0
- package/dist/db/templates-repo.d.ts +17 -0
- package/dist/db/templates-repo.d.ts.map +1 -0
- package/dist/db/templates-repo.js +57 -0
- package/dist/gui-experimental.cjs +1 -0
- package/dist/history.d.ts +60 -0
- package/dist/history.d.ts.map +1 -0
- package/dist/history.js +70 -0
- package/dist/i18n.d.ts +75 -0
- package/dist/i18n.d.ts.map +1 -0
- package/dist/i18n.js +357 -0
- package/dist/index.d.ts +858 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5179 -0
- package/dist/integrations.d.ts +72 -0
- package/dist/integrations.d.ts.map +1 -0
- package/dist/integrations.js +233 -0
- package/dist/notifications.d.ts +199 -0
- package/dist/notifications.d.ts.map +1 -0
- package/dist/notifications.js +967 -0
- package/dist/profiles.d.ts +60 -0
- package/dist/profiles.d.ts.map +1 -0
- package/dist/profiles.js +227 -0
- package/dist/rpc.d.ts +3806 -0
- package/dist/rpc.d.ts.map +1 -0
- package/dist/rpc.js +1507 -0
- package/dist/schtasks.d.ts +32 -0
- package/dist/schtasks.d.ts.map +1 -0
- package/dist/schtasks.js +45 -0
- package/dist/server.d.ts +128 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +2413 -0
- package/dist/settings.d.ts +389 -0
- package/dist/settings.d.ts.map +1 -0
- package/dist/settings.js +770 -0
- package/dist/shared/jobs-view.d.ts +59 -0
- package/dist/shared/jobs-view.d.ts.map +1 -0
- package/dist/shared/jobs-view.js +146 -0
- package/dist/skill.d.ts +15 -0
- package/dist/skill.d.ts.map +1 -0
- package/dist/skill.js +93 -0
- package/dist/task-transfer.d.ts +252 -0
- package/dist/task-transfer.d.ts.map +1 -0
- package/dist/task-transfer.js +628 -0
- package/dist/templates.d.ts +57 -0
- package/dist/templates.d.ts.map +1 -0
- package/dist/templates.js +16 -0
- package/dist/types.d.ts +96 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +130 -0
- package/dist/version.d.ts +8 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +27 -0
- package/dist/workspaces.d.ts +113 -0
- package/dist/workspaces.d.ts.map +1 -0
- package/dist/workspaces.js +393 -0
- package/docs/ARCHITECTURE.md +457 -0
- package/docs/COMPATIBILITY.md +233 -0
- package/docs/CONCEPT.md +230 -0
- package/docs/CROSS_PLATFORM.ru.md +150 -0
- package/docs/CROSS_PLATFORM.zh.md +146 -0
- package/docs/FAQ.md +52 -0
- package/docs/FAQ.ru.md +53 -0
- package/docs/FAQ.zh.md +43 -0
- package/docs/FEATURES.md +698 -0
- package/docs/FEATURES.zh.md +655 -0
- package/docs/LOCAL-AI.md +300 -0
- package/docs/MIGRATION.md +355 -0
- package/docs/README.ru.md +268 -0
- package/docs/README.zh.md +305 -0
- package/docs/SAVINGS.md +61 -0
- package/docs/SAVINGS.ru.md +60 -0
- package/docs/SAVINGS.zh.md +52 -0
- package/docs/V1-V2-COMPATIBILITY-PLAN.md +366 -0
- package/docs/ZH-LOCALE-PLAN.md +324 -0
- package/docs/dashboard.png +0 -0
- package/docs/spikes/local-model-structured-output.md +81 -0
- package/docs/spikes/ollama-qwen3-4b-smoke.json +28 -0
- package/docs/spikes/ollama-qwen3-4b.json +163 -0
- package/gui-experimental.cjs +9 -0
- package/index.js +1 -0
- package/locales/en.json +780 -0
- package/locales/ru.json +780 -0
- package/locales/zh.json +780 -0
- package/package.json +149 -4
- package/scripts/bench-local.mjs +321 -0
- package/scripts/check-zh-locale.mjs +218 -0
- package/scripts/demo-dashboard.mjs +209 -0
- package/scripts/run-tests.mjs +236 -0
- package/scripts/spike-local-structured.mjs +182 -0
- package/scripts/test-locale.mjs +45 -0
- package/skills/scheduled-job-best-practices/SKILL.md +158 -0
- package/skills/scheduled-job-best-practices/references/recipes.md +163 -0
- package/src/core/analytics.ts +424 -0
- package/src/core/audit.ts +418 -0
- package/src/core/cron-to-schtasks.ts +288 -0
- package/src/core/dry-run.ts +601 -0
- package/src/core/file-watcher.ts +245 -0
- package/src/core/git-trigger.ts +391 -0
- package/src/core/glob.ts +226 -0
- package/src/core/local-ai.ts +173 -0
- package/src/core/lock.ts +219 -0
- package/src/core/matrix.ts +947 -0
- package/src/core/native-notify.ts +157 -0
- package/src/core/one-shot.ts +189 -0
- package/src/core/otel.ts +128 -0
- package/src/core/permissions.ts +200 -0
- package/src/core/prometheus.ts +215 -0
- package/src/core/ps-wrapper.ts +1140 -0
- package/src/core/record-history.ts +615 -0
- package/src/core/retention.ts +141 -0
- package/src/core/savings.ts +150 -0
- package/src/core/schedule-gate.ts +253 -0
- package/src/core/schedule-v2.ts +668 -0
- package/src/core/scheduler/index.ts +82 -0
- package/src/core/scheduler/linux.ts +257 -0
- package/src/core/scheduler/logs.ts +37 -0
- package/src/core/scheduler/mac.ts +270 -0
- package/src/core/scheduler/posix.ts +114 -0
- package/src/core/scheduler/registry.ts +99 -0
- package/src/core/scheduler/types.ts +90 -0
- package/src/core/scheduler/windows.ts +711 -0
- package/src/core/secrets.ts +503 -0
- package/src/core/self-analysis.ts +744 -0
- package/src/core/session.ts +150 -0
- package/src/core/shutdown.ts +69 -0
- package/src/core/structured-log.ts +214 -0
- package/src/core/summary.ts +318 -0
- package/src/core/telegram.ts +436 -0
- package/src/core/triage-chain.ts +125 -0
- package/src/core/triage-compare.ts +277 -0
- package/src/core/triage-rules.ts +238 -0
- package/src/core/triage-shadow.ts +240 -0
- package/src/core/triage-worker.ts +344 -0
- package/src/core/triage.ts +366 -0
- package/src/core/watch-paths.ts +70 -0
- package/src/core/wrappers/bash.ts +532 -0
- package/src/db/git-state-repo.ts +62 -0
- package/src/db/history-repo.ts +492 -0
- package/src/db/index.ts +166 -0
- package/src/db/metrics-repo.ts +170 -0
- package/src/db/migrate.ts +328 -0
- package/src/db/recovery.ts +46 -0
- package/src/db/schema.ts +188 -0
- package/src/db/settings-repo.ts +31 -0
- package/src/db/tasks-repo.ts +162 -0
- package/src/db/templates-repo.ts +77 -0
- package/src/gui.tsx +5222 -0
- package/src/history.ts +128 -0
- package/src/i18n.ts +413 -0
- package/src/index.ts +6605 -0
- package/src/integrations.ts +297 -0
- package/src/notifications.ts +1346 -0
- package/src/profiles.ts +254 -0
- package/src/rpc.ts +1609 -0
- package/src/schtasks.ts +75 -0
- package/src/server.ts +2662 -0
- package/src/settings.ts +1369 -0
- package/src/shared/jobs-view.ts +188 -0
- package/src/skill.ts +113 -0
- package/src/task-transfer.ts +944 -0
- package/src/templates.ts +67 -0
- package/src/tui-v1.tsx +341 -0
- package/src/tui.tsx +329 -0
- package/src/types.ts +191 -0
- package/src/version.ts +27 -0
- package/src/workspaces.ts +487 -0
package/docs/LOCAL-AI.md
ADDED
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
# Local assistant (triage)
|
|
2
|
+
|
|
3
|
+
The local assistant is an optional, fully offline classifier for run outcomes.
|
|
4
|
+
After a run finishes, the scheduler can ask a local model to classify the
|
|
5
|
+
outcome (quality, timeout, permission, network, unknown) and write the verdict
|
|
6
|
+
to the triage audit. It is **opt-in**: when no model is available the scheduler
|
|
7
|
+
keeps working exactly as before and notifications are never blocked.
|
|
8
|
+
|
|
9
|
+
Triage is not a scheduler feature by itself — it only affects notifications. It
|
|
10
|
+
never changes run status, retries, Quality Gates, DAG dependencies or history.
|
|
11
|
+
|
|
12
|
+
## How it works
|
|
13
|
+
|
|
14
|
+
```
|
|
15
|
+
run finished ──► triage chain ──► notify / skip / log-only (shadow)
|
|
16
|
+
│
|
|
17
|
+
├─ llm — local model classifies the failure
|
|
18
|
+
└─ rules - built-in patterns (timeout, permission, network, quality, cost, task)
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- `off` — no triage; every notification is sent (default).
|
|
22
|
+
- `rules` — built-in rules only. No model, no network calls.
|
|
23
|
+
- `llm` — the configured local model only.
|
|
24
|
+
- `auto` — the model first, then the rules engine (recommended).
|
|
25
|
+
|
|
26
|
+
Rules semantics: if `rules` is omitted (`undefined`), the built-in rule set is
|
|
27
|
+
active. An explicit empty array (`rules: []`) disables the rules engine entirely.
|
|
28
|
+
A non-empty custom array replaces the built-in set; it does not extend it.
|
|
29
|
+
|
|
30
|
+
### Built-in rules
|
|
31
|
+
|
|
32
|
+
The built-in set classifies errors by text, status, cost and task name. All
|
|
33
|
+
built-in rules are notify-only: they never suppress a notification.
|
|
34
|
+
|
|
35
|
+
| Rule | Match | Severity |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| `error-timeout` | timeout / deadline in the error text | high |
|
|
38
|
+
| `error-permission` | permission denied, access denied, forbidden | high |
|
|
39
|
+
| `error-network` | connection refused/reset, DNS, network error | high |
|
|
40
|
+
| `error-quality` | Quality Gate, failed tests, failed build, lint | high |
|
|
41
|
+
| `cost-high` | `costUsd >= 1` | high |
|
|
42
|
+
| `task-important` | task name contains deploy, release, publish, production, backup, restore or migration | high |
|
|
43
|
+
| `status-error` | status is `error` | high |
|
|
44
|
+
| `status-partial` | status is `partial` | medium |
|
|
45
|
+
| `status-success` | status is `success` | low |
|
|
46
|
+
|
|
47
|
+
A custom array replaces the built-in set. For example, this configuration
|
|
48
|
+
suppresses noisy nightly runs and marks runs costing $5 or more as high:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
"notifications": {
|
|
52
|
+
"triage": {
|
|
53
|
+
"mode": "rules",
|
|
54
|
+
"rules": [
|
|
55
|
+
{ "id": "skip-nightly", "field": "task", "operator": "contains", "value": "nightly", "action": "skip", "priority": 50 },
|
|
56
|
+
{ "id": "expensive", "field": "cost", "operator": "gte", "value": 5, "severity": "high", "priority": 90 }
|
|
57
|
+
]
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The result is validated against a fixed JSON schema. Invalid JSON, an
|
|
63
|
+
unreachable endpoint, a timeout or low confidence all fall back to the rules
|
|
64
|
+
engine (fail-open). With `fallback: "notify"` the scheduler skips the rules step
|
|
65
|
+
and delivers the notification instead. The legacy name `"skip"` is still
|
|
66
|
+
accepted and normalized to `"notify"`.
|
|
67
|
+
|
|
68
|
+
The model only **classifies** a run: a valid verdict never suppresses a
|
|
69
|
+
notification on its own. Only a matching rule with `action: "skip"` can
|
|
70
|
+
suppress delivery. This is intentional: an uncertain small model must not be
|
|
71
|
+
able to hide a real failure.
|
|
72
|
+
|
|
73
|
+
## Delivery latency (async triage)
|
|
74
|
+
|
|
75
|
+
In `llm` and `auto` modes triage runs asynchronously. `record-history` delivers
|
|
76
|
+
the notification immediately and starts a detached worker for the model call;
|
|
77
|
+
the worker writes the verdict to `audit_log` with `async: true`. The configured
|
|
78
|
+
`timeoutMs` applies to that background request, not to delivery: a cold model
|
|
79
|
+
that takes 40 seconds cannot delay the webhook, chain triggers or the task lock.
|
|
80
|
+
|
|
81
|
+
Only `rules` mode triages synchronously, because rules are the only thing that
|
|
82
|
+
can suppress a notification. In `llm`/`auto` the model and its rules fallback
|
|
83
|
+
are advisory: the notification is already sent, so `action: "skip"` in the
|
|
84
|
+
audit means “would have been skipped”, not “was suppressed”. Use `rules` mode
|
|
85
|
+
if rules must actually suppress delivery. The GUI shows this warning when a
|
|
86
|
+
model mode is selected.
|
|
87
|
+
|
|
88
|
+
In shadow mode the worker records `shadow: true` and `suppressed: false`, so a
|
|
89
|
+
shadow report remains a safe preview of triage decisions.
|
|
90
|
+
|
|
91
|
+
## Requirements
|
|
92
|
+
|
|
93
|
+
- [Ollama](https://ollama.com/) running locally, or any OpenAI-compatible
|
|
94
|
+
server (a `baseUrl` ending with `/v1` switches to the OpenAI protocol).
|
|
95
|
+
- One pulled model, for example `qwen3:4b`.
|
|
96
|
+
- No internet access is required after the model is downloaded.
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
ollama serve
|
|
100
|
+
ollama pull qwen3:4b
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Configuration
|
|
104
|
+
|
|
105
|
+
Triage settings live under `notifications.triage` and are edited from the GUI
|
|
106
|
+
side panel ("Local assistant") or through the `manage_local_ai` agent tool.
|
|
107
|
+
|
|
108
|
+
The panel shows a persistent connection status next to **Test connection**:
|
|
109
|
+
grey means "not checked", amber "checking", green "connected", red "no
|
|
110
|
+
connection" with the provider error. The test sends one synthetic
|
|
111
|
+
classification request (it is not saved) and reports the model, protocol and
|
|
112
|
+
latency. Status resets when `mode`, `baseUrl` or `model` changes, so a stale
|
|
113
|
+
green cannot hide a new endpoint. A red status never blocks notifications:
|
|
114
|
+
`llm`/`auto` triage is asynchronous and fail-open.
|
|
115
|
+
|
|
116
|
+
| Setting | Values | Default | Meaning |
|
|
117
|
+
| --- | --- | --- | --- |
|
|
118
|
+
| `mode` | `off` / `rules` / `llm` / `auto` | `off` | Triage strategy. |
|
|
119
|
+
| `baseUrl` | URL | `http://127.0.0.1:11434` | Ollama or OpenAI-compatible endpoint. |
|
|
120
|
+
| `model` | string | `""` | Model id, for example `qwen3:4b`. |
|
|
121
|
+
| `timeoutMs` | 1000..120000 | `60000` | Background request timeout in `llm`/`auto`; does not delay delivery. |
|
|
122
|
+
| `fallback` | `rules` / `notify` | `rules` | Behaviour when the model fails or is unsure. |
|
|
123
|
+
| `confidenceThreshold` | 0..1 | `0.6` | Minimum model confidence; below it the fallback applies. |
|
|
124
|
+
| `shadow.enabled` | boolean | `true` | Log decisions without suppressing notifications. |
|
|
125
|
+
| `shadow.days` | 1..365 | `14` | Shadow period length. |
|
|
126
|
+
| `shadow.startedAt` | ISO string / null | `null` | Start of the shadow period; `null` restarts it. |
|
|
127
|
+
|
|
128
|
+
`fallback: "skip"` is accepted as a legacy alias for `notify` and is normalized
|
|
129
|
+
on load, so old settings keep working without edits.
|
|
130
|
+
|
|
131
|
+
## Message summaries
|
|
132
|
+
|
|
133
|
+
`notifications.summary` turns a notification into at most three short lines for
|
|
134
|
+
Telegram and OS toasts. The same Ollama/OpenAI-compatible provider is used, but
|
|
135
|
+
the request is independent of triage and has its own timeout.
|
|
136
|
+
|
|
137
|
+
| Setting | Values | Default | Meaning |
|
|
138
|
+
| --- | --- | --- | --- |
|
|
139
|
+
| `summary.enabled` | boolean | `false` | Use the model summary instead of the template message. |
|
|
140
|
+
| `summary.maxLines` | 1..3 | `3` | Maximum number of lines. |
|
|
141
|
+
| `summary.maxCharsPerLine` | 20..500 | `120` | Hard cut per line. |
|
|
142
|
+
| `summary.timeoutMs` | 1000..120000 | `8000` | Summary request timeout. |
|
|
143
|
+
|
|
144
|
+
The model must answer with strict JSON `{"lines": ["...", "..."]}`. Any
|
|
145
|
+
failure — no provider, HTTP error, timeout, invalid JSON or schema — falls back
|
|
146
|
+
to a deterministic truncation: status and task name, the error text, then
|
|
147
|
+
runtime, tokens and cost. A summary never blocks or drops the notification:
|
|
148
|
+
delivery waits at most `timeoutMs`.
|
|
149
|
+
|
|
150
|
+
## Managing triage from the agent
|
|
151
|
+
|
|
152
|
+
The `manage_local_ai` tool has three actions.
|
|
153
|
+
|
|
154
|
+
Read the current state:
|
|
155
|
+
|
|
156
|
+
```json
|
|
157
|
+
{ "action": "get" }
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
Update one or more fields (merged with the current settings):
|
|
161
|
+
|
|
162
|
+
```json
|
|
163
|
+
{
|
|
164
|
+
"action": "update",
|
|
165
|
+
"mode": "auto",
|
|
166
|
+
"baseUrl": "http://127.0.0.1:11434",
|
|
167
|
+
"model": "qwen3:4b",
|
|
168
|
+
"timeoutMs": 60000,
|
|
169
|
+
"fallback": "rules",
|
|
170
|
+
"confidenceThreshold": 0.6,
|
|
171
|
+
"shadow": { "enabled": true, "days": 14 }
|
|
172
|
+
}
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Send one classification request against the configured model (or a candidate
|
|
176
|
+
patch without saving it):
|
|
177
|
+
|
|
178
|
+
```json
|
|
179
|
+
{ "action": "test", "model": "qwen3:4b", "timeoutMs": 60000 }
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
`get` and `update` return a summary: `mode`, `baseUrl`, `model`, `timeoutMs`,
|
|
183
|
+
`fallback`, `confidenceThreshold`, `rules` (number of active rules or `null`),
|
|
184
|
+
`shadow`, `llmReady`, `shadowActive` and `protocol` (`ollama` or `openai`).
|
|
185
|
+
|
|
186
|
+
## Picking a model by RAM
|
|
187
|
+
|
|
188
|
+
The classifier is a small, structured task: a 4B model is usually enough. The
|
|
189
|
+
benchmark below prints a tier for the current machine.
|
|
190
|
+
|
|
191
|
+
| RAM | Tier | Recommended model | Notes |
|
|
192
|
+
| --- | --- | --- | --- |
|
|
193
|
+
| < 8 GB | rules-only | `qwen3:0.6b` | Prefer `mode: "rules"`; a tiny model may be too slow. |
|
|
194
|
+
| 8–15 GB | light | `qwen3:1.7b` | Fast, lower accuracy. |
|
|
195
|
+
| 15–30 GB | balanced | `qwen3:4b` | Recommended default. |
|
|
196
|
+
| > 30 GB | max | `qwen3:8b` | Better accuracy, more latency. |
|
|
197
|
+
|
|
198
|
+
## Benchmarking a machine
|
|
199
|
+
|
|
200
|
+
`scripts/bench-local.mjs` measures latency, schema validity and throughput
|
|
201
|
+
(tokens/s) for the configured model. It reuses the same triage prompt and JSON
|
|
202
|
+
schema as the scheduler.
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
npm run bench:local -- --model qwen3:4b --runs 3
|
|
206
|
+
npm run bench:local -- --model qwen3:4b --runs 5 --out bench.json
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
Options: `--base-url`, `--model`, `--runs` (1..50), `--timeout` (1000..600000),
|
|
210
|
+
`--out`, `--help`.
|
|
211
|
+
|
|
212
|
+
The report is a versioned JSON envelope (`schemaVersion: "1"`) suitable for
|
|
213
|
+
crowdsourcing results:
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{
|
|
217
|
+
"schemaVersion": "1",
|
|
218
|
+
"generatedAt": "2026-11-15T12:00:00.000Z",
|
|
219
|
+
"available": true,
|
|
220
|
+
"machine": { "platform": "win32", "arch": "x64", "cpu": "…", "cpuCount": 16, "ramGb": 15.9, "nodeVersion": "v24.21.0" },
|
|
221
|
+
"tier": { "id": "balanced", "recommendedModel": "qwen3:4b", "reason": "…" },
|
|
222
|
+
"model": "qwen3:4b",
|
|
223
|
+
"runs": 3,
|
|
224
|
+
"metrics": {
|
|
225
|
+
"schemaValid": 3,
|
|
226
|
+
"schemaValidRate": 1,
|
|
227
|
+
"jsonValid": 3,
|
|
228
|
+
"jsonValidRate": 1,
|
|
229
|
+
"avgLatencyMs": 23785,
|
|
230
|
+
"p95LatencyMs": 26904,
|
|
231
|
+
"avgTokPerSec": 28.7,
|
|
232
|
+
"p95TokPerSec": 28.98
|
|
233
|
+
},
|
|
234
|
+
"results": []
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Exit codes: `0` when at least 70% of responses are schema-valid, `1` otherwise,
|
|
239
|
+
`2` when the endpoint or model is unavailable (the JSON report is still written
|
|
240
|
+
with `available: false`).
|
|
241
|
+
|
|
242
|
+
## Shadow mode
|
|
243
|
+
|
|
244
|
+
Shadow mode is the safe way to evaluate triage. Decisions are written to the
|
|
245
|
+
persistent audit journal (`audit_log`, action `triage.decision`), but no
|
|
246
|
+
notification is suppressed. In `llm`/`auto` the verdict arrives asynchronously
|
|
247
|
+
after delivery; in `rules` mode it is computed before delivery. Check the shadow
|
|
248
|
+
report before switching to `mode: "auto"`: it shows how many notifications
|
|
249
|
+
would have been skipped and whether any of those were false positives.
|
|
250
|
+
|
|
251
|
+
The journal survives restarts and runs in the short-lived `record-history`
|
|
252
|
+
process, unlike the old in-memory counters. Read individual decisions with
|
|
253
|
+
`get_audit_log` (`action: "triage.decision"`); the report is also available as
|
|
254
|
+
`rpc.get_shadow_report` (including the last 50 decisions). The report covers
|
|
255
|
+
the configured shadow window `[startedAt, startedAt + days]`; resetting it
|
|
256
|
+
deletes only shadow rows and keeps ordinary decision history.
|
|
257
|
+
|
|
258
|
+
Start with `mode: "auto"`, `shadow.enabled: true` and `shadow.days: 14`. After
|
|
259
|
+
the period, review the shadow report and only then disable shadow mode.
|
|
260
|
+
|
|
261
|
+
## Troubleshooting
|
|
262
|
+
|
|
263
|
+
| Symptom | Cause | Fix |
|
|
264
|
+
| --- | --- | --- |
|
|
265
|
+
| `connection refused` / `fetch failed` | Ollama is not running | `ollama serve` |
|
|
266
|
+
| `model not found` | Model not pulled | `ollama pull <model>`, then check `ollama list` |
|
|
267
|
+
| Requests time out | Model too large for the machine or context too long | Lower the model tier, raise `timeoutMs`, cap context (below) |
|
|
268
|
+
| `llmReady: false` in `manage_local_ai` `get` | Endpoint or model unavailable | Check `baseUrl` and `model` |
|
|
269
|
+
| Very slow first response | Cold model load | Run once to warm the model; the benchmark shows steady-state numbers |
|
|
270
|
+
| Invalid JSON from the model | Model too small or prompt drift | Use a larger model or `mode: "rules"` |
|
|
271
|
+
|
|
272
|
+
### OLLAMA_CONTEXT_LENGTH
|
|
273
|
+
|
|
274
|
+
Ollama allocates a large context window by default, which costs RAM and slows
|
|
275
|
+
CPU inference. For triage, a short context is enough. Set it in the environment
|
|
276
|
+
before starting the server:
|
|
277
|
+
|
|
278
|
+
```bash
|
|
279
|
+
# Windows (PowerShell)
|
|
280
|
+
$env:OLLAMA_CONTEXT_LENGTH = "2048"
|
|
281
|
+
ollama serve
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
# Linux / macOS
|
|
286
|
+
OLLAMA_CONTEXT_LENGTH=2048 ollama serve
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
Restart Ollama after changing the variable. If the model still does not fit,
|
|
290
|
+
choose a smaller tier or use `mode: "rules"`.
|
|
291
|
+
|
|
292
|
+
## Limits
|
|
293
|
+
|
|
294
|
+
- Triage only affects notifications. It never rewrites run results.
|
|
295
|
+
- The model runs locally; prompts and logs are not sent to a third party.
|
|
296
|
+
- A missing model never blocks scheduling: rules or direct delivery take over.
|
|
297
|
+
- The classifier is intentionally conservative. When in doubt it delivers the
|
|
298
|
+
notification (fail-open).
|
|
299
|
+
- The benchmark measures a single machine; results are not a guarantee for other
|
|
300
|
+
hardware.
|
|
@@ -0,0 +1,355 @@
|
|
|
1
|
+
# Migration guide
|
|
2
|
+
|
|
3
|
+
How to move existing automation into `opencode-windows-scheduler` from cron, systemd
|
|
4
|
+
timers, launchd, Windows Task Scheduler, or another scheduler plugin.
|
|
5
|
+
|
|
6
|
+
- [Before you start](#before-you-start)
|
|
7
|
+
- [From cron / crontab](#from-cron--crontab)
|
|
8
|
+
- [From systemd timers](#from-systemd-timers)
|
|
9
|
+
- [From launchd](#from-launchd)
|
|
10
|
+
- [From Windows Task Scheduler](#from-windows-task-scheduler)
|
|
11
|
+
- [From another scheduler plugin](#from-another-scheduler-plugin)
|
|
12
|
+
- [Bulk import and export](#bulk-import-and-export)
|
|
13
|
+
- [Verification checklist](#verification-checklist)
|
|
14
|
+
- [Common pitfalls](#common-pitfalls)
|
|
15
|
+
- [Rollback](#rollback)
|
|
16
|
+
|
|
17
|
+
## Before you start
|
|
18
|
+
|
|
19
|
+
1. **Install and build.**
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g opencode-windows-scheduler
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Add the plugin to `opencode.json` and restart OpenCode. If OpenCode's built-in
|
|
26
|
+
schedules are enabled, disable them so two schedulers do not run the same work.
|
|
27
|
+
|
|
28
|
+
2. **Check Node.** `node --version` must be 20 or newer (22.5+ for the built-in SQLite
|
|
29
|
+
driver; Node 24 recommended).
|
|
30
|
+
|
|
31
|
+
3. **Inventory the old jobs.** For each job write down: name, schedule, command,
|
|
32
|
+
working directory, environment variables, timeout, and what "success" means. The
|
|
33
|
+
last one becomes your Quality Gate.
|
|
34
|
+
|
|
35
|
+
4. **Do not delete the old jobs yet.** Run both schedulers side by side for a few days,
|
|
36
|
+
then remove the old entries.
|
|
37
|
+
|
|
38
|
+
## From cron / crontab
|
|
39
|
+
|
|
40
|
+
Cron expressions are compatible (five fields). The differences are in the command.
|
|
41
|
+
|
|
42
|
+
**Before (crontab)**
|
|
43
|
+
|
|
44
|
+
```cron
|
|
45
|
+
0 2 * * * cd /srv/api && /usr/bin/git pull && /usr/bin/npm test >> /var/log/api.log 2>&1
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
**After (agent tool or GUI)**
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"name": "api-nightly",
|
|
53
|
+
"schedule": "0 2 * * *",
|
|
54
|
+
"workingDirectory": "/srv/api",
|
|
55
|
+
"beforeScript": "git pull --ff-only",
|
|
56
|
+
"prompt": "Inspect the repository, apply safe dependency updates, and explain every change you made.",
|
|
57
|
+
"qualityGate": "npm test",
|
|
58
|
+
"timeoutSeconds": 1800
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Mapping table:
|
|
63
|
+
|
|
64
|
+
| Cron concept | Scheduler equivalent |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| `cd /path && command` | `workingDirectory` or `workspaceId` |
|
|
67
|
+
| `>> file 2>&1` | log file is written automatically (`logs/<task>.log`) |
|
|
68
|
+
| `&&` chains | `beforeScript`, `prompt`, `qualityGate`, `afterScript` |
|
|
69
|
+
| exit code check | Quality Gate |
|
|
70
|
+
| `MAILTO` | webhook notifications |
|
|
71
|
+
| `%` escapes | not needed; write the prompt as normal text |
|
|
72
|
+
| `@reboot` | not supported; use a file/MCP trigger or a frequent cron |
|
|
73
|
+
|
|
74
|
+
Notes:
|
|
75
|
+
|
|
76
|
+
- `@daily`, `@hourly` and similar macros are not supported — write `0 0 * * *`,
|
|
77
|
+
`0 * * * *`, and so on.
|
|
78
|
+
- `@reboot` and `@yearly` have no direct equivalent.
|
|
79
|
+
- Cron environments are minimal. The wrapper inherits the user environment of the OS
|
|
80
|
+
scheduler entry, not your interactive shell. Absolute paths are safer than relying on
|
|
81
|
+
`PATH` from `.bashrc`.
|
|
82
|
+
|
|
83
|
+
## From systemd timers
|
|
84
|
+
|
|
85
|
+
The plugin schedules through the user crontab on Linux, so systemd calendar syntax is
|
|
86
|
+
translated to a cron expression when you migrate.
|
|
87
|
+
|
|
88
|
+
**Before**
|
|
89
|
+
|
|
90
|
+
```ini
|
|
91
|
+
# api-nightly.timer
|
|
92
|
+
[Timer]
|
|
93
|
+
OnCalendar=*-*-* 02:00:00
|
|
94
|
+
Persistent=true
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
```ini
|
|
98
|
+
# api-nightly.service
|
|
99
|
+
[Service]
|
|
100
|
+
WorkingDirectory=/srv/api
|
|
101
|
+
ExecStart=/usr/bin/npm run nightly
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**After**
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"name": "api-nightly",
|
|
109
|
+
"schedule": "0 2 * * *",
|
|
110
|
+
"workingDirectory": "/srv/api",
|
|
111
|
+
"prompt": "Run the nightly routine described in package.json and summarize the result.",
|
|
112
|
+
"qualityGate": "npm test"
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
| systemd | Scheduler |
|
|
117
|
+
| --- | --- |
|
|
118
|
+
| `OnCalendar=*-*-* 02:00` | `0 2 * * *` |
|
|
119
|
+
| `OnUnitActiveSec=15min` | `*/15 * * * *` |
|
|
120
|
+
| `WorkingDirectory` | `workingDirectory` / `workspaceId` |
|
|
121
|
+
| `Environment=` | set it in the hook or in the user environment |
|
|
122
|
+
| `TimeoutStartSec` | `timeoutSeconds` |
|
|
123
|
+
| `Persistent=true` | catch-up is not implemented; a missed window is skipped |
|
|
124
|
+
| `Requires=` / `After=` | `dependsOn` |
|
|
125
|
+
|
|
126
|
+
Disable the old units (`systemctl --user disable --now api-nightly.timer`) only after
|
|
127
|
+
the new task has run successfully at least once.
|
|
128
|
+
|
|
129
|
+
## From launchd
|
|
130
|
+
|
|
131
|
+
**Before**
|
|
132
|
+
|
|
133
|
+
```xml
|
|
134
|
+
<key>StartCalendarInterval</key>
|
|
135
|
+
<dict><key>Hour</key><integer>2</integer></dict>
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**After**
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"name": "mac-nightly",
|
|
143
|
+
"schedule": "0 2 * * *",
|
|
144
|
+
"workingDirectory": "/Users/me/projects/api",
|
|
145
|
+
"prompt": "Run the nightly maintenance and report anything unusual."
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
| launchd | Scheduler |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `StartCalendarInterval` | cron expression |
|
|
152
|
+
| `StartInterval` (seconds) | `*/N * * * *` (minute granularity) |
|
|
153
|
+
| `WorkingDirectory` | `workingDirectory` |
|
|
154
|
+
| `StandardOutPath` / `StandardErrorPath` | automatic log file |
|
|
155
|
+
| `RunAtLoad` | not supported; use a manual run or a file trigger |
|
|
156
|
+
|
|
157
|
+
## From Windows Task Scheduler
|
|
158
|
+
|
|
159
|
+
Existing tasks usually point to a `.bat`/`.ps1` file or a command line.
|
|
160
|
+
|
|
161
|
+
**After**
|
|
162
|
+
|
|
163
|
+
```json
|
|
164
|
+
{
|
|
165
|
+
"name": "win-nightly",
|
|
166
|
+
"schedule": "0 2 * * *",
|
|
167
|
+
"workingDirectory": "C:\\projects\\api",
|
|
168
|
+
"prompt": "Run the nightly maintenance for this repository.",
|
|
169
|
+
"qualityGate": "npm test"
|
|
170
|
+
}
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
| Task Scheduler | Scheduler |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| Trigger "Daily" | `0 2 * * *` |
|
|
176
|
+
| Trigger "At log on" | not supported; use a file trigger or a start-up hook |
|
|
177
|
+
| "Run whether user is logged on" | the plugin registers tasks in the current user context |
|
|
178
|
+
| "Stop task if it runs longer than" | `timeoutSeconds` |
|
|
179
|
+
| "If the task is already running" | lock file, the second run is `skipped` |
|
|
180
|
+
| Action "Start a program" | you describe the goal in a prompt instead of a command |
|
|
181
|
+
| Multiple actions | `beforeScript` + `prompt` + `qualityGate` + `afterScript` |
|
|
182
|
+
|
|
183
|
+
Delete the old task only after verifying the new one:
|
|
184
|
+
`schtasks /delete /tn "<old task>" /f`.
|
|
185
|
+
|
|
186
|
+
## From another scheduler plugin
|
|
187
|
+
|
|
188
|
+
There is no universal importer, because definition formats differ. The workflow is:
|
|
189
|
+
|
|
190
|
+
1. List the old jobs and copy their schedules, prompts and working directories.
|
|
191
|
+
2. Recreate them with `schedule_task` or the GUI.
|
|
192
|
+
3. If the old plugin exports JSON, transform it into the import format below and use
|
|
193
|
+
`import_tasks` — validation reports per-record errors.
|
|
194
|
+
4. Disable the old plugin before the first overlapping run.
|
|
195
|
+
|
|
196
|
+
## Bulk import and export
|
|
197
|
+
|
|
198
|
+
**Export format**
|
|
199
|
+
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"version": 1,
|
|
203
|
+
"exportedAt": "2026-01-01T00:00:00.000Z",
|
|
204
|
+
"tasks": [
|
|
205
|
+
{
|
|
206
|
+
"name": "api-nightly",
|
|
207
|
+
"schedule": "0 2 * * *",
|
|
208
|
+
"prompt": "Nightly maintenance.",
|
|
209
|
+
"qualityGate": "npm test",
|
|
210
|
+
"workspaceId": "ws-api"
|
|
211
|
+
}
|
|
212
|
+
]
|
|
213
|
+
}
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
**Import**
|
|
217
|
+
|
|
218
|
+
Use `import_tasks` from the GUI or the RPC layer. Rules:
|
|
219
|
+
|
|
220
|
+
- `name` and `prompt` are required.
|
|
221
|
+
- `cron` tasks need a schedule; `file` tasks need `watchPath`; `mcp-event` tasks need
|
|
222
|
+
`mcpEvent.event`.
|
|
223
|
+
- Matrix tasks cannot also set `workspaceId`, and `matrix.workspaceIds` must not be
|
|
224
|
+
empty.
|
|
225
|
+
- Workspace ids must exist in the target installation, or the record is rejected.
|
|
226
|
+
- Errors are reported per record; valid records are imported.
|
|
227
|
+
|
|
228
|
+
Workspaces are not exported as directories — recreate them with
|
|
229
|
+
`manage_workspaces` first, then map old paths by hand.
|
|
230
|
+
|
|
231
|
+
## Verification checklist
|
|
232
|
+
|
|
233
|
+
For every migrated job:
|
|
234
|
+
|
|
235
|
+
1. `dry_run` with the task name — check order, dependencies and estimated time.
|
|
236
|
+
2. `run_task_now` — confirm the log shows the expected work.
|
|
237
|
+
3. Check the Quality Gate result in `get_history`.
|
|
238
|
+
4. Confirm the next scheduled run appears with a correct "next run" timestamp.
|
|
239
|
+
5. For matrix jobs, expand the parent in the dashboard and verify every clone has the
|
|
240
|
+
right workspace path.
|
|
241
|
+
6. Wait for at least one natural scheduled run before deleting the old definition.
|
|
242
|
+
|
|
243
|
+
## From `opencode-windows-scheduler` to `agent-steward` (package rename)
|
|
244
|
+
|
|
245
|
+
The npm package `opencode-windows-scheduler` was renamed to `agent-steward` at milestone
|
|
246
|
+
**2.0.0**. This section covers the rename migration only — task definitions, schedules,
|
|
247
|
+
history and settings are **unchanged**.
|
|
248
|
+
|
|
249
|
+
### What changes
|
|
250
|
+
|
|
251
|
+
| Item | Before (`opencode-windows-scheduler`) | After (`agent-steward`) |
|
|
252
|
+
|------|--------------------------------------|-------------------------|
|
|
253
|
+
| npm package name | `opencode-windows-scheduler` | `agent-steward` |
|
|
254
|
+
| GitHub repository | `DeadSno/opencode-windows-scheduler` | `DeadSno/agent-steward` |
|
|
255
|
+
| Install command | `opencode plugin add opencode-windows-scheduler` | `opencode plugin add opencode-windows-scheduler` |
|
|
256
|
+
| V1 config key | `"plugin": ["opencode-windows-scheduler"]` | same (unchanged) |
|
|
257
|
+
| V2 config key | `"plugins": ["opencode-windows-scheduler"]` | same (unchanged) |
|
|
258
|
+
| `plugin id` | `opencode-windows-scheduler` | same (unchanged) |
|
|
259
|
+
| State paths | `%APPDATA%\opencode\windows-scheduler` / `~/.config/opencode/windows-scheduler` | same (unchanged) |
|
|
260
|
+
|
|
261
|
+
**Only the npm package name and GitHub repository changed.** Your tasks, schedules,
|
|
262
|
+
SQLite history, profiles, secrets and dashboard settings continue to work without
|
|
263
|
+
modification.
|
|
264
|
+
|
|
265
|
+
### Migration steps
|
|
266
|
+
|
|
267
|
+
1. **Update the OpenCode config** (`opencode.jsonc`):
|
|
268
|
+
|
|
269
|
+
V1:
|
|
270
|
+
```jsonc
|
|
271
|
+
{
|
|
272
|
+
"$schema": "https://opencode.ai/config.json",
|
|
273
|
+
"plugin": ["opencode-windows-scheduler"]
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
V2:
|
|
278
|
+
```jsonc
|
|
279
|
+
{
|
|
280
|
+
"$schema": "https://opencode.ai/config.json",
|
|
281
|
+
"plugins": ["opencode-windows-scheduler"]
|
|
282
|
+
}
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
The plugin key stays `opencode-windows-scheduler` — only the npm package name
|
|
286
|
+
changed. Restart OpenCode after saving.
|
|
287
|
+
|
|
288
|
+
2. **Install from the new package** — OpenCode resolves the plugin by `plugin id`, not
|
|
289
|
+
by npm package name, so existing installations keep working. New installs use
|
|
290
|
+
`agent-steward`:
|
|
291
|
+
|
|
292
|
+
```bash
|
|
293
|
+
opencode plugin add opencode-windows-scheduler
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
OpenCode will install the `agent-steward` package under the hood (the `plugin id`
|
|
297
|
+
`opencode-windows-scheduler` maps to the new package).
|
|
298
|
+
|
|
299
|
+
3. **Old package (`opencode-windows-scheduler`)** — remains published as a thin
|
|
300
|
+
re-export wrapper around `agent-steward` for one major version. It receives only
|
|
301
|
+
critical patches. No action required if you already have it installed; it will
|
|
302
|
+
continue to work until `npm deprecate` (planned for `>= 2.1`, after download parity
|
|
303
|
+
with the new package).
|
|
304
|
+
|
|
305
|
+
4. **Verify** — run `dry_run` on any existing task and confirm it executes. Check
|
|
306
|
+
`get_history` for the latest runs. Nothing should change in behaviour.
|
|
307
|
+
|
|
308
|
+
### Rollback
|
|
309
|
+
|
|
310
|
+
No rollback is needed — the `plugin id` and all state paths are identical before and
|
|
311
|
+
after the rename. If you prefer the old npm package name, keep using
|
|
312
|
+
`opencode-windows-scheduler` (the thin re-export) until it is deprecated.
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
## Local AI / triage migration
|
|
316
|
+
|
|
317
|
+
If you are migrating from a setup that used cloud AI for lightweight task triage or
|
|
318
|
+
classification, you can move that load to a local model to save tokens:
|
|
319
|
+
|
|
320
|
+
1. Install Ollama: `ollama serve` and `ollama pull qwen3:4b` (or a smaller model for
|
|
321
|
+
RAM-constrained machines — see `docs/LOCAL-AI.md` for tier recommendations).
|
|
322
|
+
2. Configure triage via `manage_local_ai({action: "update", mode: "auto", ...})` or
|
|
323
|
+
through the GUI notifications panel.
|
|
324
|
+
3. Start in `shadow` mode so decisions are logged but not applied, then switch to `auto`
|
|
325
|
+
once confidence is acceptable.
|
|
326
|
+
4. Ollama is optional — if it is unavailable, the plugin falls back to rules-only mode
|
|
327
|
+
(fail-open) and never blocks notifications.
|
|
328
|
+
|
|
329
|
+
## Common pitfalls
|
|
330
|
+
|
|
331
|
+
| Symptom | Cause | Fix |
|
|
332
|
+
| --- | --- | --- |
|
|
333
|
+
| `skipped` in history | previous run still holds the lock | wait, or lower `timeoutSeconds` |
|
|
334
|
+
| `timeout` every run | the agent needs more time | raise `timeoutSeconds` |
|
|
335
|
+
| Quality Gate fails but the work looks fine | gate runs in the task directory, not a subdirectory | prefix the command with `cd subdir && ...` |
|
|
336
|
+
| Agent cannot find the project | no `workingDirectory`/`workspaceId`, so it ran in the plugin directory | set the working directory |
|
|
337
|
+
| "Workspace path does not exist" on import | workspace ids belong to another machine | recreate workspaces and remap ids |
|
|
338
|
+
| Two runs at once after migration | old scheduler is still enabled | disable the old job |
|
|
339
|
+
| Cron rejected | expression not expressible by `schtasks` | use a supported pattern (`*/N`, fixed minute/hour, weekdays) |
|
|
340
|
+
| Prompts behave differently at night | interactive shell environment vs scheduler environment | use absolute paths, avoid alias-dependent commands |
|
|
341
|
+
| Local AI (Ollama) unreachable | `manage_local_ai` test fails or triage falls back to rules | run `ollama serve`, `ollama pull <model>`, check `OLLAMA_CONTEXT_LENGTH` |
|
|
342
|
+
| Local AI confidence too low | rules fire instead of LLM, more tokens used than expected | raise `confidenceThreshold` in `manage_local_ai`, review rule reasons in audit |
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
## Rollback
|
|
346
|
+
|
|
347
|
+
If something goes wrong:
|
|
348
|
+
|
|
349
|
+
1. Re-enable the old jobs (they were never deleted).
|
|
350
|
+
2. `pause_task` the migrated ones, or delete them.
|
|
351
|
+
3. Export the plugin definitions before major changes: `export_tasks` gives a single
|
|
352
|
+
JSON file you can re-import on any machine.
|
|
353
|
+
|
|
354
|
+
Definitions live in `scheduler.db`; deleting the plugin directory removes all state.
|
|
355
|
+
Export first if you might want it back.
|