adispatchd 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 brokoskokoli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,196 @@
-# Temporary Holding Version
+# Agent Dispatch Daemon (`adispatchd`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Konfigurationsgetriebener Orchestrator für Shell-Prozesse und KI-Agenten. Er findet Aufgaben in externen Quellen
+(V1: GitHub Issues/PRs), wählt sie über Filter und Prioritäten aus, prüft Startbedingungen, führt unabhängige
+Shell-Workflows in eigenen Workspaces aus, überwacht und protokolliert jeden Run, führt Lifecycle-Aktionen aus
+(Labels, Kommentare, Shell-Hooks) und zeigt alles in einer kleinen Weboberfläche mit Live-Updates.
+
+- **GitHub bleibt Source of Truth** – kein eigener Ticketstore; SQLite hält nur Runs, Locks, Events, Blocks, Aktionsjournale.
+- **Unabhängige Workflows** mit Source-, Cron- oder manuellem Trigger, globalen und workflowbezogenen Limits.
+- **Robust:** technische Fehler vs. fachliches `failure`, Retry-Blocks, Aktions-Retries, Cancel/Timeout per
+  Prozessgruppe, Drain, Crash-Recovery, systemd-Integration.
+
+Dokumentation: [Betrieb](docs/operations.md) · [Worker-Protokoll](docs/worker-protocol.md) · [HTTP-API/SSE](docs/api.md) ·
+[Cron-Semantik](docs/cron-semantics.md) · [Spezifikation](docs/spec-v0.1.md) · Manuelle Tests:
+[systemd](docs/manual-tests/systemd.md), [Prozess-Supervision](docs/manual-tests/process-supervision.md),
+[GitHub](docs/manual-tests/github.md)
+
+## Installation
+
+Voraussetzungen: Linux (Produktion, systemd) oder macOS (lokal), **Node.js ≥ 22.13** (empfohlen 24 LTS; SQLite kommt aus
+`node:sqlite`, kein natives Addon). Windows wird nicht unterstützt.
+
+Paket `adispatchd` auf npm, Befehl `adispatch`. Für Dienste immer eine **feste Version** global installieren (kein `npx`):
+
+```bash
+npm install -g adispatchd@0.1.0                 # aus der npm-Registry
+
+# alternativ aus dem Repository-Checkout:
+git clone https://github.com/brokoskokoli/adispatchd.git && cd adispatchd
+npm install
+npm pack                                        # baut (prepack) und erzeugt adispatchd-0.1.0.tgz
+npm install -g ./adispatchd-0.1.0.tgz   # feste Version aus dem Tarball (für Dienste Pflicht)
+# lokal ohne globale Installation: npm run build && node dist/cli/main.js <kommando> …
+```
+
+## Quickstart (lokal)
+
+```bash
+adispatch init --config-dir ./config --data-dir ./data      # legt Beispielkonfiguration + Skripte an
+adispatch start --config-dir ./config --data-dir ./data     # Vordergrund, Ctrl-C = Drain
+```
+
+- Weboberfläche/API: <http://127.0.0.1:8787/> (`/health`, `/ready`, `/api/v1/…`).
+- Workflow **hello** (manuell, ohne GitHub) starten – in der UI unter *Workflows* oder:
+  ```bash
+  curl -X POST -H 'X-Adispatch-Request: 1' -H 'Content-Type: application/json' \
+       -d '{"parameters":{"name":"Ada"}}' http://127.0.0.1:8787/api/v1/workflows/hello/start
+  ```
+  Logs liegen unter `data/logs/<run-id>/`, Kontext/Ergebnis unter `data/runs/<run-id>/`.
+- Steuerung: `adispatch status|pause|resume|drain|cancel-all --config-dir ./config`.
+- GitHub anbinden: GitHub App je Rolle anlegen (Rechte: Issues r/w, Pull requests write, Metadata read), App-/Installation-ID in
+  `identities.yaml`, Repo in `sources.yaml`, Private Key als Umgebungsvariable (`export GITHUB_CODER_PRIVATE_KEY="$(cat key.pem)"`),
+  dann in `workflows/coder.yaml` `enabled: true` setzen und `adispatch config reload --config-dir ./config`.
+
+`init` überschreibt nie bestehende Dateien (vorhandene werden als „kept“ gemeldet) und validiert danach die Konfiguration.
+
+## CLI
+
+| Kommando | Zweck |
+|---|---|
+| `init --config-dir D --data-dir D [--port P]` | Verzeichnisstruktur + kommentierte Beispielkonfiguration anlegen |
+| `start --config-dir D --data-dir D [--drain-timeout 10m] [--cancel-timeout 2m] [--host H] [--port P]` | Orchestrator im Vordergrund; SIGTERM/SIGINT = Drain, danach Cancel-All; 2. Signal = sofort Cancel-All; Exit 0 nach geordnetem Stop |
+| `status`, `pause`, `resume` | Zustand / automatische Starts pausieren und fortsetzen |
+| `drain [--wait] [--timeout T]` | keine neuen Runs, aktive zu Ende, dann Stop |
+| `cancel-all [--reason R] [--wait]` | alle Runs abbrechen (`on_cancel`), dann Stop |
+| `config validate --config-dir D` | Offline-Validierung (Syntax, Schema, Referenzen, Platzhalter) mit Datei:Zeile |
+| `config reload` | laufende Instanz lädt die Konfiguration atomar neu (ungültig → alte bleibt aktiv) |
+| `workflow dry-run <id> [--json] [--local]` | Kandidatenauswahl ohne Start/Actions/Shell-Prüfungen; gegen die laufende Instanz, sonst lokal |
+| `service install\|status\|uninstall [--dry-run]` | systemd-Dienst (Linux), siehe [Betrieb](docs/operations.md#installation-als-systemd-dienst-linux) |
+
+HTTP-Kommandos finden die Instanz über `--url` oder Host/Port aus `config.yaml` von `--config-dir` (Default
+`http://127.0.0.1:8787`). Exit-Codes: 0 ok, 1 Fehler, 2 Aufruffehler, 3 Instanz nicht erreichbar, 4 `--wait`-Timeout.
+
+## Konfiguration
+
+**Verbindliche Referenz aller Dateien, Felder, Defaults, Filter, Platzhalter und des Auswertungsablaufs:
+[docs/configuration-reference.md](docs/configuration-reference.md)** (ersetzt die Formatvorschläge der Spec; die
+Beispiele darin werden per Test gegen den echten Loader geprüft).
+
+```
+config-dir/                      data-dir/
+  config.yaml   global (§5.1)      adispatchd.sqlite   Runs, Locks, Events, Blocks, Journale
+  sources.yaml  GitHub-Repos       adispatchd.lock     Instanzsperre (nie anfassen)
+  identities.yaml GitHub Apps      logs/<run>/stdout.log, stderr.log
+  workflows/*.yaml                 runs/<run>/context.json, result.json
+  views/*.yaml                     workspaces/<workflow>/<run>/
+  scripts/*.sh                     backups/   DB-Backups vor Migrationen
+```
+
+Ein Workflow (vollständiges Beispiel: `workflows/coder.yaml` nach `init`, Referenz: [Konfigurationsreferenz](docs/configuration-reference.md)):
+
+```yaml
+id: coder
+priority: 50                         # Workflow-Priorität vor Item-Priorität
+max_concurrent: 2
+identity: coder                      # GitHub-App für Labels/Kommentare
+trigger: { type: source, source: project_a }   # oder { type: schedule, cron: '0 3 * * *' } / { type: manual }
+filter:
+  all:
+    - { field: labels, operator: contains, value: ready-for-coding }
+    - { field: dependencies.blocked_by_open, operator: equals, value: 0 }
+conditions:
+  workflow: [ { type: shell, command: scripts/check-credits.sh, cache: 60s } ]
+execute:
+  type: shell
+  command: scripts/coder.sh          # relativ zum config-dir; ohne Shell, Argumente als Liste
+  secrets: { GH_TOKEN: { identity: coder } }
+  timeout: { max_duration: 6h, idle_timeout: 45m }
+retry: { max_technical_failures: 3 }
+on_start:   [ { type: source.update, labels: { add: [coding], remove: [ready-for-coding] } } ]
+on_success: [ { type: source.comment, message: 'Completed: {result.message}' } ]
+on_failure: [ { type: source.update, labels: { add: [needs-maintainer], remove: [coding] } } ]
+on_crash:   [ { type: source.update, labels: { add: [ready-for-coding], remove: [coding] } } ]
+```
+
+- Hooks: `on_start`, `on_success`, `on_failure`, `on_crash`, `on_start_error`, `on_timeout`, `on_cancel`; Actions
+  `source.update`, `source.comment`, `shell`; Retry 3 × 30 s (`lifecycle.action_retry`), `continue_on_error`.
+- Platzhalter (feste Liste): `{run.id}`, `{workflow.id}`, `{item.number}`, `{item.url}`, `{result.message}`,
+  `{parameters.<name>}`, `{workspace.base_dir}` … – unbekannte Platzhalter sind Konfigurationsfehler.
+- Manuelle Starts (UI/API) umgehen Filter, Conditions, Limits und Retry-Blocks, nie aber den aktiven Lock pro Workflow+Item.
+- Views (`views/*.yaml`) sind read-only Tabellen über mehrere Sources inkl. `run.last_*`-Feldern.
+- Änderungen gelten erst nach `config reload` (oder UI „Reload“); laufende Runs nutzen ihren Snapshot. Runtime-Overrides aus
+  der UI gehen bei Neustart verloren.
+- Secrets stehen nie in YAML: Private Keys/Webhook-URLs nur über Umgebungsvariablen (`private_key_env`, `url_env`, `headers_env`).
+
+## Worker-Protokoll (Kurzfassung)
+
+Details: [docs/worker-protocol.md](docs/worker-protocol.md).
+
+- **Input:** Minimalumgebung (`PATH`, `HOME`, …) + `execute.env` + deklarierte Secrets + `ADISPATCH_RUN_ID`, `ADISPATCH_WORKFLOW_ID`,
+  `ADISPATCH_SOURCE_*`, `ADISPATCH_WORKSPACE`, `ADISPATCH_CONTEXT_FILE` (JSON-Kontext), `ADISPATCH_RESULT_FILE`. Keine Controller-Umgebung.
+- **Exit-Code = technischer Status:** `0` = ok, alles andere = `crashed` (technischer Fehler, zählt zum Retry-Block).
+- **Fachliches Ergebnis** nur über die Ergebnisdatei (atomar schreiben):
+  `{"schema_version":1,"result":"failure","message":"Requirements unclear"}` + `exit 0` → `on_failure` („Needs Maintainer“),
+  kein technischer Fehler. Ohne Datei gilt Exit 0 als `success`.
+- **Events:** Zeilen `@@ADISPATCH_EVENT {"type":"status","message":"Tests laufen"}` auf stdout/stderr – nur informativ.
+- **Cancel/Timeout:** SIGTERM an die Prozessgruppe, nach `cancel_grace` (30 s) SIGKILL. Eigene Sessions/Container räumt das
+  Skript selbst auf.
+
+## Sicherheit
+
+- **Keine Anmeldung in V1.** Die API bindet standardmäßig nur an `127.0.0.1`. Fernzugriff ausschließlich über einen
+  **authentifizierenden** Reverse Proxy, VPN oder Tailscale; dessen Hostnamen in `server.allowed_hosts` eintragen
+  (DNS-Rebinding-Schutz). Bei Nicht-Loopback-Bind warnt `start`. Anleitung: [Betrieb → Fernzugriff](docs/operations.md#fernzugriff-reverse-proxy-spec-15-201).
+- Mutierende Requests brauchen den Header `X-Adispatch-Request: 1`; es gibt keine CORS-Freigaben.
+- **Skripte und YAML sind vertrauenswürdiger Code** mit den Rechten des Dienstes – keine Sandbox. Schreibrecht auf das
+  config-dir ist gleichbedeutend mit Codeausführung; `service install` legt es `root`-eigen an und lässt den Dienst unter einem
+  eigenen Benutzer laufen.
+- Worker erhalten nur ausdrücklich deklarierte Secrets (z. B. kurzlebiges `GH_TOKEN`); Secrets werden nie in Kontext-/
+  Ergebnisdateien, API-Antworten oder Logs persistiert, Redaction in Prozesslogs ist best-effort. Ein Worker kann ihm
+  übergebene Secrets dennoch ausgeben.
+- GitHub-Apps mit minimalen Rechten; fehlende Rechte bei Cross-Repo-Abhängigkeiten führen zu `unknown` (kein Start), nicht zu „0“.
+- Event-, Result- und Log-Inhalte werden in der UI nur als Text dargestellt.
+
+## Betrieb
+
+Kurzfassung – Details in [docs/operations.md](docs/operations.md):
+
+- **systemd:** `sudo adispatch service install --config-dir /etc/adispatchd --data-dir /var/lib/adispatchd --create-user`
+  (vorher `--dry-run`). Unit mit absolutem Node-/Paketpfad, dediziertem Benutzer, `Restart=on-failure`, `KillMode=mixed`,
+  `TimeoutStopSec` > Drain + Cancel + Grace. Secrets in `/etc/default/adispatchd`.
+- **Geplante Stopps/Updates:** `adispatch drain --wait`, dann die neue Version installieren (`npm install -g adispatchd@<neu>` oder Tarball), starten.
+  Migrationen laufen automatisch mit Backup in `data-dir/backups/`; config-dir und data-dir bleiben erhalten.
+- **Backups:** config-dir (git), Env-Datei, `adispatchd.sqlite` per `sqlite3 … ".backup …"`, `logs/`, `runs/`.
+  `adispatchd.lock*` nie kopieren oder öffnen. data-dir nur auf lokalem Dateisystem (kein NFS).
+- **Recovery:** nach Absturz/Neustart werden verwaiste Runs `crashed` + `on_crash`, nicht sicher identifizierbare Prozesse
+  `recovery_pending` (UI „Retry Recovery“); der Scheduler startet erst danach.
+
+## Entwicklung
+
+```bash
+npm install
+npm run check        # Gate: tsc --noEmit && vitest run (vor jedem Commit)
+npm run test:pack    # npm pack → Installation im Temp-Verzeichnis → init → start → drain → Update (≈ 10–60 s)
+npm run dev -- start --config-dir ./config --data-dir ./data   # ohne Build (tsx)
+npm run build        # nach dist/
+```
+
+```
+src/
+  core/        gemeinsame Typen, Verträge, Hilfsfunktionen
+  config/      YAML-Konfiguration, Schemas, Reload        persistence/ SQLite, Migrationen, Repositories, Instanz-Lock
+  filters/     Filter-AST, Prioritäten, Shell-Checks      executors/   Shell-Executor, Worker-Protokoll, Prozessidentität
+  sources/     GitHub-Adapter                             identities/  GitHub-App-Credentials
+  lifecycle/   Lifecycle-Aktionen, Action-Journal         runs/        Run-Controller, Recovery, Shutdown, Retention
+  scheduler/   Scheduler, Trigger, Dry-Run                views/ notifications/ api/ (HTTP/SSE) ui/ (Weboberfläche)
+  cli/         Kommandos                                  service/     systemd-Unit und Installationsplan
+  app.ts       Bootstrap einer Instanz
+```
+
+Konventionen: [docs/conventions.md](docs/conventions.md) · Arbeitspakete: [docs/work-items/](docs/work-items/README.md) ·
+Übergaben: `docs/handoff/`.
+
+## Lizenz
+
+[MIT](LICENSE) © 2026 brokoskokoli

package/dist/api/errors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Consistent API error form `{ error: { code, message, details? } }` and the
+ * mapping of component error codes to HTTP status codes.
+ */
+import { type Redactor } from '../core/index.js';
+/** Error raised by route handlers with an explicit HTTP status. */
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(statusCode: number, code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+/** JSON body of an error response. */
+export interface ApiErrorBody {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+/** HTTP status per component error code (WI-03/07/08/09 contracts). */
+export declare const ERROR_STATUS: Readonly<Record<string, number>>;
+/** Status + body for any thrown value. Unknown errors become 500 without internals. */
+export declare function toErrorResponse(err: unknown, redact?: Redactor): {
+    status: number;
+    body: ApiErrorBody;
+};

package/dist/api/errors.js

@@ -0,0 +1,80 @@
+/**
+ * Consistent API error form `{ error: { code, message, details? } }` and the
+ * mapping of component error codes to HTTP status codes.
+ */
+import { errorMessage, isOrchestratorError, redactValue } from '../core/index.js';
+/** Error raised by route handlers with an explicit HTTP status. */
+export class ApiError extends Error {
+    statusCode;
+    code;
+    details;
+    constructor(statusCode, code, message, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+        this.details = details;
+        this.name = 'ApiError';
+    }
+}
+/** HTTP status per component error code (WI-03/07/08/09 contracts). */
+export const ERROR_STATUS = {
+    validation_error: 400,
+    invalid_request: 400,
+    manual_item_required: 400,
+    manual_item_not_supported: 400,
+    manual_item_invalid_ref: 400,
+    invalid_parameters: 400,
+    lifecycle_not_skippable: 400,
+    not_found: 404,
+    config_unknown_workflow: 404,
+    manual_item_not_found: 404,
+    view_not_found: 404,
+    lock_conflict: 409,
+    blocked: 409,
+    block_exists: 409,
+    invalid_transition: 409,
+    run_not_reserved: 409,
+    run_already_started: 409,
+    run_not_active: 409,
+    run_not_cancellable: 409,
+    run_not_controlled: 409,
+    run_not_recovery_pending: 409,
+    lifecycle_busy: 409,
+    lifecycle_not_retryable: 409,
+    config_invalid: 422,
+    source_unavailable: 502,
+    run_controller_not_ready: 503,
+    run_controller_not_accepting: 503,
+    scheduler_not_accepting: 503,
+    not_ready: 503,
+    kill_failed: 500,
+};
+/** Status + body for any thrown value. Unknown errors become 500 without internals. */
+export function toErrorResponse(err, redact = (s) => s) {
+    if (err instanceof ApiError) {
+        return {
+            status: err.statusCode,
+            body: { error: compact(err.code, redact(err.message), err.details === undefined ? undefined : redactValue(err.details, redact)) },
+        };
+    }
+    if (isOrchestratorError(err)) {
+        const status = ERROR_STATUS[err.code] ?? 500;
+        return {
+            status,
+            body: { error: compact(err.code, redact(err.message), err.details === undefined ? undefined : redactValue(err.details, redact)) },
+        };
+    }
+    // Fastify errors (body too large, bad JSON, unsupported media type, ...).
+    const fe = err;
+    if (typeof fe.statusCode === 'number' && fe.statusCode >= 400 && fe.statusCode < 500) {
+        return {
+            status: fe.statusCode,
+            body: { error: compact(typeof fe.code === 'string' ? fe.code.toLowerCase() : 'invalid_request', redact(errorMessage(err))) },
+        };
+    }
+    return { status: 500, body: { error: { code: 'internal_error', message: 'Internal server error' } } };
+}
+function compact(code, message, details) {
+    return details === undefined ? { code, message } : { code, message, details };
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"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"}

package/dist/api/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Component `api` – public API (WI-10): Fastify HTTP API under `/api/v1`,
+ * `/health`, `/ready`, SSE event hub and log paging (Spec §15, §21).
+ * Other components import from this module only.
+ */
+export { createApiServer, CSRF_HEADER, isAllowedHost, type ApiDeps, type ReadinessReport } from './server.js';
+export { ApiError, ERROR_STATUS, toErrorResponse, type ApiErrorBody } from './errors.js';
+export { EventHub, DEFAULT_SSE_HEARTBEAT_MS, DEFAULT_SSE_MAX_BUFFER_BYTES, DEFAULT_SSE_MAX_REPLAY, type EventHubOptions, type StreamEvent, } from './sse.js';
+export { readLogPage, DEFAULT_LOG_PAGE_BYTES, MAX_LOG_PAGE_BYTES, type LogPage } from './logs.js';
+export { toRunSummary, runOutcome, type RunOutcome, type RunSummary, type ActionView } from './serialize.js';

package/dist/api/index.js

@@ -0,0 +1,11 @@
+/**
+ * Component `api` – public API (WI-10): Fastify HTTP API under `/api/v1`,
+ * `/health`, `/ready`, SSE event hub and log paging (Spec §15, §21).
+ * Other components import from this module only.
+ */
+export { createApiServer, CSRF_HEADER, isAllowedHost } from './server.js';
+export { ApiError, ERROR_STATUS, toErrorResponse } from './errors.js';
+export { EventHub, DEFAULT_SSE_HEARTBEAT_MS, DEFAULT_SSE_MAX_BUFFER_BYTES, DEFAULT_SSE_MAX_REPLAY, } from './sse.js';
+export { readLogPage, DEFAULT_LOG_PAGE_BYTES, MAX_LOG_PAGE_BYTES } from './logs.js';
+export { toRunSummary, runOutcome } from './serialize.js';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAsC,MAAM,aAAa,CAAC;AAC9G,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAqB,MAAM,aAAa,CAAC;AACzF,OAAO,EACL,QAAQ,EACR,wBAAwB,EACxB,4BAA4B,EAC5B,sBAAsB,GAGvB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,kBAAkB,EAAgB,MAAM,WAAW,CAAC;AAClG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAqD,MAAM,gBAAgB,CAAC"}

package/dist/api/logs.d.ts

@@ -0,0 +1,30 @@
+/** Default page size. */
+export declare const DEFAULT_LOG_PAGE_BYTES: number;
+/** Max page size per request. */
+export declare const MAX_LOG_PAGE_BYTES: number;
+/** One page of a log stream. */
+export interface LogPage {
+    stream: 'stdout' | 'stderr';
+    /** Byte offset of `data` in the file. */
+    offset: number;
+    /** Byte length of `data`. */
+    length: number;
+    /** Offset to request next (`offset + length`). */
+    nextOffset: number;
+    /** Current file size in bytes (0 if the file does not exist). */
+    size: number;
+    /** True if `nextOffset` reached the current end of the file. */
+    eof: boolean;
+    /** False if the log file does not exist (yet). */
+    exists: boolean;
+    data: string;
+}
+/**
+ * Read a page. `tail` (bytes) reads the last bytes of the file and takes
+ * precedence over `offset`.
+ */
+export declare function readLogPage(file: string, stream: 'stdout' | 'stderr', options?: {
+    offset?: number;
+    limit?: number;
+    tail?: number;
+}): Promise<LogPage>;

package/dist/api/logs.js

@@ -0,0 +1,88 @@
+/**
+ * Paged access to run log files (Spec §15, §16): byte offsets per stream,
+ * bounded page size, tail mode. Never reads a whole (up to 100 MB) file.
+ *
+ * Pages are cut at UTF-8 character boundaries: an incomplete multi-byte
+ * sequence at the end of a page is left for the next page, and a page that
+ * starts inside a sequence (tail mode) skips the continuation bytes.
+ */
+import { open, stat } from 'node:fs/promises';
+/** Default page size. */
+export const DEFAULT_LOG_PAGE_BYTES = 64 * 1024;
+/** Max page size per request. */
+export const MAX_LOG_PAGE_BYTES = 1024 * 1024;
+/**
+ * Read a page. `tail` (bytes) reads the last bytes of the file and takes
+ * precedence over `offset`.
+ */
+export async function readLogPage(file, stream, options = {}) {
+    const limit = Math.min(Math.max(1, Math.floor(options.limit ?? DEFAULT_LOG_PAGE_BYTES)), MAX_LOG_PAGE_BYTES);
+    let size;
+    try {
+        const st = await stat(file);
+        if (!st.isFile())
+            throw Object.assign(new Error('not a file'), { code: 'ENOENT' });
+        size = st.size;
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            return { stream, offset: 0, length: 0, nextOffset: 0, size: 0, eof: true, exists: false, data: '' };
+        }
+        throw err;
+    }
+    let offset;
+    let length;
+    if (options.tail !== undefined) {
+        const tail = Math.min(Math.max(0, Math.floor(options.tail)), MAX_LOG_PAGE_BYTES);
+        offset = Math.max(0, size - tail);
+        length = size - offset;
+    }
+    else {
+        offset = Math.min(Math.max(0, Math.floor(options.offset ?? 0)), size);
+        length = Math.min(limit, size - offset);
+    }
+    if (length === 0)
+        return { stream, offset, length: 0, nextOffset: offset, size, eof: offset >= size, exists: true, data: '' };
+    const handle = await open(file, 'r');
+    let buf;
+    try {
+        buf = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buf, 0, length, offset);
+        buf = buf.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+    // Skip leading continuation bytes (page started inside a character) – only when not at the start of the file.
+    let start = 0;
+    if (offset > 0)
+        while (start < buf.length && start < 3 && isContinuation(buf[start]))
+            start++;
+    // Leave an incomplete trailing sequence for the next page; if the page consists of nothing
+    // else and it is the end of the file (invalid trailing bytes), return it anyway so readers progress.
+    let end = completeLength(buf, start);
+    if (end <= start && buf.length > start && offset + buf.length >= size)
+        end = buf.length;
+    const data = buf.subarray(start, end).toString('utf8');
+    const pageOffset = offset + start;
+    const pageLength = end - start;
+    const nextOffset = pageOffset + pageLength;
+    return { stream, offset: pageOffset, length: pageLength, nextOffset, size, eof: nextOffset >= size, exists: true, data };
+}
+function isContinuation(byte) {
+    return (byte & 0xc0) === 0x80;
+}
+/** Length of `buf` without an incomplete UTF-8 sequence at the end. */
+function completeLength(buf, start) {
+    const n = buf.length;
+    // Find the start byte of the last (possibly incomplete) sequence within the last 4 bytes.
+    for (let i = n - 1; i >= Math.max(start, n - 4); i--) {
+        const byte = buf[i];
+        if (isContinuation(byte))
+            continue;
+        const need = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+        return i + need <= n ? n : i;
+    }
+    return n;
+}
+//# sourceMappingURL=logs.js.map

package/dist/api/logs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.js","sourceRoot":"","sources":["../../src/api/logs.ts"],"names":[],"mappings":"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"}

package/dist/api/serialize.d.ts

@@ -0,0 +1,65 @@
+/**
+ * API response shapes (documented in docs/api.md). Responses never contain
+ * secrets: run snapshots hold identity IDs only, worker context/result files
+ * are redacted by the executor, error details pass `redactValue`.
+ */
+import { type TechnicalStatus } from '../core/index.js';
+import type { EffectiveWorkflow } from '../config/index.js';
+import type { ActionAttemptRecord, BlockRecord, RunActionRecord, RunRecord } from '../persistence/index.js';
+import type { CronWorkflowStatus, WorkflowPlanningDiagnosis } from '../scheduler/index.js';
+/**
+ * Unambiguous outcome of a run for the UI (Spec §21): business `failure` vs.
+ * technical errors vs. cancelled; `lifecycleFailed` separately.
+ */
+export type RunOutcome = 'active' | 'success' | 'failure' | 'technical_error' | 'cancelled';
+/** Run in lists. */
+export interface RunSummary {
+    id: string;
+    workflowId: string;
+    workflowName: string | null;
+    triggerType: RunRecord['triggerType'];
+    sourceId: string | null;
+    sourceItemKey: string | null;
+    sourceUrl: string | null;
+    scheduledFor: string | null;
+    identity: string | null;
+    status: TechnicalStatus;
+    active: boolean;
+    outcome: RunOutcome;
+    finalStatus: RunRecord['finalStatus'];
+    businessResult: RunRecord['businessResult'];
+    finalReason: string | null;
+    /** `result.message` of the worker result file, if any. */
+    resultMessage: string | null;
+    statusMessage: string | null;
+    exitCode: number | null;
+    lifecycleStatus: RunRecord['lifecycleStatus'];
+    lifecycleFailed: boolean;
+    createdAt: string;
+    startedAt: string | null;
+    finishedAt: string | null;
+    durationMs: number | null;
+}
+/** Action with its attempts. */
+export interface ActionView extends RunActionRecord {
+    attemptsDetail: ActionAttemptRecord[];
+}
+/** Outcome classification (see {@link RunOutcome}). */
+export declare function runOutcome(run: Pick<RunRecord, 'status' | 'businessResult'>): RunOutcome;
+/** Summary of a run. */
+export declare function toRunSummary(run: RunRecord): RunSummary;
+/** Extra fields of the run detail. */
+export declare function runDetailFields(run: RunRecord): Record<string, unknown>;
+/** Workflow in lists / detail. */
+export declare function toWorkflowView(wf: EffectiveWorkflow, extra: {
+    activeRuns: number;
+    activeBlocks: number;
+    cron: CronWorkflowStatus | null;
+    diagnosis: WorkflowPlanningDiagnosis | undefined;
+}): Record<string, unknown>;
+/** Block with UI helpers. */
+export declare function toBlockView(block: BlockRecord, extra: {
+    affectedRunIds: string[];
+    sourceUrl: string | null;
+    workflowName: string | null;
+}): Record<string, unknown>;