agent-steward 0.0.1 → 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/README.md +306 -15
- 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 +133 -13
- 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
|
@@ -0,0 +1,457 @@
|
|
|
1
|
+
# Architecture
|
|
2
|
+
|
|
3
|
+
This document explains how `opencode-windows-scheduler` is put together: the process
|
|
4
|
+
model, the modules, the data model and the extension points.
|
|
5
|
+
|
|
6
|
+
- [Design principles](#design-principles)
|
|
7
|
+
- [Process model](#process-model)
|
|
8
|
+
- [Data flow](#data-flow)
|
|
9
|
+
- [Modules](#modules)
|
|
10
|
+
- [Scheduling backends](#scheduling-backends)
|
|
11
|
+
- [Run wrapper](#run-wrapper)
|
|
12
|
+
- [History, metrics and recovery](#history-metrics-and-recovery)
|
|
13
|
+
- [Chains, retries and DAG](#chains-retries-and-dag)
|
|
14
|
+
- [Matrix builds](#matrix-builds)
|
|
15
|
+
- [Workspaces](#workspaces)
|
|
16
|
+
- [Triggers](#triggers)
|
|
17
|
+
- [Storage](#storage)
|
|
18
|
+
- [Interfaces](#interfaces)
|
|
19
|
+
- [Localization](#localization)
|
|
20
|
+
- [Security model](#security-model)
|
|
21
|
+
- [Extension points](#extension-points)
|
|
22
|
+
|
|
23
|
+
## Design principles
|
|
24
|
+
|
|
25
|
+
1. **The OS scheduler owns time.** The plugin never keeps a timer in memory for cron
|
|
26
|
+
jobs. Every recurring task becomes a real OS entry (Task Scheduler, launchd,
|
|
27
|
+
crontab), so jobs survive reboots and closed editor windows.
|
|
28
|
+
2. **The host process owns the UI.** Agent tools, the sidebar GUI, the RPC layer and the
|
|
29
|
+
dashboard live inside the OpenCode plugin host. They are stateless wrappers around
|
|
30
|
+
the database and the OS scheduler.
|
|
31
|
+
3. **Runs are independent processes.** A job executes `opencode run` through a wrapper
|
|
32
|
+
that enforces timeout, single-instance locking, pre/post hooks and a Quality Gate.
|
|
33
|
+
The wrapper reports the result back to the database, not to the plugin host.
|
|
34
|
+
4. **One source of truth for definitions is SQLite.** OS entries are derived artifacts:
|
|
35
|
+
they can always be recreated from the database with export/import.
|
|
36
|
+
5. **Local first.** No network services, no telemetry, no accounts by default. The dashboard binds
|
|
37
|
+
to localhost only. Local AI triage (Ollama) is optional and connects only when explicitly enabled
|
|
38
|
+
via `manage_local_ai`.
|
|
39
|
+
|
|
40
|
+
## Process model
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
┌─────────────────────────────┐
|
|
44
|
+
│ OpenCode (plugin host) │
|
|
45
|
+
│ • agent tools (25) │
|
|
46
|
+
│ • sidebar GUI (gui.tsx) │
|
|
47
|
+
│ • RPC ↔ sidebar │
|
|
48
|
+
│ • dashboard HTTP server │
|
|
49
|
+
│ • chokidar file watcher │
|
|
50
|
+
└──────────┬──────────────────┘
|
|
51
|
+
│ creates / updates
|
|
52
|
+
▼
|
|
53
|
+
┌─────────────────────────────┐ ┌──────────────────────────────┐
|
|
54
|
+
│ OS scheduler │ │ SQLite (scheduler.db) │
|
|
55
|
+
│ Windows Task Scheduler │ │ tasks, history, metrics, │
|
|
56
|
+
│ launchd / crontab │ │ templates, settings, │
|
|
57
|
+
└──────────┬──────────────────┘ │ workspaces │
|
|
58
|
+
│ fires │ └──────────────────────────────┘
|
|
59
|
+
▼ │ ▲
|
|
60
|
+
┌─────────────────────────────┐ │ │ writes
|
|
61
|
+
│ Run wrapper (.cmd / .sh) │ │ │
|
|
62
|
+
│ • lock │ │ ┌─────────┴──────────────┐
|
|
63
|
+
│ • timeout │ └──│ recorder process │
|
|
64
|
+
│ • pre-flight hook │ │ core/record-history.js │
|
|
65
|
+
│ • opencode run ... │────────▶│ • history / metrics │
|
|
66
|
+
│ • Quality Gate │ │ • retries, chains │
|
|
67
|
+
│ • post-flight hook │ │ • DAG dependents │
|
|
68
|
+
└─────────────────────────────┘ │ • matrix continuation │
|
|
69
|
+
└────────────────────────┘
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
There are four kinds of processes:
|
|
73
|
+
|
|
74
|
+
| Process | Lifetime | Responsibility |
|
|
75
|
+
| --- | --- | --- |
|
|
76
|
+
| Plugin host | OpenCode session | Register tools/skill, create OS entries, serve RPC and dashboard, watch files |
|
|
77
|
+
| OS scheduler | Always | Fire jobs on schedule or on demand |
|
|
78
|
+
| Run wrapper | Per run | Lock, timeout, hooks, Quality Gate, invoke `opencode run`, call the recorder |
|
|
79
|
+
| Recorder | Per run (short) | Persist history/metrics, schedule retries, trigger chains and dependents, continue matrices |
|
|
80
|
+
|
|
81
|
+
Because the recorder is a separate short-lived process, it cannot rely on in-memory
|
|
82
|
+
state of the plugin host. Everything it needs (definitions, retry state, matrix queue)
|
|
83
|
+
is read from the database or from files under the plugin directory.
|
|
84
|
+
|
|
85
|
+
## Data flow
|
|
86
|
+
|
|
87
|
+
**Create a task**
|
|
88
|
+
|
|
89
|
+
1. Agent tool / GUI / import calls `schedulerCreateTask(...)`.
|
|
90
|
+
2. Definitions are validated (cron, workspace path, matrix rules), a prompt file and a
|
|
91
|
+
wrapper script are written under the plugin directory; if the task's workspace has
|
|
92
|
+
env variables, `<PLUGIN_DIR>/env/<sanitized>.env` is written (mode `0600` on POSIX).
|
|
93
|
+
3. An OS entry is created through the platform backend.
|
|
94
|
+
4. The definition is stored in `tasks.definition_json`.
|
|
95
|
+
|
|
96
|
+
**Run a task**
|
|
97
|
+
|
|
98
|
+
1. The OS scheduler starts the wrapper.
|
|
99
|
+
2. When the task carries a schedule gate (poll-mode cron, foreign timezone or a
|
|
100
|
+
launch window), the wrapper first runs `node dist/core/schedule-gate.js`: it
|
|
101
|
+
re-checks the extended cron in the task's zone, and if now is outside the
|
|
102
|
+
launch window it waits until the window opens (postpone, deduplicated by a
|
|
103
|
+
defer-file) or exits with code 3 so the wrapper skips silently.
|
|
104
|
+
3. The wrapper acquires the lock (`locks/<task>.lock`), writes the log
|
|
105
|
+
(`logs/<task>.log`), loads workspace env from `<PLUGIN_DIR>/env/<sanitized>.env`
|
|
106
|
+
(Windows `-EnvFile`, POSIX `set -a; . "$ENV_FILE"; set +a`) before starting
|
|
107
|
+
`opencode run` with the prompt file. Output is streamed to the log.
|
|
108
|
+
4. When the process ends, the wrapper enforces the timeout result, runs the Quality
|
|
109
|
+
Gate and the post-flight hook.
|
|
110
|
+
5. The wrapper calls `node dist/core/record-history.js --finish ...` with status,
|
|
111
|
+
duration, tokens, cost, model and hook results.
|
|
112
|
+
6. The recorder writes `history` and updates `metrics`, then evaluates retries, task
|
|
113
|
+
chains, DAG dependents and matrix continuation.
|
|
114
|
+
|
|
115
|
+
**Read state**
|
|
116
|
+
|
|
117
|
+
`collectTasksView()` (shared by tools, RPC and GUI) merges definitions, the latest
|
|
118
|
+
history record and metrics into a `TaskItem`. Matrix parents get an aggregated status
|
|
119
|
+
from their clones instead of their own last run.
|
|
120
|
+
|
|
121
|
+
## Modules
|
|
122
|
+
|
|
123
|
+
| Path | Role |
|
|
124
|
+
| --- | --- |
|
|
125
|
+
| `src/index.ts` | Plugin lifecycle, 25 agent tools, RPC handlers, task CRUD, view assembly |
|
|
126
|
+
| `src/rpc.ts` | JSON-schema contracts for every RPC method |
|
|
127
|
+
| `src/gui.tsx` | OpenCode sidebar panel (SolidJS, built to `gui-experimental.cjs`) |
|
|
128
|
+
| `src/server.ts` | Local web dashboard HTTP server and HTML rendering |
|
|
129
|
+
| `src/skill.ts` | Loads and registers the bundled agent skill |
|
|
130
|
+
| `src/task-transfer.ts` | Export/import, validation, `MatrixConfig` types |
|
|
131
|
+
| `src/profiles.ts` | Profile directory resolution: per-profile plugin dir (base for `default`, `<base>/profiles/<name>` for named profiles); profile name, marker, port, create/delete/switch |
|
|
132
|
+
| `src/workspaces.ts` | Workspace registry and path validation; env pairs and `.env` file resolution with secret masking |
|
|
133
|
+
| `src/templates.ts` | Reusable task templates |
|
|
134
|
+
| `src/settings.ts` | Plugin settings: notifications, history retention, audit, interface locale (`auto`/`ru`/`en`/`zh`) and last known UI locale, local AI/triage |
|
|
135
|
+
| `src/i18n.ts` | Interface locale (`ru` default, `en`/`zh`), BCP 47 mapping, JSON catalogs in `locales/`, ICU subset (`{param}`, `plural`) via built-in `Intl`, fallback to `ru` |
|
|
136
|
+
| `src/notifications.ts` | Multi-channel delivery (webhook, Telegram, native OS) with retries/backoff, templates, task filters, quiet hours, matrix and stuck-clone notifications, daily/weekly digest |
|
|
137
|
+
| `src/core/telegram.ts` | Telegram Bot API `sendMessage`: parse-mode escaping, dashboard link, token validation and masking |
|
|
138
|
+
| `src/core/native-notify.ts` | Native OS notifications: Windows Toast (PowerShell/WinRT), macOS `osascript`, Linux `notify-send`; no external dependency |
|
|
139
|
+
| `src/core/secrets.ts` | Encrypted secret store (AES-256-GCM, `secrets.key` 0600, `${secret:NAME}` refs, redaction) |
|
|
140
|
+
| `src/core/audit.ts` | SQLite audit journal (`audit_log`), redacted details, retention cleanup |
|
|
141
|
+
| `src/history.ts` | History model and status types |
|
|
142
|
+
| `src/version.ts` | Runtime plugin version (reads package.json) |
|
|
143
|
+
| `src/core/retention.ts` | Daily history prune and incremental vacuum |
|
|
144
|
+
| `src/core/analytics.ts` | Pure 14-day analytics and CSV export |
|
|
145
|
+
| `src/core/scheduler/` | Platform backends, registry, logs |
|
|
146
|
+
| `src/core/ps-wrapper.ts` | PowerShell wrapper template and `.cmd` generation |
|
|
147
|
+
| `src/core/wrappers/bash.ts` | POSIX wrapper template |
|
|
148
|
+
| `src/core/record-history.ts` | Recorder: history, retries, chains, DAG, matrix continuation |
|
|
149
|
+
| `src/core/matrix.ts` | Fan-out, aggregation, sync, cancel, orphan cleanup |
|
|
150
|
+
| `src/core/dry-run.ts` | Pipeline simulation (no execution) |
|
|
151
|
+
| `src/core/lock.ts` | Single-instance lock manager |
|
|
152
|
+
| `src/core/file-watcher.ts` | chokidar-based file triggers |
|
|
153
|
+
| `src/core/local-ai.ts` | Local AI triage: LLM classifier with rules fallback, shadow mode, fail-open, manage_local_ai backing |
|
|
154
|
+
| `src/core/cron-to-schtasks.ts` | Cron → Task Scheduler translation |
|
|
155
|
+
| `src/core/schedule-v2.ts` | Extended cron parser/matcher, timezone math, launch windows, poll-mode decisions |
|
|
156
|
+
| `src/core/schedule-gate.ts` | Wrapper-side gate: cron re-check (poll mode), window postpone, defer-file |
|
|
157
|
+
| `src/db/` | SQLite access: schema, migrations, repositories, recovery |
|
|
158
|
+
| `src/shared/jobs-view.ts` | Task view shared by the GUI and dashboard |
|
|
159
|
+
|
|
160
|
+
## Scheduling backends
|
|
161
|
+
|
|
162
|
+
`scheduler/registry.ts` keeps the mapping between a task name and its OS entry.
|
|
163
|
+
`scheduler/index.ts` picks a backend from `process.platform`.
|
|
164
|
+
|
|
165
|
+
| Platform | Backend | Notes |
|
|
166
|
+
| --- | --- | --- |
|
|
167
|
+
| Windows | `schtasks.exe` | Cron is translated to `MINUTE/HOURLY/DAILY/WEEKLY/MONTHLY` flags; non-cron triggers are registered as `ONCE` at `31.12.2099` |
|
|
168
|
+
| Linux | `crontab` | Task lines with the plugin marker are rewritten via `crontab -` |
|
|
169
|
+
| macOS | `launchd` | `StartCalendarInterval` plists |
|
|
170
|
+
| POSIX fallback | `crontab` | Used when launchd is unavailable |
|
|
171
|
+
|
|
172
|
+
File and MCP triggers are not time-based. They are still registered as a far-future
|
|
173
|
+
one-shot entry so that `runMatrix`, DAG dependencies and manual runs can start them,
|
|
174
|
+
while the OS never fires them on its own. File triggers are additionally watched by
|
|
175
|
+
chokidar inside the plugin host.
|
|
176
|
+
|
|
177
|
+
## Run wrapper
|
|
178
|
+
|
|
179
|
+
The wrapper is generated per task and is the only place where execution policy is
|
|
180
|
+
enforced:
|
|
181
|
+
|
|
182
|
+
| Concern | Implementation |
|
|
183
|
+
| --- | --- |
|
|
184
|
+
| Working directory | Task `workingDirectory`, or the workspace path, or the plugin directory |
|
|
185
|
+
| Prompt | Written to a prompt file, passed to `opencode run` |
|
|
186
|
+
| Timeout | `timeoutSeconds`; on expiry the child process tree is stopped and the run is marked `timeout` |
|
|
187
|
+
| Workspace env | Variables from the workspace's `.env` file and explicit pairs are injected before `opencode run` (wrapper `env:` / `export`); secret-looking keys are masked in logs |
|
|
188
|
+
| No overlap | Lock file per task; a second start exits immediately and records `skipped` |
|
|
189
|
+
| Pre-flight | `beforeScript`; non-zero exit marks `preFlight` as failed |
|
|
190
|
+
| Quality Gate | `qualityGate` after a successful run; non-zero exit turns the run into an error |
|
|
191
|
+
| Post-flight | `afterScript`; non-zero exit is reported but does not rewrite a success |
|
|
192
|
+
| Logging | Append-only log per task under `logs/` |
|
|
193
|
+
| History | Calls the recorder with `--start` and `--finish` |
|
|
194
|
+
|
|
195
|
+
Windows uses PowerShell and `.cmd` shims; POSIX uses bash. Both wrappers are generated
|
|
196
|
+
from templates so the policy stays identical across platforms.
|
|
197
|
+
|
|
198
|
+
## History, metrics and recovery
|
|
199
|
+
|
|
200
|
+
`history` stores one row per run: status (`running`, `success`, `error`, `timeout`,
|
|
201
|
+
`partial`), start/finish timestamps, duration, error text, tokens, cost, model,
|
|
202
|
+
pre/post-flight results, the chained next task, workspace and tool restrictions.
|
|
203
|
+
`metrics` holds per-task counters and totals.
|
|
204
|
+
|
|
205
|
+
If the host or the machine dies mid-run, the row stays in `running`. On the next
|
|
206
|
+
plugin activation, `db/recovery.ts` marks stale `running` rows as `error`, so the UI
|
|
207
|
+
never shows a permanently running task.
|
|
208
|
+
|
|
209
|
+
History is bounded by retention: `settings.json` carries `history.retentionDays` and
|
|
210
|
+
`history.maxRecords` (defaults 30 / 5000, `0` disables). Cleanup runs at most once a
|
|
211
|
+
day on plugin start (`core/retention.ts`), prunes only finished rows via
|
|
212
|
+
`pruneHistory` in `db/history-repo.ts`, then `PRAGMA incremental_vacuum` frees space.
|
|
213
|
+
Aggregates in `metrics` are never pruned. Period analytics (per-day buckets, success
|
|
214
|
+
rate, tokens, cost, matrix/model breakdowns) are computed by `core/analytics.ts` and
|
|
215
|
+
exposed as `get_analytics` / `GET /api/analytics`; the dashboard renders a 14-day
|
|
216
|
+
block and `GET /api/history/export` serves CSV/JSON.
|
|
217
|
+
|
|
218
|
+
## Chains, retries and DAG
|
|
219
|
+
|
|
220
|
+
All three are evaluated by the recorder after a run finishes:
|
|
221
|
+
|
|
222
|
+
- **Retries** — `retryCount`/`retryDelay` with a retry-state file so a crash cannot
|
|
223
|
+
loop forever. Retries are attempted before chains and dependents.
|
|
224
|
+
- **Chains** — `nextTaskOnSuccess` / `nextTaskOnError` start exactly one follow-up task.
|
|
225
|
+
- **DAG** — `dependsOn` is satisfied only when every dependency's latest run is
|
|
226
|
+
successful. For a matrix dependency, all clones must be successful; the parent's own
|
|
227
|
+
aggregate record is not enough.
|
|
228
|
+
|
|
229
|
+
`selectDependentsToTrigger(taskName, definitions, history)` is a pure function, which
|
|
230
|
+
keeps the rules testable.
|
|
231
|
+
|
|
232
|
+
## Matrix builds
|
|
233
|
+
|
|
234
|
+
A matrix task is a template, not a runnable job:
|
|
235
|
+
|
|
236
|
+
1. `expandMatrixTask(parent)` produces one clone per workspace:
|
|
237
|
+
`<parent>-matrix-<workspace>`, each with its own `workspaceId`, `matrixParentId`,
|
|
238
|
+
a file trigger and per-workspace overrides applied.
|
|
239
|
+
2. `runMatrix(parent)` starts clones according to `strategy` (`parallel`/`sequential`)
|
|
240
|
+
and `concurrency`; extra clones wait in `matrixQueue` persisted on the parent.
|
|
241
|
+
3. On each clone completion, the recorder calls `advanceMatrixAfterClone` (drain the
|
|
242
|
+
queue or start the next sequential clone) and `finalizeMatrixIfComplete`.
|
|
243
|
+
4. `aggregateMatrixResults(parent)` derives `success` / `error` / `partial` / `running` /
|
|
244
|
+
`empty` from clone history.
|
|
245
|
+
5. `syncMatrixFamily(parent)` diffs existing clones against a fresh expansion on update:
|
|
246
|
+
missing clones are created, changed clones are updated, extra clones are removed.
|
|
247
|
+
Clones whose latest run is `running` are never touched.
|
|
248
|
+
|
|
249
|
+
The parent is registered in the OS scheduler as a far-future one-shot entry only so it
|
|
250
|
+
can be addressed by name; it never fires on its own.
|
|
251
|
+
|
|
252
|
+
## Workspaces
|
|
253
|
+
|
|
254
|
+
A workspace is a named directory (usually a git repository) with an id, path, optional
|
|
255
|
+
remote and color. Workspaces provide:
|
|
256
|
+
|
|
257
|
+
- the working directory for a task (`workspaceId` instead of `workingDirectory`);
|
|
258
|
+
- matrix targets (`matrix.workspaceIds`);
|
|
259
|
+
- per-workspace overrides (`matrix.overrides`);
|
|
260
|
+
- dashboard grouping;
|
|
261
|
+
- env variables: explicit `KEY=VALUE` pairs plus an optional `.env` file (loaded first,
|
|
262
|
+
explicit pairs override), injected into task runs via the wrapper; secret-looking
|
|
263
|
+
keys are masked in logs.
|
|
264
|
+
|
|
265
|
+
Paths are validated on creation, update and import: a workspace must point to an
|
|
266
|
+
existing directory. Env keys must match `^[A-Za-z_][A-Za-z0-9_]*$`; max 100 pairs.
|
|
267
|
+
|
|
268
|
+
## Triggers
|
|
269
|
+
|
|
270
|
+
| Trigger | How it fires |
|
|
271
|
+
| --- | --- |
|
|
272
|
+
| `cron` | OS scheduler on the translated schedule |
|
|
273
|
+
| `file` | chokidar watches `watchPath`; debounced change starts the task |
|
|
274
|
+
| `git` | Polls `HEAD` in the task working directory; runs when new commits match branch/path/ignore filters |
|
|
275
|
+
| `mcp-event` | `emit_event` RPC/tool matches server + event and starts subscribers |
|
|
276
|
+
|
|
277
|
+
Cron expressions are standard 5-field. The Windows backend supports the subset that
|
|
278
|
+
`schtasks` can express; unsupported shapes are rejected at creation time with a clear
|
|
279
|
+
error instead of silently drifting.
|
|
280
|
+
|
|
281
|
+
## Storage
|
|
282
|
+
|
|
283
|
+
Everything lives under the plugin directory:
|
|
284
|
+
|
|
285
|
+
| Platform | Path |
|
|
286
|
+
| --- | --- |
|
|
287
|
+
| Windows | `%APPDATA%\opencode\windows-scheduler` |
|
|
288
|
+
| macOS/Linux | `$XDG_CONFIG_HOME/opencode/windows-scheduler` (default `~/.config/...`) |
|
|
289
|
+
|
|
290
|
+
```
|
|
291
|
+
scheduler.db SQLite database (WAL)
|
|
292
|
+
logs/ per-task run logs
|
|
293
|
+
locks/ lock files
|
|
294
|
+
wrappers/ generated .cmd / .sh wrappers
|
|
295
|
+
prompts/ prompt files
|
|
296
|
+
env/ per-workspace env files (<task>.env), mode 0600 on POSIX
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
Named profiles (Sprint 21) each own a copy of this tree under
|
|
300
|
+
`<base>/profiles/<name>` (`default` uses the base directory). Profile directory,
|
|
301
|
+
database, settings, logs, wrappers and locks all resolve per-profile.
|
|
302
|
+
|
|
303
|
+
Override the database location with `OPENCODE_SCHEDULER_DB` (used by tests). Override
|
|
304
|
+
the whole plugin directory (database, logs, locks, wrappers, prompts) with
|
|
305
|
+
`OPENCODE_SCHEDULER_HOME` on any platform. Profile selection uses
|
|
306
|
+
`OPENCODE_SCHEDULER_PROFILE` > `active-profile` marker > `default`.
|
|
307
|
+
|
|
308
|
+
Schema evolution is additive: `applySchema` runs `CREATE TABLE IF NOT EXISTS` on every
|
|
309
|
+
connection and adds missing columns after `PRAGMA table_info`, so upgrading the plugin
|
|
310
|
+
never requires a manual migration.
|
|
311
|
+
|
|
312
|
+
## Interfaces
|
|
313
|
+
|
|
314
|
+
| Interface | Audience | Entry point |
|
|
315
|
+
| --- | --- | --- |
|
|
316
|
+
| Agent tools | AI agent | 26 tools registered via `ctx.tool.transform` |
|
|
317
|
+
| Agent skill | AI agent | `skills/scheduled-job-best-practices` |
|
|
318
|
+
| RPC | Sidebar GUI | `src/rpc.ts` contracts, 44 methods |
|
|
319
|
+
| Sidebar GUI | Human | `gui-experimental.cjs` |
|
|
320
|
+
| Web dashboard | Human | `startDashboardServer` (localhost, random/fixed port) |
|
|
321
|
+
|
|
322
|
+
## Localization
|
|
323
|
+
|
|
324
|
+
User-visible text lives in flat JSON catalogs: `locales/ru.json` (default),
|
|
325
|
+
`locales/en.json` and `locales/zh.json`. Keys are dot-separated and grouped by surface —
|
|
326
|
+
`gui.*`, `notify.*`, `tool.*`, `dryRun.*`, `matrix.*`, `schedule.*` — and all catalogs
|
|
327
|
+
must have the same key set with non-empty values.
|
|
328
|
+
|
|
329
|
+
`src/i18n.ts` loads the catalogs once and caches them. It exposes `t(key, params)`,
|
|
330
|
+
`setLocale(locale)`, `messageIn(locale, key)` and `hasKey(key, locale)`. Lookup order is
|
|
331
|
+
active locale → `en` → `ru` → the key itself, so a missing translation never renders as
|
|
332
|
+
an empty string. The `locale` setting (`ru` default, `en`/`zh` optional, `auto` follows
|
|
333
|
+
the OpenCode interface language) is applied immediately, without restarting OpenCode.
|
|
334
|
+
`auto` is resolved in the GUI through `ctx.locale.locale()` with BCP 47 prefix mapping
|
|
335
|
+
(`zh-CN` → `zh`, `en-GB` → `en`); the resolved value is sent to the server as `uiLocale`,
|
|
336
|
+
because the server process cannot see the window. The sidebar GUI embeds the catalogs at
|
|
337
|
+
build time via `registerCatalog`, because a webview bundle cannot read package files at
|
|
338
|
+
runtime.
|
|
339
|
+
|
|
340
|
+
The template subset is deliberately small and dependency-free:
|
|
341
|
+
|
|
342
|
+
- `{name}` — interpolation; the caller formats the value (duration, money, date).
|
|
343
|
+
- `{count, plural, one {…} few {…} many {…} other {…}}` — plural forms through
|
|
344
|
+
`Intl.PluralRules` for the active locale (`ru` uses one/few/many, `en` one/other,
|
|
345
|
+
`zh` only `other`).
|
|
346
|
+
|
|
347
|
+
Rules:
|
|
348
|
+
|
|
349
|
+
- a user-visible message is a whole phrase in the catalog, including punctuation; never
|
|
350
|
+
concatenate translated fragments;
|
|
351
|
+
- store stable codes, not localized text, in the database; translate at render time;
|
|
352
|
+
- agent tool descriptions, schemas and API payloads stay English; `console.*`
|
|
353
|
+
diagnostics stay Russian;
|
|
354
|
+
- add every new key to all catalogs. `test-docs.mjs` enforces parity and non-empty
|
|
355
|
+
values; `npm run test:en` and `npm run test:zh` replay all suites under `en`/`zh` and
|
|
356
|
+
CI runs them. `OPENCODE_SCHEDULER_LOCALE` only overrides the initial locale for tests
|
|
357
|
+
and services — it is not a user-facing setting.
|
|
358
|
+
|
|
359
|
+
## Security model
|
|
360
|
+
|
|
361
|
+
- The dashboard has **no authentication** and binds to localhost. Do not expose it.
|
|
362
|
+
- A job definition is **code**: prompts, hooks, Quality Gates and wrappers all execute
|
|
363
|
+
with your user privileges. Treat task creation like granting shell access.
|
|
364
|
+
- `allowedTools` / `deniedTools` are **enforced at the run-wrapper level** (Sprint 29.2).
|
|
365
|
+
Before each `opencode run`, the wrapper passes `permissions` rules through
|
|
366
|
+
`OPENCODE_CONFIG_CONTENT`: `deniedTools` are mapped to `effect: "deny"` for the
|
|
367
|
+
corresponding OpenCode action (`shell`, `edit`, `glob`, `grep`, `webfetch`,
|
|
368
|
+
`websearch`, `question`, `subagent`, `skill`), and `allowedTools` (if specified)
|
|
369
|
+
additionally denies every action not in the list. No config file is written, so a
|
|
370
|
+
project-level `opencode.jsonc` is preserved and parallel tasks in one workdir do not
|
|
371
|
+
race. The wrapper passes `--auto` so non-denied permissions are auto-approved.
|
|
372
|
+
`allowedTools`/`deniedTools` metadata is still recorded in history for audit.
|
|
373
|
+
- **Default policy (`src/core/permissions.ts`):** the baseline is
|
|
374
|
+
`permissions.defaultPolicy` — `hybrid` (default) denies `shell` and `question` while
|
|
375
|
+
allowing read/edit/glob/grep/subagent/skill/webfetch/websearch, `secure` allows only
|
|
376
|
+
read/glob/grep/skill, `legacy` allows everything (1.5.x behaviour). Task `legacyShell`
|
|
377
|
+
re-enables `shell` under `hybrid`; `deniedTools` still wins. Policy denials are
|
|
378
|
+
audited as `tool.blocked` with `reason: "default-policy"`, and each wrapper logs
|
|
379
|
+
`policy=<name>, denied=<actions>` before the run.
|
|
380
|
+
- **Audit of blocked tools (Sprint 29.4):** when a task definition is saved,
|
|
381
|
+
`recordTaskToolBlocks()` writes one `tool.blocked` audit event per entry in
|
|
382
|
+
`deniedTools` (`target` = task name, `details.tool` = tool, plus `allowedTools`,
|
|
383
|
+
`deniedTools` and `reason`). In allow-list mode one event with `tool: "*"` records
|
|
384
|
+
that every unlisted tool is denied. The event is emitted on create and on update, so
|
|
385
|
+
changing the task policy also changes the audited details. Because the wrapper runs
|
|
386
|
+
`opencode` as an external process, the plugin cannot observe individual blocked
|
|
387
|
+
attempts at runtime; the audit reflects the enforced policy, not each refusal.
|
|
388
|
+
- Task prompts, hooks and Quality Gate scripts are **plain text** executed with your
|
|
389
|
+
user privileges; only secrets (in `secrets.json`, AES-256-GCM) are encrypted.
|
|
390
|
+
Workspace `env` can reference secrets as `${secret:NAME}`; values are masked in
|
|
391
|
+
logs, history and audit. Treat task creation like granting shell access.
|
|
392
|
+
- Secrets are stored encrypted in `<PLUGIN_DIR>/secrets.json` (AES-256-GCM) with a
|
|
393
|
+
32-byte key file `secrets.key` (mode 0600 on POSIX; on Windows an ACL that removes
|
|
394
|
+
inheritance and grants the current user only, applied by `icacls` on create and
|
|
395
|
+
re-applied on read for keys created before 1.5.5). Workspace `env` can reference them
|
|
396
|
+
as `${secret:NAME}`; values are substituted at run time and masked in logs,
|
|
397
|
+
history and audit.
|
|
398
|
+
- Workspace paths are validated, but hooks are not sandboxed: only schedule jobs from
|
|
399
|
+
repositories you trust.
|
|
400
|
+
|
|
401
|
+
### Permission model
|
|
402
|
+
|
|
403
|
+
The effective policy is resolved in this order (later wins):
|
|
404
|
+
|
|
405
|
+
1. `permissions.defaultPolicy` — the baseline: `hybrid` (default, no `shell`/`question`),
|
|
406
|
+
`secure` (read-only) or `legacy` (everything allowed, 1.5.x behaviour).
|
|
407
|
+
2. Task `legacyShell` — re-enables `shell` under `hybrid` only.
|
|
408
|
+
3. Task `allowedTools` — if present, every action not listed is denied; an explicitly
|
|
409
|
+
listed action can override a policy denial.
|
|
410
|
+
4. Task `deniedTools` — always denied and takes priority over `allowedTools`.
|
|
411
|
+
5. The generated `OPENCODE_CONFIG_CONTENT` — passed in the wrapper environment; no file
|
|
412
|
+
is written and the project config stays untouched.
|
|
413
|
+
6. Project `opencode.json(c)` and system config — merged by OpenCode; a closer or
|
|
414
|
+
system-level config can weaken task-scoped denies (see limitations below).
|
|
415
|
+
7. `--auto` — auto-approves everything that remains, so no interactive prompts block
|
|
416
|
+
an unattended run.
|
|
417
|
+
|
|
418
|
+
Tool mapping used by both wrappers:
|
|
419
|
+
|
|
420
|
+
| Task tool | OpenCode action |
|
|
421
|
+
| --- | --- |
|
|
422
|
+
| `bash`, `shell` | `shell` |
|
|
423
|
+
| `write`, `edit`, `apply_patch`, `remove` | `edit` |
|
|
424
|
+
| `glob`, `grep`, `webfetch`, `websearch` | same name |
|
|
425
|
+
| `question`, `subagent`, `skill` | same name |
|
|
426
|
+
|
|
427
|
+
Hooks, Quality Gates and wrapper scripts are outside this model: they run before or
|
|
428
|
+
after the agent with the user's privileges and are not filtered by tool policy.
|
|
429
|
+
|
|
430
|
+
### Permission enforcement — known limitations (spike 29.1 findings)
|
|
431
|
+
|
|
432
|
+
- `opencode run` CLI (v2.2.3) supports only `--auto` (auto-approve non-denied
|
|
433
|
+
permissions). There are **no** `--allow-tool` / `--deny-tool` CLI flags, so
|
|
434
|
+
per-task restrictions cannot be passed via arguments. Enforcement is done by
|
|
435
|
+
generating a task-scoped config and passing it through `OPENCODE_CONFIG_CONTENT`.
|
|
436
|
+
- OpenCode merges `opencode.json(c)` from the current directory up to the filesystem
|
|
437
|
+
root. A project-level `opencode.jsonc` with permissive rules can override or weaken
|
|
438
|
+
task-scoped denies (last matching rule wins, closer directory wins for merge).
|
|
439
|
+
System config (`/etc/opencode`, `%ProgramData%\opencode`) overrides project config.
|
|
440
|
+
- Nested agent calls (subagents) use their **own** permissions, not a subset of the
|
|
441
|
+
parent's. A task that denies `subagent` prevents launching subagents, but a launched
|
|
442
|
+
subagent is not further restricted by the parent task's policy.
|
|
443
|
+
- **Plan B**: if the task-scoped config passed via `OPENCODE_CONFIG_CONTENT` proves
|
|
444
|
+
insufficient, enforcement can be moved to wrapper-level tool filtering (intercepting
|
|
445
|
+
`opencode run` invocation and refusing to start when a denied tool would be needed)
|
|
446
|
+
or to a managed system-level `policies` entry that hard-denies specific tools
|
|
447
|
+
globally.
|
|
448
|
+
|
|
449
|
+
## Extension points
|
|
450
|
+
|
|
451
|
+
| Goal | Where to start |
|
|
452
|
+
| --- | --- |
|
|
453
|
+
| New OS backend | Implement `SchedulerBackend` in `src/core/scheduler/`, register it in `index.ts` |
|
|
454
|
+
| New trigger type | Add a `triggerType` branch in `schedulerCreateTask` and in the wrapper |
|
|
455
|
+
| New agent tool | Add a zod schema + execute function, register in `ctx.tool.transform`, add an RPC contract |
|
|
456
|
+
| New dashboard panel | Extend `server.ts` routes and the HTML template |
|
|
457
|
+
| New matrix policy | Extend `MatrixConfig` in `task-transfer.ts` and the logic in `core/matrix.ts` |
|