The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* Kanban data layer. Everything goes through `ctx.rest` — the plugin's own
* `/api/plugins/kanban/*` FastAPI router (`plugins/kanban/dashboard/plugin_api.py`),
* reused as-is via the desktop's namespace-scoped REST door. No new backend.
*
* Fetching, caching, polling, dedupe, and invalidation are React Query's job
* (the app's standard, via the SDK). This module owns the query keys, the REST
* calls, and the selected-board atom — every call passes `?board=<slug>` so the
* desktop's selection never flips the server-wide current-board pointer.
*
* Every query key and the persisted board selection are scoped by the ACTIVE
* CONNECTION (`host.state.connectionId`): a board lives on ONE gateway, so a
* connection switch must be a clean cache miss (the hermes-bots roster
* pattern), and each gateway remembers its own selected board instead of
* pinning a slug the next gateway 404s on.
*/
import {
atom,
captureGatewayFileDownload,
host,
type PluginOs,
type PluginRestOptions,
type PluginStorage,
type PluginTranslate,
queryClient,
useValue
} from '@hermes/plugin-sdk'
// Native completion notification.
import { bindCompletionNotify, type CompletionEvent, onKanbanEventsFrame } from './completion-notify'
import type {
BoardExportResult,
BoardImportResult,
BoardMeta,
BoardsResponse,
KanbanBoard,
KanbanProfile,
KanbanProject,
KanbanTask,
KanbanTaskDetail,
OrchestrationSettings,
TaskEstimate,
WorkerLog
} from './types'
type Rest = <T>(path: string, opts?: PluginRestOptions) => Promise<T>
type Socket = (path: string, onMessage: (data: unknown) => void) => () => void
let rest: null | Rest = null
let os: null | PluginOs = null
/** Selected board slug ('' = the server's current board). Persisted. */
export const $boardSlug = atom<string>('')
/** Whether the "how this board works" intro was dismissed. Persisted. */
export const $introDismissed = atom<boolean>(false)
/** Sub-group the Running lane by assignee (the dashboard's "lanes by
* profile"). Persisted. */
export const $lanesByProfile = atom<boolean>(false)
/** Per-lane collapse OVERRIDES (true=collapsed, false=expanded). Absence means
* auto: empty lanes collapse to a rail, occupied lanes expand. Persisted. */
export const $collapsedLanes = atom<Record<string, boolean>>({})
/** Cache scope of the local pool — the SDK atom's own spelling. */
const LOCAL_SCOPE = 'local'
const KANBAN_KEY_ROOT = ['kanban'] as const
const BOARD_SLUG_KEY = 'boardSlug'
const INTRO_KEY = 'introDismissed'
const LANES_KEY = 'lanesByProfile'
const COLLAPSED_KEY = 'collapsedLanes'
// Last frame cursor per (connection, board) this plugin bind. The socket
// reopens on every board switch and connection change; resuming from the last
// frame replays only what was missed. Keyed by connection so one gateway's
// cursor cannot resume another's stream. Cleared on bind/unbind — events that
// land while the plugin is unloaded are not replayed.
const eventCursorByBoard = new Map<string, number>()
function cursorKey(scope: string, slug: string): string {
return `${scope}\0${slug}`
}
function snapshotCursor(scope: string, slug: string): number | undefined {
for (const archived of [false, true]) {
const board = queryClient.getQueryData<KanbanBoard>(boardKey(scope, slug, archived))
if (typeof board?.latest_event_id === 'number') {
return board.latest_event_id
}
}
return undefined
}
/** Cursor a fresh socket starts from: the last frame this connection saw, else
* the cached board snapshot's tail. Undefined means nothing is known yet —
* fetch the snapshot before opening, never open at since=0. */
function eventsSince(scope: string, slug: string): number | undefined {
const seen = eventCursorByBoard.get(cursorKey(scope, slug))
if (typeof seen === 'number') {
return seen
}
return snapshotCursor(scope, slug)
}
function eventsUrl(slug: string, since: number | undefined): string {
const params = new URLSearchParams()
if (slug) {
params.set('board', slug)
}
if (since !== undefined) {
params.set('since', String(since))
}
const query = params.toString()
return query ? `/events?${query}` : '/events'
}
function boardSnapshotPath(slug: string): string {
return slug ? `/board?board=${encodeURIComponent(slug)}` : '/board'
}
/** Cache-scope id for the active connection — the segment every query key
* embeds. `'local'` covers the pre-descriptor null; the SDK atom already
* reports 'local' for the local pool. For NON-rendering code (mutations,
* socket frames); rendering components use `useKanbanScope` so the keys they
* build during render recompute when the connection changes. */
export function kanbanConnectionScope(): string {
return host.state.connectionId.get() ?? LOCAL_SCOPE
}
export function useKanbanScope(): string {
return useValue(host.state.connectionId) ?? LOCAL_SCOPE
}
/** Where a request issued NOW is routed, as a cache scope. The request tag
* moves before the connection descriptor publishes, and React re-keys the
* observers later still — so between the two an observer can sit on the
* outgoing scope's key while a fetch would land on the incoming backend. */
const routedScope = (): string => host.activeConnectionId() ?? LOCAL_SCOPE
/** `enabled` for every kanban query: only fetch while the key's scope is the
* routed one. A switch's app-wide invalidation then leaves the outgoing
* observers alone (the incoming keys are already a cache miss) instead of
* writing the new gateway's payload under the old connection's key — which
* would paint on the way back. Installed as the `['kanban']` query default in
* `bindApi`; sites with their own `enabled` compose it. */
export const routedToScope = (query: { queryKey: readonly unknown[] }): boolean => query.queryKey[2] === routedScope()
/** One live `task_events` frame → precise cache invalidation: the board, plus
* each touched task's detail. The polls (8s board / 4s drawer) stay as the
* fallback — the socket just makes the board feel instant. */
function onEventsFrame(scope: string, slug: string, data: unknown, selectedSlug = slug): void {
const frame = data as { cursor?: unknown; events?: CompletionEvent[] }
if (typeof frame?.cursor === 'number') {
eventCursorByBoard.set(cursorKey(scope, slug), frame.cursor)
}
const events = frame?.events
if (!events?.length) {
return
}
void queryClient.invalidateQueries({ queryKey: boardKeyPrefix(scope) })
// Any event can change a board's card count — keep the switcher badge honest.
void queryClient.invalidateQueries({ queryKey: boardsKey(scope) })
for (const taskId of new Set(events.map(event => event.task_id).filter(Boolean))) {
void queryClient.invalidateQueries({ queryKey: taskKey(scope, slug, taskId!) })
if (selectedSlug !== slug) {
void queryClient.invalidateQueries({ queryKey: taskKey(scope, selectedSlug, taskId!) })
}
}
// Completion notification (after invalidation so notify failure
// never interferes with cache invalidation).
void onKanbanEventsFrame(slug, events).catch(() => undefined)
}
// A persisted, subscribable atom (the structural slice we need — avoids
// importing nanostore's type just to describe one).
interface Persisted<T> {
get(): T
set(value: T): void
listen(cb: (value: T) => void): () => void
}
/** Bind the plugin's doors at register time and return a disposer the host
* runs on unload/disable — so nothing (store sync, socket) survives a toggle
* or duplicates on re-enable. The events socket is pinned to a board at
* handshake, so a board switch closes + reopens it. */
export function bindApi(
r: Rest,
storage: PluginStorage,
socket: Socket,
notifyDoors?: { os?: PluginOs; t?: PluginTranslate }
): () => void {
rest = r
os = notifyDoors?.os ?? null
bindCompletionNotify(r, notifyDoors?.t, notifyDoors?.os)
const unsubs: Array<() => void> = []
queryClient.setQueryDefaults(KANBAN_KEY_ROOT, { enabled: routedToScope })
unsubs.push(() => queryClient.setQueryDefaults(KANBAN_KEY_ROOT, {}))
// Hydrate an atom from storage and keep storage in sync with it.
const persist = <T>(atom: Persisted<T>, key: string, fallback: T) => {
atom.set(storage.get(key, fallback))
unsubs.push(atom.listen(value => storage.set(key, value)))
}
persist($introDismissed, INTRO_KEY, false)
persist($lanesByProfile, LANES_KEY, false)
persist($collapsedLanes, COLLAPSED_KEY, {})
eventCursorByBoard.clear()
let close: (() => void) | null = null
let socketGeneration = 0
const dial = (scope: string, slug: string, since: number | undefined) => {
const generation = socketGeneration
const selectedSlug = $boardSlug.get()
return socket(eventsUrl(slug, since), data => {
if (generation === socketGeneration) {
onEventsFrame(scope, slug, data, selectedSlug)
}
})
}
const open = (selectedSlug: string) => {
const generation = ++socketGeneration
const scope = kanbanConnectionScope()
close?.()
close = null
const openResolved = (slug: string) => {
if (generation !== socketGeneration) {
return
}
const since = eventsSince(scope, slug)
if (since !== undefined) {
close = dial(scope, slug, since)
return
}
// No cached tail yet. Wait for the snapshot and open at its
// latest_event_id. A board switch or unload bumps the generation so a
// late snapshot cannot open a stale socket. A failed fetch still opens
// with no since — the server starts at the tail rather than replaying.
void queryClient
.fetchQuery({
queryFn: () => r<KanbanBoard>(boardSnapshotPath(slug)),
queryKey: boardKey(scope, slug, false)
})
.then(board => {
if (generation !== socketGeneration) {
return
}
const tail = typeof board?.latest_event_id === 'number' ? board.latest_event_id : undefined
close = dial(scope, slug, tail)
})
.catch(() => {
if (generation !== socketGeneration) {
return
}
close = dial(scope, slug, undefined)
})
}
if (selectedSlug) {
openResolved(selectedSlug)
return
}
// Resolve the alias BEFORE the handshake: /events is pinned to its board
// when opened. Resolving on each frame could classify an old socket's
// events against a different server-current board's cursor.
void r<BoardsResponse>('/boards')
.then(boards => openResolved(typeof boards.current === 'string' ? boards.current : ''))
.catch(() => openResolved('')) // Keep live cache invalidation; notifications fail closed.
}
// The local connection keeps the BARE key (the bare-local rule of
// lib/connection-scoped: byte-identical storage for single-backend users, and
// the slug picked before per-connection keys existed survives the upgrade).
// Remotes are suffixed by registry id.
const slugStorageKey = () => {
const scope = kanbanConnectionScope()
return scope === LOCAL_SCOPE ? BOARD_SLUG_KEY : `${BOARD_SLUG_KEY}.${scope}`
}
$boardSlug.set(storage.get(slugStorageKey(), ''))
unsubs.push($boardSlug.listen(slug => storage.set(slugStorageKey(), slug)))
open($boardSlug.get())
unsubs.push($boardSlug.listen(open))
unsubs.push(
host.state.connectionId.listen((next, prev) => {
// Query keys embed the scope, so the new connection is already a cache
// miss; only the LIVE bindings (socket, slug) follow it. The boot-time
// null → 'local' publish is the same scope, not a switch. A changed slug
// reopens the socket through the $boardSlug listener above; an unchanged
// slug still needs a dial because the backend behind it changed.
if ((next ?? LOCAL_SCOPE) === (prev ?? LOCAL_SCOPE)) {
return
}
const previous = $boardSlug.get()
$boardSlug.set(storage.get(slugStorageKey(), ''))
if ($boardSlug.get() === previous) {
open(previous)
}
})
)
return () => {
socketGeneration += 1
eventCursorByBoard.clear()
unsubs.forEach(unsub => unsub())
close?.()
rest = null
os = null
}
}
/** The plugin's OS door, for components too deep to be handed `ctx`. Null
* before `bindApi` and after unload. */
export const pluginOs = (): null | PluginOs => os
function call<T>(path: string, opts?: PluginRestOptions): Promise<T> {
return rest ? rest<T>(path, opts) : Promise.reject(new Error('kanban api not ready'))
}
/** Append the selected board (and other params) to a path. */
function withBoard(path: string, params: Record<string, string> = {}): string {
const search = new URLSearchParams(params)
const slug = $boardSlug.get()
if (slug) {
search.set('board', slug)
}
const qs = search.toString()
return qs ? `${path}?${qs}` : path
}
// ── query keys (connection- and board-scoped; scope is always segment [2]) ────
/** Prefix matching every board query on one connection (all slugs, both
* archived views) — the mutation-settled invalidation target. */
export const boardKeyPrefix = (scope: string) => ['kanban', 'board', scope] as const
export const boardKey = (scope: string, slug: string, archived: boolean) =>
[...boardKeyPrefix(scope), slug, archived] as const
export const taskKey = (scope: string, slug: string, id: string) => ['kanban', 'task', scope, slug, id] as const
export const logKey = (scope: string, slug: string, id: string) => ['kanban', 'log', scope, slug, id] as const
export const boardsKey = (scope: string) => ['kanban', 'boards', scope] as const
export const profilesKey = (scope: string) => ['kanban', 'profiles', scope] as const
export const projectsKey = (scope: string) => ['kanban', 'projects', scope] as const
export const orchestrationKey = (scope: string) => ['kanban', 'orchestration', scope] as const
// ── reads ─────────────────────────────────────────────────────────────────────
export const fetchBoard = (archived: boolean) =>
call<KanbanBoard>(withBoard('/board', archived ? { include_archived: 'true' } : {}))
export const fetchTask = async (id: string) => {
const downloadAttachment = captureGatewayFileDownload()
const detail = await call<KanbanTaskDetail>(withBoard(`/tasks/${id}`))
return { ...detail, downloadAttachment }
}
/** Worker stdout/stderr tail (last 16 KiB — plenty for the drawer). */
export const fetchLog = (id: string) => call<WorkerLog>(withBoard(`/tasks/${id}/log`, { tail: '16384' }))
export const fetchBoards = () => call<BoardsResponse>('/boards')
export const fetchProfiles = () => call<{ profiles: KanbanProfile[] }>('/profiles')
/** First-class Hermes projects, for scoping a board's default workspace. */
export const fetchProjects = () => call<{ projects: KanbanProject[] }>('/projects')
export const fetchOrchestration = () => call<OrchestrationSettings>('/orchestration')
// ── writes ────────────────────────────────────────────────────────────────────
// Every board edit nudges the dispatcher (debounced, fire-and-forget) so the
// change takes effect NOW instead of on the next 60s tick — create a ready
// task and the worker spawns immediately, no manual "nudge" ritual. The tick
// is lock-guarded and ~1ms when there's nothing to do, so over-nudging is
// free; failures are non-events (the periodic tick still exists).
let nudgeTimer: null | ReturnType<typeof setTimeout> = null
function autoNudge(): void {
if (nudgeTimer != null) {
clearTimeout(nudgeTimer)
}
nudgeTimer = setTimeout(() => {
nudgeTimer = null
nudgeDispatcher().catch(() => undefined)
}, 400)
}
/** Resolve the write, then kick the dispatcher. Rejections pass through. */
function nudged<T>(write: Promise<T>): Promise<T> {
return write.then(value => {
autoNudge()
return value
})
}
export const patchTask = (id: string, patch: Record<string, unknown>) =>
nudged(call(withBoard(`/tasks/${id}`), { method: 'PATCH', body: patch }))
export const createTask = (body: Record<string, unknown>) =>
nudged(call<{ task: KanbanTask | null; warning?: string }>(withBoard('/tasks'), { method: 'POST', body }))
// Deleting can unblock dependants (a gone parent no longer gates), so it
// nudges too.
export const deleteTask = (id: string) => nudged(call(withBoard(`/tasks/${id}`), { method: 'DELETE' }))
/** One patch, many ids — independent per-id application; returns per-id
* outcomes so the UI can toast partial failures. */
export const bulkTasks = (ids: string[], patch: Record<string, unknown>) =>
nudged(
call<{ results: Array<{ id: string; ok: boolean; error?: string }> }>(withBoard('/tasks/bulk'), {
method: 'POST',
body: { ids, ...patch }
})
)
export const addComment = (id: string, body: string) =>
call(withBoard(`/tasks/${id}/comments`), { method: 'POST', body: { author: 'desktop', body } })
export const reassignTask = (id: string, profile: string) =>
nudged(call(withBoard(`/tasks/${id}/reassign`), { method: 'POST', body: { profile, reclaim_first: true } }))
export const reclaimTask = (id: string) => nudged(call(withBoard(`/tasks/${id}/reclaim`), { method: 'POST', body: {} }))
export const uploadAttachment = (id: string, upload: { filename: string; contentType?: string; bytes: ArrayBuffer }) =>
call(withBoard(`/tasks/${id}/attachments`), { method: 'POST', upload })
export const createBoard = (slug: string, name: string, projectId?: string) =>
call<{ board: { slug: string } }>('/boards', {
method: 'POST',
body: { slug, name, ...(projectId ? { project_id: projectId } : {}) }
})
/** Rough auxiliary-model estimate for a task (tokens + complexity). Makes a
* model call — gate behind an explicit user action + disclaimer. */
export const estimateTask = (id: string) =>
call<TaskEstimate>(withBoard(`/tasks/${id}/estimate`), { method: 'POST', body: {} })
/** Estimate from typed title/body before a task exists (create dialog). */
export const estimateNew = (title: string, body: string) =>
call<TaskEstimate>('/estimate', { method: 'POST', body: { title, body: body || undefined } })
/** Edit a board's display metadata + default project directory. Pass
* `default_workdir: ''` to clear it. Slug is immutable. */
export const updateBoard = (slug: string, patch: Record<string, unknown>) =>
call<{ board: BoardMeta }>(`/boards/${encodeURIComponent(slug)}`, { method: 'PATCH', body: patch })
/** Archive a board to `boards/_archived/` — recoverable, and the backend
* refuses to touch `default`. (`?delete=true` hard-deletes; no caller yet.) */
export const deleteBoard = (slug: string) =>
call<{ result: { action: string; new_path: string }; current: string }>(`/boards/${encodeURIComponent(slug)}`, {
method: 'DELETE'
})
// Board transfer exchanges filesystem paths, not bytes — the picker runs on
// the machine hosting the backend, so the backend reads and writes the file.
export const exportBoard = (slug: string, output: string) =>
call<BoardExportResult>(`/boards/${encodeURIComponent(slug)}/export`, { method: 'POST', body: { output } })
export const importBoard = (archive: string) =>
call<BoardImportResult>('/boards/import', { method: 'POST', body: { archive } })
export const nudgeDispatcher = () => call<{ spawned?: unknown[] }>(withBoard('/dispatch'), { method: 'POST', body: {} })
export const saveOrchestration = (patch: Record<string, unknown>) =>
call<OrchestrationSettings>('/orchestration', { method: 'PUT', body: patch })
export const saveProfileDescription = (name: string, description: string) =>
call(`/profiles/${encodeURIComponent(name)}`, { method: 'PATCH', body: { description } })
export const autoDescribeProfile = (name: string) =>
call<{ ok: boolean; reason?: null | string; description?: null | string }>(
`/profiles/${encodeURIComponent(name)}/describe-auto`,
{ method: 'POST', body: { overwrite: true } }
)