Changeset 0.27.0 (#166)
This commit is contained in:
842
docs/DESIGN-0.27.0.md
Normal file
842
docs/DESIGN-0.27.0.md
Normal file
@@ -0,0 +1,842 @@
|
||||
# DESIGN — v0.27.0+: Debt Clearance, Extension Surfaces, Tasks
|
||||
|
||||
**Status:** Draft
|
||||
**Scope:** Deferred debt clearance (v0.27.0), Tasks / Autonomous Agents (v0.27.x), TBD pull-forward (v0.28.0)
|
||||
**Depends on:** Workflow Engine (v0.26.0), Dynamic Surfaces (v0.25.0), Permissions (v0.24.2)
|
||||
**Current version:** 0.26.5
|
||||
|
||||
---
|
||||
|
||||
## Versioning Plan
|
||||
|
||||
```
|
||||
v0.27.0 Debt Clearance: Extension Surface Routes + Workflow Polish
|
||||
│
|
||||
v0.27.1 Tasks Foundation: Service Channels + Scheduler
|
||||
│
|
||||
v0.27.2 Task Execution: Budgets + Admin Controls
|
||||
│
|
||||
v0.27.3 Task Chaining: Webhooks + Workflow-to-Workflow
|
||||
│
|
||||
v0.27.4 Personal Tasks: BYOK Scheduling + User Task UI
|
||||
│
|
||||
v0.28.0 Platform Polish (TBD pull-forward)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Code Audit — Items Already Shipped
|
||||
|
||||
The ROADMAP lists these as deferred but the code proves they're done:
|
||||
|
||||
| Item | Evidence | Listed as deferred in |
|
||||
|------|----------|----------------------|
|
||||
| Persona tool grant enforcement in completion handler | `completion.go:928–949` — second-pass allowlist via `GetToolGrants()` | v0.25.0, v0.26.0 |
|
||||
| Version snapshot includes persona tool grants | `workflows.go:263–273` — `stageSnapshot.ToolGrants` populated at publish | v0.25.0 |
|
||||
| Session cleanup job | Shipped in v0.26.0 (background goroutine, `SESSION_EXPIRY_DAYS`) | v0.24.3 |
|
||||
|
||||
**Action:** Cross off all three in the ROADMAP's deferred sections and in
|
||||
the v0.25.0 / v0.26.0 milestone checklists.
|
||||
|
||||
---
|
||||
|
||||
## v0.27.0 — Debt Clearance
|
||||
|
||||
All deferred items from v0.25.0 and v0.26.0 plus outstanding tech debt
|
||||
that blocks future work. No new features — just finishing what's owed.
|
||||
|
||||
### Phase 1: Extension Surface Routes (`/s/:slug`)
|
||||
|
||||
The longest-deferred item (originally v0.21.3). Infrastructure exists:
|
||||
`surface_registry` table, `InstallSurface` handler (zip upload + asset
|
||||
extraction), `ListEnabledSurfaces` API. What's missing is the runtime
|
||||
route mounting, template rendering, and frontend nav integration.
|
||||
|
||||
**Problem: Hardcoded surface conditionals in `base.html`**
|
||||
|
||||
Lines 61–66 and 118–122 of `base.html` use `{{if eq .Surface "chat"}}`
|
||||
chains. Extension surfaces fall through to "Unknown surface". Same
|
||||
pattern for CSS includes (line 25–26) and script includes (118–122).
|
||||
|
||||
**Solution: Generic extension surface template + dynamic blocks**
|
||||
|
||||
```
|
||||
base.html changes:
|
||||
{{if eq .Surface "chat"}}...
|
||||
{{else if eq .Surface "admin"}}...
|
||||
...
|
||||
{{else if .Manifest}}{{template "surface-extension" .}}
|
||||
{{else}}<div>Unknown surface: {{.Surface}}</div>
|
||||
{{end}}
|
||||
```
|
||||
|
||||
New template `templates/surfaces/extension.html`:
|
||||
```html
|
||||
{{define "surface-extension"}}
|
||||
<div id="extension-surface" class="extension-surface"
|
||||
data-surface-id="{{.Surface}}"
|
||||
data-manifest='{{.Manifest | toJSON}}'>
|
||||
{{/* Extension JS mounts into this container */}}
|
||||
<div id="extension-mount"></div>
|
||||
</div>
|
||||
{{end}}
|
||||
|
||||
{{define "css-extension"}}
|
||||
{{/* Extension CSS loaded dynamically from surfacesDir */}}
|
||||
{{if .Manifest}}
|
||||
<link rel="stylesheet" href="{{.BasePath}}/surfaces/{{.Surface}}/css/main.css?v={{.Version}}">
|
||||
{{end}}
|
||||
{{end}}
|
||||
|
||||
{{define "scripts-extension"}}
|
||||
{{if .Manifest}}
|
||||
<script nonce="{{.CSPNonce}}" src="{{.BasePath}}/surfaces/{{.Surface}}/js/main.js?v={{.Version}}"></script>
|
||||
{{end}}
|
||||
{{end}}
|
||||
```
|
||||
|
||||
**Dynamic route registration at startup:**
|
||||
|
||||
```go
|
||||
// pages.go — New() after registerCoreSurfaces():
|
||||
func (e *Engine) loadExtensionSurfaces() {
|
||||
if e.stores.Surfaces == nil {
|
||||
return
|
||||
}
|
||||
ctx := context.Background()
|
||||
surfaces, err := e.stores.Surfaces.List(ctx)
|
||||
if err != nil {
|
||||
log.Printf("[pages] Failed to load extension surfaces: %v", err)
|
||||
return
|
||||
}
|
||||
for _, sr := range surfaces {
|
||||
if sr.Source == "core" {
|
||||
continue // Core surfaces already registered
|
||||
}
|
||||
route, _ := sr.Manifest["route"].(string)
|
||||
if route == "" {
|
||||
route = "/s/" + sr.ID // Default to /s/:id
|
||||
}
|
||||
manifest := SurfaceManifest{
|
||||
ID: sr.ID,
|
||||
Route: route,
|
||||
Title: sr.Title,
|
||||
Template: "surface-extension",
|
||||
Auth: authFromManifest(sr.Manifest), // default "authenticated"
|
||||
Layout: layoutFromManifest(sr.Manifest),
|
||||
Source: "extension",
|
||||
}
|
||||
e.surfaces = append(e.surfaces, manifest)
|
||||
}
|
||||
log.Printf("[pages] Loaded %d extension surfaces from registry",
|
||||
len(surfaces) - countCore(surfaces))
|
||||
}
|
||||
```
|
||||
|
||||
**nginx config — serve extension static assets:**
|
||||
|
||||
```nginx
|
||||
# Extension surface assets
|
||||
location /surfaces/ {
|
||||
alias /data/surfaces/;
|
||||
expires 1h;
|
||||
add_header Cache-Control "public, immutable";
|
||||
}
|
||||
```
|
||||
|
||||
**Frontend nav integration:**
|
||||
|
||||
`ListEnabledSurfaces` API already returns route + title for all enabled
|
||||
surfaces. The sidebar/nav needs to render extension surfaces as
|
||||
additional items. Extension surfaces appear in a "Surfaces" section
|
||||
of the sidebar, below the core nav items.
|
||||
|
||||
```js
|
||||
// app.js or pages.js — on init:
|
||||
const surfaces = await App.api.get('/api/v1/surfaces');
|
||||
surfaces.filter(s => !['chat','admin','settings','editor','notes'].includes(s.id))
|
||||
.forEach(s => renderExtensionNavItem(s));
|
||||
```
|
||||
|
||||
**Extension surface manifest contract (`.surface` archive):**
|
||||
|
||||
```
|
||||
my-dashboard.surface (zip)
|
||||
├── manifest.json
|
||||
├── js/
|
||||
│ └── main.js ← entry point, mounts into #extension-mount
|
||||
├── css/
|
||||
│ └── main.css ← scoped styles
|
||||
└── assets/ ← images, fonts, etc.
|
||||
```
|
||||
|
||||
`manifest.json`:
|
||||
```json
|
||||
{
|
||||
"id": "my-dashboard",
|
||||
"title": "Dashboard",
|
||||
"route": "/s/dashboard",
|
||||
"auth": "authenticated",
|
||||
"layout": "single",
|
||||
"components": ["chat-pane"],
|
||||
"hooks": ["surface"]
|
||||
}
|
||||
```
|
||||
|
||||
The extension JS receives the standard `ctx` object (same extension API
|
||||
from v0.11.0) plus access to platform components:
|
||||
|
||||
```js
|
||||
// main.js — extension surface entry point
|
||||
(function() {
|
||||
const mount = document.getElementById('extension-mount');
|
||||
const manifest = JSON.parse(
|
||||
document.getElementById('extension-surface').dataset.manifest
|
||||
);
|
||||
|
||||
// Full access to platform primitives + components
|
||||
const chatPane = window.ChatPane?.create(mount, { role: 'assist' });
|
||||
|
||||
// Build custom UI
|
||||
mount.innerHTML = '<h1>My Dashboard</h1>';
|
||||
})();
|
||||
```
|
||||
|
||||
**Admin UI additions:**
|
||||
|
||||
The admin surfaces section (already exists) gains:
|
||||
- Upload button (already wired to `InstallSurface`)
|
||||
- Enable/disable toggles (already wired)
|
||||
- Uninstall button (already wired to `DeleteSurface`)
|
||||
- Route display showing the `/s/:slug` URL
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] `surface-extension` template (HTML + CSS + scripts blocks)
|
||||
- [ ] `base.html` conditional chain extended with `{{if .Manifest}}` fallthrough
|
||||
- [ ] `loadExtensionSurfaces()` in page engine
|
||||
- [ ] nginx location block for `/surfaces/` static assets
|
||||
- [ ] Frontend nav renders extension surfaces from `ListEnabledSurfaces`
|
||||
- [ ] Admin surfaces section shows upload/enable/disable/uninstall
|
||||
- [ ] Sample `.surface` archive (hello-world dashboard) for testing
|
||||
- [ ] CSP nonce propagation for extension scripts
|
||||
|
||||
|
||||
### Phase 2: Workflow Engine Polish
|
||||
|
||||
Eight items deferred from v0.26.0. All backend infrastructure exists;
|
||||
these are wiring, UI, and enforcement.
|
||||
|
||||
**Channel header stage indicator + advance/reject controls**
|
||||
- Workflow channels show: stage name, step N of M, assignment info
|
||||
- Advance / Reject buttons (permission-gated by `workflow.manage`)
|
||||
- Renders in the chat header area (same slot as `ai_mode` context banner)
|
||||
|
||||
**Stage persona auto-switch in chat UI**
|
||||
- On stage transition, chat UI updates the active persona display
|
||||
- Model selector reflects the stage persona's bound model
|
||||
- System prompt injection already works (v0.26.4); this is FE-only
|
||||
|
||||
**Assignment notifications via WebSocket**
|
||||
- New workflow assignment → `workflow.assigned` WS event to team members
|
||||
- Claim confirmation → `workflow.claimed` WS event to claimer
|
||||
- Uses existing notification infrastructure (v0.20.0)
|
||||
|
||||
**Round-robin auto-assignment**
|
||||
- Per-stage `transition_rules.auto_assign: "round_robin"` in `workflow_stages`
|
||||
- On stage entry: query team members, pick least-recently-assigned
|
||||
- `workflow_assignments.assigned_to` populated automatically
|
||||
- Falls back to unassigned pool if round-robin fails
|
||||
|
||||
**`on_complete` workflow chaining**
|
||||
- Column exists on `workflows` table (nullable JSONB, v0.26.1)
|
||||
- Schema: `{"action": "start_workflow", "target_slug": "...", "data_map": {...}}`
|
||||
- On workflow completion: if `on_complete` is non-null, start target workflow
|
||||
with mapped `stage_data` from completed instance
|
||||
- Reuses existing `StartInstance()` path
|
||||
|
||||
**Workflow retention enforcement**
|
||||
- Column exists on `workflows` table (`retention` JSONB, v0.26.1)
|
||||
- Background sweep (extend staleness goroutine): completed instances
|
||||
older than `retention.delete_after_days` → hard delete
|
||||
- `retention.mode = "archive"` → set `workflow_status = 'archived'`,
|
||||
`ai_mode = 'off'` (already implemented for channel archive)
|
||||
|
||||
**Drag-and-drop stage reorder in builder**
|
||||
- Backend `PATCH /api/v1/workflows/:id/stages/reorder` already exists
|
||||
- Frontend: HTML5 drag events on stage list items in workflow builder
|
||||
- Same DnD pattern as channel/folder reorder (v0.23.1)
|
||||
|
||||
**Team-scoped workflow management UI**
|
||||
- Team admin settings surface gains "Workflows" section
|
||||
- Lists workflows owned by the team, quick-edit name/description
|
||||
- Links to full builder for stage editing
|
||||
- Mirrors the admin-level builder but scoped to `team_id`
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Channel header workflow stage indicator component
|
||||
- [ ] Advance/reject buttons with permission gate
|
||||
- [ ] Stage persona auto-switch in chat UI
|
||||
- [ ] `workflow.assigned` / `workflow.claimed` WS events
|
||||
- [ ] Round-robin auto-assignment in stage transition handler
|
||||
- [ ] `on_complete` chaining trigger in workflow completion path
|
||||
- [ ] Retention enforcement in staleness sweep goroutine
|
||||
- [ ] Drag-and-drop stage reorder in workflow builder UI
|
||||
- [ ] Team settings → Workflows section
|
||||
|
||||
|
||||
### Phase 3: Workspace + Editor Debt
|
||||
|
||||
Items deferred from v0.21.x that are low-hanging fruit.
|
||||
|
||||
- [ ] `.gitignore` respect in workspace indexing (`workspace/indexer.go` — skip paths matching patterns from `.gitignore` in workspace root)
|
||||
- [ ] Workspace settings UI: git config section in channel/project settings (remote URL, branch, auto-commit toggle)
|
||||
- [ ] Pane state persistence per-user/per-project (save pane layout to `user_settings` JSONB, restore on surface load)
|
||||
- [ ] Editor drag-drop file reorder (workspace file tree — reorder via DnD, persist order in workspace metadata)
|
||||
|
||||
**Explicitly deferred (not v0.27.0):**
|
||||
- User settings git credentials management UI — needs vault-encrypted git credential store (v0.28.0 candidate)
|
||||
- Integration tests: clone/commit/push/pull — needs git binary in CI container
|
||||
- Article-specific AI tools — needs article surface rebuild
|
||||
- Mobile hamburger nav — needs responsive audit pass
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] `.gitignore` filter in `workspace/indexer.go`
|
||||
- [ ] Git config section in workspace/project settings UI
|
||||
- [ ] Pane layout persistence in `user_settings`
|
||||
- [ ] Editor file tree DnD reorder
|
||||
|
||||
|
||||
### ROADMAP Cleanup
|
||||
|
||||
Update the ROADMAP itself:
|
||||
- [ ] Cross off tool grant enforcement (3 locations)
|
||||
- [ ] Move "Deferred to v0.27.0" items under their proper v0.27.0 section
|
||||
- [ ] Remove duplicate entries (extension surface routes listed 4× across the file)
|
||||
- [ ] Add v0.27.0 section with phase structure
|
||||
- [ ] Update dependency graph
|
||||
|
||||
---
|
||||
|
||||
## v0.27.1 — Tasks Foundation: Service Channels + Scheduler
|
||||
|
||||
The core primitive: a channel with no human participant, driven by
|
||||
a scheduler.
|
||||
|
||||
### Service Channels
|
||||
|
||||
`type: 'service'` — a new channel type. Service channels:
|
||||
- Have zero human participants (only persona participants)
|
||||
- Cannot be joined by users (read-only view for authorized users)
|
||||
- Are created by the scheduler or the `task_create` tool
|
||||
- Inherit the workflow engine's stage model (optional — simple tasks
|
||||
skip stages entirely)
|
||||
- Appear in a "Tasks" sidebar section (collapsed by default)
|
||||
|
||||
```sql
|
||||
-- No new migration needed — channel type CHECK already allows extension.
|
||||
-- Add 'service' to the channel type CHECK constraint:
|
||||
ALTER TABLE channels DROP CONSTRAINT IF EXISTS channels_type_check;
|
||||
ALTER TABLE channels ADD CONSTRAINT channels_type_check
|
||||
CHECK (type IN ('direct','dm','group','channel','workflow','service'));
|
||||
```
|
||||
|
||||
### Task Definitions
|
||||
|
||||
A task is a lightweight scheduled job that creates a service channel
|
||||
and runs a completion (or instantiates a workflow).
|
||||
|
||||
**`tasks` table:**
|
||||
```sql
|
||||
CREATE TABLE tasks (
|
||||
id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
|
||||
owner_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
|
||||
team_id TEXT REFERENCES teams(id) ON DELETE SET NULL,
|
||||
name TEXT NOT NULL,
|
||||
description TEXT,
|
||||
scope TEXT NOT NULL DEFAULT 'personal'
|
||||
CHECK (scope IN ('personal', 'team', 'global')),
|
||||
|
||||
-- What to run
|
||||
task_type TEXT NOT NULL DEFAULT 'prompt'
|
||||
CHECK (task_type IN ('prompt', 'workflow')),
|
||||
persona_id TEXT REFERENCES personas(id) ON DELETE SET NULL,
|
||||
model_id TEXT, -- explicit model override (nullable)
|
||||
system_prompt TEXT, -- additional system prompt (prepended)
|
||||
user_prompt TEXT, -- the message to send
|
||||
workflow_id TEXT REFERENCES workflows(id) ON DELETE SET NULL,
|
||||
tool_grants JSONB, -- explicit tool allowlist (nullable = inherit all)
|
||||
|
||||
-- Schedule
|
||||
schedule TEXT NOT NULL, -- cron expression (5-field)
|
||||
timezone TEXT NOT NULL DEFAULT 'UTC',
|
||||
is_active BOOLEAN NOT NULL DEFAULT true,
|
||||
|
||||
-- Execution policy
|
||||
max_tokens INTEGER NOT NULL DEFAULT 4096,
|
||||
max_tool_calls INTEGER NOT NULL DEFAULT 10,
|
||||
max_wall_clock INTEGER NOT NULL DEFAULT 300, -- seconds
|
||||
output_mode TEXT NOT NULL DEFAULT 'channel'
|
||||
CHECK (output_mode IN ('channel', 'note', 'webhook')),
|
||||
output_channel_id TEXT REFERENCES channels(id) ON DELETE SET NULL,
|
||||
webhook_url TEXT,
|
||||
|
||||
-- Provider routing
|
||||
provider_config_id TEXT REFERENCES provider_configs(id) ON DELETE SET NULL,
|
||||
|
||||
-- Notifications
|
||||
notify_on_complete BOOLEAN NOT NULL DEFAULT false,
|
||||
notify_on_failure BOOLEAN NOT NULL DEFAULT true,
|
||||
|
||||
-- Bookkeeping
|
||||
last_run_at TIMESTAMPTZ,
|
||||
next_run_at TIMESTAMPTZ,
|
||||
run_count INTEGER NOT NULL DEFAULT 0,
|
||||
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
|
||||
);
|
||||
|
||||
CREATE INDEX idx_tasks_next_run ON tasks (next_run_at) WHERE is_active = true;
|
||||
CREATE INDEX idx_tasks_owner ON tasks (owner_id);
|
||||
```
|
||||
|
||||
**Two task types:**
|
||||
|
||||
1. **Prompt task** (`task_type = 'prompt'`): Create a service channel,
|
||||
send `user_prompt` with `system_prompt` prepended, collect response.
|
||||
Simple, single-turn. Good for: news digest, stock screener, daily
|
||||
standup prep, report generation.
|
||||
|
||||
2. **Workflow task** (`task_type = 'workflow'`): Instantiate a workflow
|
||||
in a service channel. Multi-stage, tool-using, potentially long-running.
|
||||
Good for: data pipeline, automated review, research agent.
|
||||
|
||||
### Scheduler
|
||||
|
||||
Background goroutine (same pattern as compaction scanner, staleness sweep):
|
||||
|
||||
```go
|
||||
type TaskScheduler struct {
|
||||
stores store.Stores
|
||||
interval time.Duration // poll interval: 30s
|
||||
stop chan struct{}
|
||||
}
|
||||
|
||||
func (s *TaskScheduler) Run() {
|
||||
ticker := time.NewTicker(s.interval)
|
||||
for {
|
||||
select {
|
||||
case <-ticker.C:
|
||||
s.poll()
|
||||
case <-s.stop:
|
||||
return
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func (s *TaskScheduler) poll() {
|
||||
// SELECT * FROM tasks WHERE is_active AND next_run_at <= now()
|
||||
// ORDER BY next_run_at LIMIT 10
|
||||
due, _ := s.stores.Tasks.ListDue(ctx)
|
||||
for _, task := range due {
|
||||
go s.execute(task)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cron parsing: use `github.com/robfig/cron/v3` for 5-field expressions.
|
||||
Compute `next_run_at` after each execution.
|
||||
|
||||
### Provider Resolution for Tasks
|
||||
|
||||
Task execution needs a provider. Resolution order:
|
||||
|
||||
1. Explicit `provider_config_id` on task (user chose a specific provider)
|
||||
2. Personal BYOK provider (if `scope = 'personal'` and user has BYOK keys)
|
||||
3. Team provider (if `scope = 'team'`)
|
||||
4. Global provider (fallback)
|
||||
5. Routing policy (if task's model matches a routing policy)
|
||||
|
||||
This is the same resolution chain as completions, reusing the existing
|
||||
`resolveProvider()` path in `completion.go`.
|
||||
|
||||
### Migration
|
||||
|
||||
- 026_tasks.sql: `tasks` table, service channel type extension
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] `tasks` table + store interface + PG/SQLite implementations
|
||||
- [ ] `type: 'service'` channel type
|
||||
- [ ] `TaskScheduler` background goroutine
|
||||
- [ ] Cron expression parsing + `next_run_at` computation
|
||||
- [ ] Task execution path (create service channel, run completion)
|
||||
- [ ] Provider resolution for task context
|
||||
- [ ] Tasks sidebar section (read-only view of service channels)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v0.27.2 — Task Execution: Budgets + Admin Controls
|
||||
|
||||
### Execution Budgets
|
||||
|
||||
Three limits enforced in the task execution path:
|
||||
|
||||
1. **`max_tokens`** — total output tokens. Tracked via existing
|
||||
`usage_log` infrastructure. Execution halts mid-stream if exceeded.
|
||||
2. **`max_tool_calls`** — total tool invocations per run. Counter
|
||||
incremented in `streamWithToolLoop`. Execution halts on breach.
|
||||
3. **`max_wall_clock`** — seconds. `context.WithTimeout` on the
|
||||
execution goroutine. Hard kill on timeout.
|
||||
|
||||
Budget breach → task marked as `budget_exceeded` in run history,
|
||||
notification to owner.
|
||||
|
||||
### Task Run History
|
||||
|
||||
**`task_runs` table:**
|
||||
```sql
|
||||
CREATE TABLE task_runs (
|
||||
id TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
|
||||
task_id TEXT NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
|
||||
channel_id TEXT REFERENCES channels(id) ON DELETE SET NULL,
|
||||
status TEXT NOT NULL DEFAULT 'running'
|
||||
CHECK (status IN ('running','completed','failed',
|
||||
'budget_exceeded','cancelled')),
|
||||
started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
|
||||
completed_at TIMESTAMPTZ,
|
||||
tokens_used INTEGER DEFAULT 0,
|
||||
tool_calls INTEGER DEFAULT 0,
|
||||
wall_clock INTEGER DEFAULT 0, -- seconds
|
||||
error TEXT
|
||||
);
|
||||
```
|
||||
|
||||
### Admin Controls
|
||||
|
||||
**Global config keys:**
|
||||
- `tasks.enabled` — master kill switch (default: true)
|
||||
- `tasks.allow_personal` — whether non-admin users can create personal
|
||||
tasks (default: false). Same pattern as `personas.allow_personal`.
|
||||
- `tasks.max_concurrent` — max simultaneous task executions (default: 5)
|
||||
- `tasks.default_budget.max_tokens` — default ceiling (overridable per task)
|
||||
- `tasks.default_budget.max_tool_calls` — default ceiling
|
||||
- `tasks.default_budget.max_wall_clock` — default ceiling (seconds)
|
||||
|
||||
**Admin panel — Tasks section:**
|
||||
- List all tasks (filterable by owner, team, scope, status)
|
||||
- View task run history with budget usage
|
||||
- Pause/resume individual tasks
|
||||
- Kill running executions
|
||||
- Edit default budgets
|
||||
- Toggle `tasks.allow_personal`
|
||||
|
||||
**Permission integration:**
|
||||
- New permission: `tasks.create` — required to create tasks
|
||||
- New permission: `tasks.admin` — required to manage others' tasks
|
||||
- `Everyone` group gets `tasks.create` if `tasks.allow_personal` is true
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Execution budget enforcement (tokens, tool calls, wall clock)
|
||||
- [ ] `task_runs` table + store
|
||||
- [ ] Budget breach notification to task owner
|
||||
- [ ] Global config keys for task admin controls
|
||||
- [ ] Admin panel Tasks section (CRUD, history, kill switch)
|
||||
- [ ] `tasks.create` and `tasks.admin` permissions
|
||||
- [ ] `tasks.allow_personal` toggle (mirrors `personas.allow_personal`)
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v0.27.3 — Task Chaining: Webhooks + Workflow-to-Workflow
|
||||
|
||||
### Completion Webhooks
|
||||
|
||||
When a task (or workflow) completes, optionally POST to an external URL:
|
||||
|
||||
```go
|
||||
type WebhookPayload struct {
|
||||
TaskID string `json:"task_id"`
|
||||
TaskName string `json:"task_name"`
|
||||
Status string `json:"status"`
|
||||
ChannelID string `json:"channel_id"`
|
||||
CompletedAt time.Time `json:"completed_at"`
|
||||
Output string `json:"output"` // last assistant message
|
||||
StageData any `json:"stage_data"` // workflow stage data (if applicable)
|
||||
}
|
||||
```
|
||||
|
||||
- Webhook URL on task or workflow (`webhook_url` column)
|
||||
- Retry: 3 attempts with exponential backoff (1s, 5s, 25s)
|
||||
- Timeout: 10s per attempt
|
||||
- HMAC signature header (`X-Switchboard-Signature`) using a per-task secret
|
||||
|
||||
### `task_create` Tool
|
||||
|
||||
AI-invocable tool that spawns sub-tasks:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "task_create",
|
||||
"description": "Create a new scheduled or one-shot task",
|
||||
"parameters": {
|
||||
"name": "string",
|
||||
"prompt": "string",
|
||||
"schedule": "string (cron or 'once')",
|
||||
"persona": "string (handle, optional)",
|
||||
"max_tokens": "integer (optional)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `RequireWorkflow` or `RequireTeam` predicate (not available in
|
||||
personal chats — prevents runaway task creation)
|
||||
- One-shot tasks: `schedule = 'once'`, `next_run_at = now()`
|
||||
- Created tasks inherit the parent's scope (team/global)
|
||||
- Depth limit: tasks cannot create tasks (no recursive spawning)
|
||||
|
||||
### Workflow-to-Workflow Chaining
|
||||
|
||||
Wires the `on_complete` column (v0.26.1) into the task system:
|
||||
|
||||
- On workflow completion with `on_complete` set: create a one-shot task
|
||||
that instantiates the target workflow with mapped data
|
||||
- Data mapping: `data_map` keys in `on_complete` JSONB map source
|
||||
`stage_data` fields to target workflow's initial `stage_data`
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Webhook delivery with retry + HMAC signature
|
||||
- [ ] `task_create` tool with depth limit
|
||||
- [ ] `on_complete` chaining via task system
|
||||
- [ ] Webhook secret generation per task/workflow
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v0.27.4 — Personal Tasks: BYOK Scheduling + User Task UI
|
||||
|
||||
The user-facing task experience. Users create personal tasks that run
|
||||
against their BYOK providers.
|
||||
|
||||
### Use Cases
|
||||
|
||||
- **Morning news digest:** Daily at 6am, prompt "Summarize top tech news",
|
||||
output to a personal service channel. Persona: "News Analyst" with
|
||||
`web_search` tool grant.
|
||||
- **Stock screener:** Weekdays at market open, prompt "Check my watchlist
|
||||
for unusual pre-market activity", BYOK OpenAI key for cost control.
|
||||
- **Weekly project summary:** Friday at 5pm, prompt "Summarize this
|
||||
week's activity across my projects", uses `conversation_search` +
|
||||
`workspace_search` tools.
|
||||
- **Daily standup prep:** Weekday mornings, reviews yesterday's notes
|
||||
and generates standup talking points.
|
||||
|
||||
### Settings Surface — Tasks Section
|
||||
|
||||
New section in user settings (same pattern as BYOK, Personas):
|
||||
|
||||
- Task list: name, schedule (human-readable), last run status, next run
|
||||
- Create task: name, persona picker, model picker, prompt editor,
|
||||
schedule builder (preset crons + custom), budget overrides
|
||||
- Task detail: run history, output channel link, edit, pause/delete
|
||||
- BYOK indicator: shows which provider the task will use
|
||||
|
||||
### Schedule Builder
|
||||
|
||||
Preset schedules + custom cron for power users:
|
||||
|
||||
| Preset | Cron |
|
||||
|--------|------|
|
||||
| Every morning (6am) | `0 6 * * *` |
|
||||
| Weekday mornings (8am) | `0 8 * * 1-5` |
|
||||
| Every hour | `0 * * * *` |
|
||||
| Weekly (Monday 9am) | `0 9 * * 1` |
|
||||
| Monthly (1st at midnight) | `0 0 1 * *` |
|
||||
| Custom... | user-entered 5-field cron |
|
||||
|
||||
Timezone selector defaults to browser timezone.
|
||||
|
||||
### BYOK Task Routing
|
||||
|
||||
Personal tasks prefer the user's BYOK provider:
|
||||
|
||||
1. If task has explicit `provider_config_id` → use it
|
||||
2. If user has a BYOK provider config for the task's model → use BYOK
|
||||
3. Fall through to team/global provider (if allowed by admin)
|
||||
|
||||
Admin can restrict personal tasks to BYOK-only via
|
||||
`tasks.personal_require_byok` config key (default: false). When true,
|
||||
personal tasks without a BYOK provider fail with a clear error instead
|
||||
of falling through to org providers.
|
||||
|
||||
### Output Modes
|
||||
|
||||
Three output destinations:
|
||||
|
||||
1. **Channel** (default): Output goes to a persistent service channel.
|
||||
User views it like a read-only chat. Channel accumulates run outputs
|
||||
over time (scrollable history).
|
||||
2. **Note**: Output saved as a channel-scoped note (good for structured
|
||||
data, reports). Note title includes timestamp.
|
||||
3. **Webhook**: Output POSTed to external URL (for integration with
|
||||
other tools — Slack, email, etc.).
|
||||
|
||||
### Task Sidebar Section
|
||||
|
||||
New sidebar section (below Channels, above Chats):
|
||||
|
||||
```
|
||||
▾ Tasks (collapsible)
|
||||
◷ Morning News Digest ✓ 6:02am
|
||||
◷ Stock Screener ✓ 9:30am
|
||||
◷ Weekly Summary ⏳ Fri 5pm
|
||||
+ New task
|
||||
```
|
||||
|
||||
Click opens the task's output channel. Status indicators: ✓ (last run
|
||||
succeeded), ✗ (failed), ⏳ (next run time), ▶ (running now).
|
||||
|
||||
**Deliverables:**
|
||||
- [ ] Settings → Tasks section (CRUD, schedule builder, budget config)
|
||||
- [ ] BYOK provider routing for personal tasks
|
||||
- [ ] `tasks.personal_require_byok` config key
|
||||
- [ ] Output modes: channel, note, webhook
|
||||
- [ ] Tasks sidebar section with status indicators
|
||||
- [ ] "Run Now" button for manual trigger
|
||||
- [ ] Task output channel read-only view
|
||||
|
||||
|
||||
---
|
||||
|
||||
## v0.28.0 — Platform Polish (TBD Pull-Forward)
|
||||
|
||||
Candidates pulled from the TBD section, prioritized by value and
|
||||
dependency readiness.
|
||||
|
||||
### Tier 1 — High value, dependencies met
|
||||
|
||||
**Virtual scroll for long conversations**
|
||||
Conversations with 500+ messages bog down the DOM. Virtual scroll renders
|
||||
only visible messages + buffer zone. Prerequisite for heavy task output
|
||||
channels.
|
||||
|
||||
**KB auto-injection (context-aware)**
|
||||
Top-K chunk prepend to system prompt, context budget aware, per-channel
|
||||
toggle. Useful for tasks that need domain knowledge without explicit
|
||||
`kb_search` tool calls. Latency budgeting required (embedding lookup
|
||||
adds ~200ms).
|
||||
|
||||
**Helm chart**
|
||||
Raw k8s manifests with `${VAR}` substitution → proper Helm chart.
|
||||
`values.yaml` for replicas, image tags, ingress, storage, secrets,
|
||||
feature flags. Subchart for dev/test Postgres. Target: `helm install
|
||||
switchboard ./chart`. Now makes sense because the feature set is
|
||||
stabilizing post-tasks.
|
||||
|
||||
**Per-provider model preferences**
|
||||
`user_model_settings` unique key is `(user_id, model_id)` — same model
|
||||
from different providers shares one visibility toggle. Needs
|
||||
`provider_config_id` dimension in DB constraint, store, API, and
|
||||
frontend `hiddenModels` keying. Natural fit now that BYOK tasks need
|
||||
per-provider model selection.
|
||||
|
||||
### Tier 2 — Medium value, some design work needed
|
||||
|
||||
**Memory compaction**
|
||||
Summarize old memories to save context tokens. Confidence decay: reduce
|
||||
confidence over time, prune low-confidence entries. Natural extension of
|
||||
the memory system (v0.18.0).
|
||||
|
||||
**`capability_match` routing policy**
|
||||
"Cheapest model with tool_calling" — a new routing policy type. Useful
|
||||
for tasks that need tool use but don't need the strongest model.
|
||||
|
||||
**New provider types via config file**
|
||||
OpenAI-compatible endpoints registrable via YAML config (no Go code).
|
||||
Enables users to point at local LLMs (Ollama, vLLM, llama.cpp) without
|
||||
a provider code change.
|
||||
|
||||
### Tier 3 — Future (v0.29+)
|
||||
|
||||
- Desktop app (Tauri) — large scope, independent track
|
||||
- Full PWA with offline — needs service worker rewrite
|
||||
- Plugin/extension marketplace — needs extension surface routes first (v0.27.0)
|
||||
- Starlark/sidecar extension tiers — needs extension surface routes first
|
||||
- Git credentials vault store — needs vault extension design
|
||||
- Cross-persona memory sharing — needs memory system redesign
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Design Decision: Task Permission Model
|
||||
|
||||
Tasks introduce a new resource type that intersects with multiple
|
||||
existing permission boundaries:
|
||||
|
||||
| Scope | Who can create | Provider used | Visibility |
|
||||
|-------|---------------|---------------|------------|
|
||||
| Personal | User (if `tasks.allow_personal`) | User's BYOK or team fallback | Owner only |
|
||||
| Team | User with `tasks.create` + team membership | Team provider | Team members |
|
||||
| Global | Admin | Global provider | All users (read) |
|
||||
|
||||
Personal tasks are the BYOK sweet spot. The admin toggle
|
||||
(`tasks.allow_personal`) mirrors the existing `personas.allow_personal`
|
||||
pattern — a single boolean in global config, surfaced in the admin
|
||||
settings panel.
|
||||
|
||||
**Why not just a permission?** The `tasks.create` permission already
|
||||
gates the ability. `tasks.allow_personal` is a _policy_ control —
|
||||
admins might allow task creation for team tasks but prohibit personal
|
||||
tasks to prevent uncontrolled BYOK spending. Two orthogonal knobs.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Design Decision: Task vs. Workflow Relationship
|
||||
|
||||
Tasks and workflows are related but distinct:
|
||||
|
||||
| | Task | Workflow |
|
||||
|---|------|---------|
|
||||
| Trigger | Cron schedule or `task_create` tool | Human click or task trigger |
|
||||
| Participants | Zero humans (service channel) | Humans + AI |
|
||||
| Complexity | Single prompt or workflow instantiation | Multi-stage, assignment queue |
|
||||
| Output | Channel, note, or webhook | Channel (interactive) |
|
||||
| Lifecycle | Recurring (cron) or one-shot | Single instance |
|
||||
|
||||
A **prompt task** is simpler than a workflow — it's a scheduled
|
||||
completion. A **workflow task** is a task that instantiates a workflow.
|
||||
This keeps the task system lean (scheduling + budgets + output routing)
|
||||
and the workflow engine rich (stages + assignment + personas).
|
||||
|
||||
The `task_type` column makes this explicit. Prompt tasks don't need
|
||||
workflows at all — they're a direct scheduler → completion path.
|
||||
Workflow tasks reuse the full workflow engine.
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Resolved Decisions
|
||||
|
||||
1. **Task output retention.** Use channel-level retention from v0.26.0.
|
||||
No per-task retention policy needed — the channel's `retention` JSONB
|
||||
handles archive/delete semantics. Notes created by task output survive
|
||||
channel removal (notes are channel-scoped but not cascade-deleted).
|
||||
Storage quotas per user are a future concern (v0.29+ candidate) — not
|
||||
blocking for initial task support.
|
||||
|
||||
2. **Concurrent task execution.** Skip with a warning log. If
|
||||
`task_runs` has a row with `status = 'running'` for the task, the
|
||||
scheduler skips that tick. Log: `[scheduler] Skipping task %s — previous
|
||||
run still active`. No queue — if a task consistently overruns its
|
||||
schedule, the user needs to adjust the cron interval or budget.
|
||||
|
||||
3. **Task templates.** Ship 3–5 optional starter templates in v0.27.4.
|
||||
Presented as suggestions during task creation ("Start from a
|
||||
template..." option alongside blank task). Not auto-created — user
|
||||
must explicitly choose one. Templates are just pre-filled form values,
|
||||
not persistent DB records.
|
||||
|
||||
4. **Task notifications.** Opt-in per task. Two booleans on the `tasks`
|
||||
table: `notify_on_complete` (default false), `notify_on_failure`
|
||||
(default true). Uses existing notification infrastructure (v0.20.0
|
||||
bell + WebSocket push).
|
||||
Reference in New Issue
Block a user