@syncended/dsh-automations 0.1.0

package/dist/validation.js

@@ -0,0 +1,159 @@
+import { isAbsolute } from 'node:path';
+import { validateCron } from './cron.js';
+const JOB_ID = /^[a-z0-9](?:[a-z0-9-]{0,62})$/;
+const OVERLAP_POLICIES = new Set(['skip', 'queue', 'allow']);
+const MISFIRE_POLICIES = new Set(['skip', 'run-once']);
+const MAX_PROMPT_CHARS = 131_072;
+const MAX_NAME_CHARS = 120;
+const MAX_TIMEOUT_MS = 24 * 60 * 60 * 1_000;
+const MIN_TIMEOUT_MS = 1_000;
+export class AutomationInputError extends Error {
+    code;
+    status;
+    constructor(message, code = 'INVALID_INPUT', status = 400, options) {
+        super(message, options);
+        this.name = 'AutomationInputError';
+        this.code = code;
+        this.status = status;
+    }
+}
+function object(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new AutomationInputError(`${path} must be an object`);
+    }
+    return value;
+}
+function rejectUnknown(value, allowed, path) {
+    const allowedSet = new Set(allowed);
+    const unknown = Object.keys(value).filter((key) => !allowedSet.has(key));
+    if (unknown.length > 0)
+        throw new AutomationInputError(`${path} contains unknown field(s): ${unknown.join(', ')}`);
+}
+function string(value, path, maxChars = 4_096) {
+    if (typeof value !== 'string')
+        throw new AutomationInputError(`${path} must be a string`);
+    const normalized = value.trim();
+    if (normalized === '')
+        throw new AutomationInputError(`${path} must not be empty`);
+    if (normalized.length > maxChars)
+        throw new AutomationInputError(`${path} must be at most ${maxChars} characters`);
+    return normalized;
+}
+function optionalString(value, path, maxChars = 512) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return string(value, path, maxChars);
+}
+function boolean(value, path, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw new AutomationInputError(`${path} must be a boolean`);
+    return value;
+}
+function integer(value, path, fallback, min, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw new AutomationInputError(`${path} must be a safe integer between ${min} and ${max}`);
+    }
+    return value;
+}
+export function normalizeJobId(value) {
+    const id = value.trim().toLowerCase();
+    if (!JOB_ID.test(id)) {
+        throw new AutomationInputError('job id must match [a-z0-9][a-z0-9-]{0,62}', 'INVALID_JOB_ID');
+    }
+    return id;
+}
+export function slugifyJobId(name) {
+    const slug = name
+        .normalize('NFKD')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 48);
+    return slug === '' ? 'automation' : slug;
+}
+function normalizeTask(value) {
+    const task = object(value, 'spec.task');
+    rejectUnknown(task, ['kind', 'prompt'], 'spec.task');
+    if (task.kind !== undefined && task.kind !== 'agent') {
+        throw new AutomationInputError('spec.task.kind must be "agent"');
+    }
+    return {
+        kind: 'agent',
+        prompt: string(task.prompt, 'spec.task.prompt', MAX_PROMPT_CHARS),
+    };
+}
+function normalizeExecution(value) {
+    const execution = object(value, 'spec.execution');
+    rejectUnknown(execution, ['cwd', 'provider', 'model', 'reasoningEffort', 'agentPreset', 'permissionPreset', 'timeoutMs'], 'spec.execution');
+    const cwd = string(execution.cwd, 'spec.execution.cwd', 8_192);
+    if (!isAbsolute(cwd))
+        throw new AutomationInputError('spec.execution.cwd must be an absolute path');
+    const provider = optionalString(execution.provider, 'spec.execution.provider');
+    const model = optionalString(execution.model, 'spec.execution.model');
+    if ((provider === undefined) !== (model === undefined)) {
+        throw new AutomationInputError('spec.execution.provider and spec.execution.model must be set together or both omitted');
+    }
+    const reasoningEffort = optionalString(execution.reasoningEffort, 'spec.execution.reasoningEffort');
+    const agentPreset = optionalString(execution.agentPreset, 'spec.execution.agentPreset');
+    const permissionPreset = optionalString(execution.permissionPreset, 'spec.execution.permissionPreset') ?? 'workspace-write';
+    const timeoutMs = integer(execution.timeoutMs, 'spec.execution.timeoutMs', 3_600_000, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    return {
+        cwd,
+        ...(provider === undefined ? {} : { provider }),
+        ...(model === undefined ? {} : { model }),
+        ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+        ...(agentPreset === undefined ? {} : { agentPreset }),
+        permissionPreset,
+        timeoutMs,
+    };
+}
+function normalizePolicies(value) {
+    const policies = value === undefined ? {} : object(value, 'spec.policies');
+    rejectUnknown(policies, ['overlap', 'misfire'], 'spec.policies');
+    const overlap = policies.overlap ?? 'skip';
+    if (typeof overlap !== 'string' || !OVERLAP_POLICIES.has(overlap)) {
+        throw new AutomationInputError('spec.policies.overlap must be skip, queue, or allow');
+    }
+    const misfire = policies.misfire ?? 'run-once';
+    if (typeof misfire !== 'string' || !MISFIRE_POLICIES.has(misfire)) {
+        throw new AutomationInputError('spec.policies.misfire must be skip or run-once');
+    }
+    return {
+        overlap: overlap,
+        misfire: misfire,
+    };
+}
+export function normalizeJobSpec(value) {
+    const spec = object(value, 'spec');
+    rejectUnknown(spec, ['name', 'enabled', 'schedule', 'task', 'execution', 'policies'], 'spec');
+    const schedule = object(spec.schedule, 'spec.schedule');
+    rejectUnknown(schedule, ['cron', 'timezone'], 'spec.schedule');
+    const normalizedSchedule = validateCron(string(schedule.cron, 'spec.schedule.cron', 256), optionalString(schedule.timezone, 'spec.schedule.timezone', 256) ?? 'UTC');
+    return {
+        name: string(spec.name, 'spec.name', MAX_NAME_CHARS),
+        enabled: boolean(spec.enabled, 'spec.enabled', true),
+        schedule: normalizedSchedule,
+        task: normalizeTask(spec.task),
+        execution: normalizeExecution(spec.execution),
+        policies: normalizePolicies(spec.policies),
+    };
+}
+export function assertExpectedVersion(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new AutomationInputError('expectedVersion must be a positive safe integer');
+    }
+    return value;
+}
+export function assertJsonObject(value, path = 'request body') {
+    return object(value, path);
+}
+export function assertOnlyKeys(value, allowed, path = 'request body') {
+    rejectUnknown(value, allowed, path);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

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

package/docs/architecture.md

@@ -0,0 +1,195 @@
+# Architecture
+
+## Goals
+
+The MVP must solve deployment-level scheduling without coupling future automation semantics to cron. A schedule decides **when to admit a run**; an executor decides **how that run progresses**.
+
+Non-goals for the first release:
+
+- distributed/multi-host workers;
+- exactly-once external effects;
+- calendar syntax beyond standard five-field cron;
+- arbitrary untrusted code execution;
+- automatic retry of a run that may already have produced side effects.
+
+## Components
+
+```text
+Settings UI / HTTP API
+          │
+          ▼
+ AutomationService ─── ProjectPolicy
+          │
+          ├── AutomationStateStore (atomic JSON, occurrence index)
+          │
+          └── AutomationScheduler
+                 │
+                 └── ExecutorRegistry
+                        └── HarnessAgentExecutor (MVP)
+```
+
+### AutomationService
+
+Cordis service `ctx.automations`. It owns input validation, canonical project authorization, metadata discovery, the Web route, and the public executor-registration seam.
+
+### AutomationStateStore
+
+The store owns one versioned document:
+
+- `jobs`: versioned user definitions plus the durable `nextRunAt` watermark;
+- `runs`: orchestration state and immutable execution snapshots;
+- `runOrder`: stable history ordering;
+- `occurrences`: idempotency key → run id.
+
+Every writer mutation:
+
+1. acquires the DSH cross-process file lock;
+2. re-reads and validates the latest complete document;
+3. mutates one detached state;
+4. atomically renames a private `0600` replacement;
+5. publishes the committed state in memory.
+
+The current startup recovery assumes one active scheduler host. The short mutation lock prevents duplicate admission, but a second live host would incorrectly treat the first host's running records as crash orphans. Multi-host support therefore requires leases before it can be advertised.
+
+### AutomationScheduler
+
+The scheduler has four responsibilities only:
+
+1. derive and arm the earliest wall-clock wakeup;
+2. atomically claim due cron/manual occurrences;
+3. apply misfire and overlap policy;
+4. dispatch queued runs through the executor registry under a global concurrency bound.
+
+It never knows how an Agent, workflow, or code task works.
+
+### HarnessAgentExecutor
+
+The `agent` executor:
+
+1. re-authorizes the canonical project;
+2. resolves the job's agent and permission presets;
+3. resolves the current default model or the pinned provider/model route;
+4. creates a fresh Session and Agent through `ctx.agents.create`;
+5. composes the preset in the unpublished setup transaction;
+6. installs model selection and the permission preset;
+7. submits the prompt as a plugin-origin user message;
+8. waits for quiescence, flushes Session persistence, and folds the terminal result;
+9. disposes the live handle while retaining persisted Session history.
+
+No nested `dsh` process is required, and the normal DSH tool, sandbox, approval, persistence, and model routing layers remain authoritative.
+
+## State machine
+
+```text
+                         host crash
+                    ┌────────────────► interrupted
+                    │
+queued ───────────► running ──────────► succeeded
+  │                  │  │
+  │                  │  ├────────────► failed
+  │                  │  ├────────────► timed-out
+  │                  │  └────────────► cancelled
+  ├──────────────────────────────────► cancelled
+  └──────────────────────────────────► skipped
+```
+
+Terminal states never transition. `running` is committed before executor work begins. A crash in the narrow interval after that commit but before the first effect may lose work; retrying automatically would create the more dangerous inverse window—duplicating an effect that completed before the crash.
+
+## Admission and idempotency
+
+A cron key is:
+
+```text
+<job-id>:cron:<scheduled-for-utc>
+```
+
+A manual key uses a random UUID. The occurrence index and the scheduler watermark are written together. Missed cron history is latest-only:
+
+- `skip`: record the overdue occurrence as skipped and advance past `now`;
+- `run-once`: select the latest due occurrence, admit one run, and advance past `now`.
+
+There is no backlog explosion after a long shutdown.
+
+## Why runs pin a full job snapshot
+
+A queued run must not change when a user edits or deletes its source job. The snapshot pins:
+
+- job id/version and name;
+- schedule/policy values used at admission;
+- prompt and execution settings;
+- project/model/preset/permission/timeout values.
+
+Deleting a job marks its still-queued runs skipped; already-running work drains against its snapshot.
+
+## Path to durable multi-agent automations
+
+Cron remains one trigger feeding the same `Run` aggregate. The next layers are additive.
+
+### Stage 2: workflow executor
+
+Add `task.kind = "workflow"` and an executor backed by `ctx.workflowEngine`:
+
+- code/meta/args are pinned in the run snapshot;
+- workflow progress is mirrored into durable run events;
+- child Session ids are retained as run artifacts;
+- host cancellation terminates the workflow worker and children.
+
+The existing Harness workflow worker is execution isolation from the event loop, **not** a security sandbox.
+
+### Stage 3: durable task graph
+
+Introduce a graph below one run:
+
+```text
+Run
+ ├── Task A (code/action)
+ ├── Task B (agent) dependsOn A
+ ├── Task C (agent) dependsOn A
+ └── Task D (reduce) dependsOn B,C
+```
+
+Each task needs:
+
+- stable `taskId` and definition version;
+- dependency edges;
+- `pending | ready | leased | running | retry-wait | terminal` state;
+- attempt number and idempotency key;
+- lease owner, expiry, and heartbeat;
+- retry policy with deterministic next-at time;
+- input/output references, not unbounded inline blobs;
+- child Session/workflow references;
+- append-only transition events.
+
+A projector derives runnable tasks. Workers atomically acquire leases. Expired leases become recoverable according to each task's declared effect semantics:
+
+- `pure` / idempotent tasks may retry automatically;
+- `effectful` tasks require an external idempotency key or operator decision;
+- Agent tasks default to effectful because tools may change files or remote systems.
+
+### Stage 4: multi-host storage
+
+Replace the JSON document with SQLite (single machine) or a transactional database (multi-host), while keeping the service and executor contracts:
+
+- unique occurrence constraint;
+- compare-and-swap job versions;
+- transactional task lease acquisition;
+- append-only run/task events plus projections;
+- artifact storage and retention;
+- metrics, dead-letter/operator recovery, and audit export.
+
+## Extension contract
+
+`ctx.automations.registerExecutor(executor)` is intentionally small:
+
+```ts
+interface AutomationExecutor {
+  readonly kind: string
+  execute(context: {
+    run: AutomationRun
+    signal: AbortSignal
+    attachSession(sessionId: string): Promise<void>
+  }): Promise<{ sessionId?: string; output?: string }>
+}
+```
+
+Future executor-specific config should become a discriminated `task` schema. Cron admission, overlap/misfire behavior, run ordering, and the Web run-history surface remain shared.

package/docs/http-api.md

@@ -0,0 +1,40 @@
+# HTTP API
+
+The browser plugin uses a small package-owned API under `/api/automations`. Responses are JSON with `Cache-Control: no-store`.
+
+Mutations require:
+
+```http
+Content-Type: application/json
+X-DSH-Automation-Client: 1
+```
+
+## Read
+
+- `GET /api/automations?limit=100` — jobs and newest-first run history.
+- `GET /api/automations/meta` — current model directory, permission presets, and agent presets.
+
+## Jobs
+
+- `POST /api/automations/jobs` — `{ "id"?: string, "spec": JobSpec }`.
+- `PUT /api/automations/jobs/:id` — `{ "expectedVersion"?: number, "spec": JobSpec }`.
+- `DELETE /api/automations/jobs/:id` — `{}`.
+- `POST /api/automations/jobs/:id/run` — `{}`.
+- `POST /api/automations/jobs/:id/enabled` — `{ "enabled": boolean, "expectedVersion"?: number }`.
+
+## Runs
+
+- `POST /api/automations/runs/:id/cancel` — `{ "reason"?: string }`.
+
+Updates use optimistic job versions. A stale `expectedVersion` returns HTTP 409 with error code `VERSION_CONFLICT`.
+
+Error shape:
+
+```json
+{
+  "error": {
+    "code": "INVALID_INPUT",
+    "message": "..."
+  }
+}
+```

package/docs/security.md

@@ -0,0 +1,51 @@
+# Security model
+
+## Trust boundary
+
+This plugin is intended for the same trusted operator boundary as a local DeepSeek Harness Web deployment. It does not add authentication to `dsh-host-webserver`. If the Harness binds to `0.0.0.0`, anyone who can reach that surface may also be able to manage automations; place the deployment behind an appropriate authenticated boundary before exposing it.
+
+## Management API
+
+Mutation requests must:
+
+- use `application/json`;
+- send `X-DSH-Automation-Client: 1`;
+- originate from the same browser origin when Fetch Metadata / Origin headers are present.
+
+The custom header forces a cross-origin browser request through CORS preflight, which the route does not grant. This is a CSRF fence, not user authentication.
+
+## Filesystem authority
+
+A job's project is canonicalized with `realpath` before storage. `workspace-write` uses that Session cwd as its DSH sandbox root. `allowedProjectRoots`, when configured, are canonicalized and checked with path-segment containment rather than string prefixes.
+
+The executor repeats authorization at dispatch, catching deleted paths and symlink retargeting after configuration.
+
+## Permission presets
+
+The job selects an existing DSH permission preset rather than independently inventing sandbox and approval values. The standard presets are:
+
+- `read-only`: no file mutation; approval remains fail-closed;
+- `workspace-write`: writes only under the Session workspace; widening requires approval;
+- `danger-full-access`: unrestricted file effects and no approval prompts.
+
+Scheduled Agents are not attached to an interactive browser ownership chain. A policy that needs a human prompt must therefore be expected to reject/unavailable when nobody can answer. Jobs should be designed for deterministic unattended behavior and should normally use `read-only` or `workspace-write`.
+
+## Secrets and persisted data
+
+`state.json` contains job prompts, project paths, model/preset selections, run metadata, and bounded final assistant text. It is atomically replaced with mode `0600`; parent directories created by the plugin use `0700`. Session transcripts are persisted by the configured Harness Session backend and may contain substantially more data.
+
+Do not put API keys directly in prompts. Use normal Harness credential providers and environment policy.
+
+## Crash semantics
+
+The store guarantees complete-file replacement, not fsync durability. After a host restart:
+
+- `queued` runs are eligible to dispatch;
+- `running` runs become `interrupted`;
+- interrupted runs are not retried automatically.
+
+This avoids silently repeating side effects but does not provide exactly-once execution. Tasks that call external systems should carry their own stable idempotency key (for example, the automation occurrence key) whenever the target supports one.
+
+## Code and future workflows
+
+The MVP accepts prompt text, not arbitrary executable automation code. A future workflow executor may use the Harness workflow worker, whose worker thread protects host event-loop liveness but is explicitly not a security sandbox. Hostile code requires a separate process/container/VM boundary with a narrow capability protocol.