@baselineos/temporal 1.6.0

package/README.md

@@ -0,0 +1,21 @@
+# @baselineos/temporal
+
+Temporal.io workflow integration for BaselineOS. Provides durable
+workflow execution, activity definitions, and the client/worker pair.
+
+Extracted from `baselineos/src/temporal/` in Sprint 4.2a so consumers
+can install Temporal support without pulling the entire BaselineOS
+runtime.
+
+## Usage
+
+```typescript
+import { createTemporalClient, createActivities, BASELINE_TASK_QUEUE } from '@baselineos/temporal';
+```
+
+The `baselineos` package re-exports the same surface for backward
+compatibility — existing consumers don't need to change imports.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import { Task, ExecutionStep, Artifact, VerificationResult, Review } from '@baselineos/protocol-core';
+import * as _temporalio_client from '@temporalio/client';
+import { Client } from '@temporalio/client';
+
+/**
+ * Minimal type stubs for the host runtime.
+ *
+ * Carryover #35: temporal can't depend on `baselineos` (cycle), so we
+ * define the narrow shape of ExecutionEngine + DecompositionResult that
+ * temporal activities actually use. The real implementations live in
+ * baselineos/src/core/execution-engine.ts; this file mirrors only the
+ * surface the activities call.
+ *
+ * @license Apache-2.0
+ */
+
+/** A decomposed task plan returned by ExecutionEngine.decompose(). */
+interface DecompositionResult {
+    phases: Array<{
+        title: string;
+        description: string;
+        capabilities: string[];
+    }>;
+    estimatedComplexity: Task['complexity'];
+    rationale: string;
+}
+/** A single compliance violation; mirrors baselineos/src/core/compliance-gate.ts. */
+interface ComplianceViolation {
+    principleId: string;
+    name: string;
+    severity: 'blocking' | 'warning';
+    evidence: string;
+    line?: number;
+}
+/** Compliance result attached to an ExecutionResult. */
+interface ComplianceResult {
+    passed: boolean;
+    violations: ComplianceViolation[];
+    warnings: ComplianceViolation[];
+    score: number;
+}
+/**
+ * The shape of an execution-engine `execute()` return. Mirrors the runtime
+ * baselineos/src/core/execution-engine.ts definition. Kept local because
+ * protocol-core's ExecutionResult is a different concept (lang IR).
+ */
+interface ExecutionResult {
+    output: string;
+    tokensUsed: number;
+    duration: number;
+    artifacts: Artifact[];
+    model: string;
+    compliance: ComplianceResult;
+}
+/**
+ * Minimal ExecutionEngine surface that temporal activities call.
+ *
+ * Kept narrow on purpose — the full ExecutionEngine in baselineos has many
+ * more methods (selfVerify variants, streaming, cache integration, etc.).
+ * Activities only need these four; expand only when a new activity needs
+ * something else.
+ */
+interface ExecutionEngine {
+    execute(task: Task, step?: ExecutionStep): Promise<ExecutionResult>;
+    selfVerify(task: Task, output: string): Promise<VerificationResult>;
+    conductReview(task: Task, output: string, reviewType: 'supervisor' | 'quality'): Promise<Review>;
+    decompose(task: Task): Promise<DecompositionResult>;
+}
+
+/**
+ * Temporal Activities — SIGNAL-045
+ *
+ * Activity functions executed by the Temporal worker. Each activity wraps a
+ * single operation on the execution engine and is retried independently by
+ * Temporal on failure. Activities are the boundary between Temporal's durable
+ * orchestration and the existing BaselineOS execution infrastructure.
+ *
+ * Retry policy (applied by workflow — see workflows.ts):
+ *   - maximumAttempts: 3
+ *   - initialInterval: 1s, backoffCoefficient: 2, maximumInterval: 30s
+ *   - Non-retryable: ApplicationFailure with nonRetryable=true
+ *
+ * All activities receive their dependencies via context injection through
+ * createActivities(). This keeps activities pure functions for testing.
+ *
+ * @license Apache-2.0
+ */
+
+interface ActivityDependencies {
+    engine: ExecutionEngine;
+}
+interface ExecuteTaskInput {
+    task: Task;
+    step?: ExecutionStep;
+}
+interface SelfVerifyInput {
+    task: Task;
+    output: string;
+}
+interface ConductReviewInput {
+    task: Task;
+    output: string;
+    reviewType: 'supervisor' | 'quality';
+}
+interface DecomposeInput {
+    task: Task;
+}
+/**
+ * Create activity functions bound to the given execution engine.
+ * Register the returned object with the Temporal worker:
+ *   worker.run({ activities: createActivities({ engine }) })
+ */
+declare function createActivities(deps: ActivityDependencies): {
+    /**
+     * Execute a task (or a specific step) using the underlying engine.
+     * Returns ExecutionResult on success; throws ApplicationFailure on compliance violations.
+     */
+    executeTask(input: ExecuteTaskInput): Promise<ExecutionResult>;
+    /**
+     * Agent self-verifies its output against the task's acceptance criteria.
+     */
+    selfVerifyTask(input: SelfVerifyInput): Promise<VerificationResult>;
+    /**
+     * Supervisor or quality review of task output.
+     */
+    conductTaskReview(input: ConductReviewInput): Promise<Review>;
+    /**
+     * Decompose a complex task into structured subtasks.
+     */
+    decomposeTask(input: DecomposeInput): Promise<DecompositionResult>;
+};
+type BaselineActivities = ReturnType<typeof createActivities>;
+
+/**
+ * Temporal Client Factory — SIGNAL-045
+ *
+ * Creates a Temporal client configured from environment variables.
+ * The client is used by TemporalOrchestrator to submit workflows.
+ *
+ * Environment variables:
+ *   TEMPORAL_ADDRESS     — Temporal frontend address (default: localhost:7233)
+ *   TEMPORAL_NAMESPACE   — Temporal namespace (default: baseline)
+ *   TEMPORAL_TLS         — 'true' to enable TLS (default: false)
+ *
+ * @license Apache-2.0
+ */
+
+interface TemporalClientConfig {
+    address?: string;
+    namespace?: string;
+    tls?: boolean;
+}
+declare const BASELINE_TASK_QUEUE = "baseline-task-queue";
+/**
+ * Create and connect a Temporal client.
+ * Call client.connection.close() when done.
+ */
+declare function createTemporalClient(config?: TemporalClientConfig): Promise<Client>;
+
+interface BaselineTaskWorkflowInput {
+    task: Task;
+    step?: ExecutionStep;
+    /** Whether to run supervisor review after self-verify (default: false) */
+    runSupervisorReview?: boolean;
+    /** Whether to decompose the task before executing (default: false) */
+    runDecomposition?: boolean;
+    /** Whether to pause for human approval before execution (default: false) */
+    requireHumanApproval?: boolean;
+}
+interface WorkflowResult {
+    taskId: string;
+    output: string;
+    tokensUsed: number;
+    duration: number;
+    model: string;
+    verification: VerificationResult;
+    review?: Review;
+    decomposition?: DecompositionResult;
+    phase: WorkflowPhase;
+}
+type WorkflowPhase = 'initialising' | 'awaiting-approval' | 'decomposing' | 'executing' | 'verifying' | 'reviewing' | 'completed' | 'failed';
+declare const humanApprovalSignal: _temporalio_client.SignalDefinition<[{
+    approved: boolean;
+    reason: string;
+}], string>;
+declare const getStatusQuery: _temporalio_client.QueryDefinition<WorkflowPhase, [], string>;
+declare function baselineTaskWorkflow(input: BaselineTaskWorkflowInput): Promise<WorkflowResult>;
+
+export { type ActivityDependencies, BASELINE_TASK_QUEUE, type BaselineActivities, type BaselineTaskWorkflowInput, type TemporalClientConfig, type WorkflowPhase, type WorkflowResult, baselineTaskWorkflow, createActivities, createTemporalClient, getStatusQuery, humanApprovalSignal };

package/dist/index.js

@@ -0,0 +1,210 @@
+// src/activities.ts
+import { ApplicationFailure } from "@temporalio/activity";
+function createActivities(deps) {
+  const { engine } = deps;
+  return {
+    /**
+     * Execute a task (or a specific step) using the underlying engine.
+     * Returns ExecutionResult on success; throws ApplicationFailure on compliance violations.
+     */
+    async executeTask(input) {
+      const result = await engine.execute(input.task, input.step);
+      if (!result.compliance.passed) {
+        const violations = result.compliance.violations.filter((v) => v.severity === "blocking").map((v) => v.name).join(", ");
+        throw ApplicationFailure.nonRetryable(
+          `Compliance gate failed \u2014 blocking violations: ${violations}`,
+          "ComplianceFailure"
+        );
+      }
+      return result;
+    },
+    /**
+     * Agent self-verifies its output against the task's acceptance criteria.
+     */
+    async selfVerifyTask(input) {
+      return engine.selfVerify(input.task, input.output);
+    },
+    /**
+     * Supervisor or quality review of task output.
+     */
+    async conductTaskReview(input) {
+      return engine.conductReview(input.task, input.output, input.reviewType);
+    },
+    /**
+     * Decompose a complex task into structured subtasks.
+     */
+    async decomposeTask(input) {
+      return engine.decompose(input.task);
+    }
+  };
+}
+
+// src/client.ts
+import { Client, Connection } from "@temporalio/client";
+var BASELINE_TASK_QUEUE = "baseline-task-queue";
+async function createTemporalClient(config = {}) {
+  const address = config.address ?? process.env.TEMPORAL_ADDRESS ?? "localhost:7233";
+  const namespace = config.namespace ?? process.env.TEMPORAL_NAMESPACE ?? "baseline";
+  const tls = config.tls ?? process.env.TEMPORAL_TLS === "true";
+  const connection = await Connection.connect({
+    address,
+    tls: tls ? {} : false
+  });
+  return new Client({ connection, namespace });
+}
+
+// src/workflows.ts
+import { proxyActivities, defineSignal, defineQuery, setHandler, condition, sleep, ApplicationFailure as ApplicationFailure2 } from "@temporalio/workflow";
+var humanApprovalSignal = defineSignal("humanApproval");
+var getStatusQuery = defineQuery("getStatus");
+var {
+  executeTask,
+  selfVerifyTask,
+  conductTaskReview,
+  decomposeTask
+} = proxyActivities({
+  startToCloseTimeout: "5 minutes",
+  retry: {
+    maximumAttempts: 3,
+    initialInterval: "1 second",
+    backoffCoefficient: 2,
+    maximumInterval: "30 seconds",
+    nonRetryableErrorTypes: ["ComplianceFailure"]
+  }
+});
+async function baselineTaskWorkflow(input) {
+  let phase = "initialising";
+  setHandler(getStatusQuery, () => phase);
+  if (input.requireHumanApproval) {
+    phase = "awaiting-approval";
+    let approved = false;
+    let approvalReason = "";
+    setHandler(humanApprovalSignal, ({ approved: a, reason }) => {
+      approved = a;
+      approvalReason = reason;
+    });
+    const signalReceived = await condition(() => approved || approvalReason !== "", "24 hours");
+    if (!signalReceived || !approved) {
+      throw ApplicationFailure2.nonRetryable(
+        `Human approval not received within timeout${approvalReason ? `: ${approvalReason}` : ""}`,
+        "ApprovalTimeout"
+      );
+    }
+  }
+  let decomposition;
+  if (input.runDecomposition) {
+    phase = "decomposing";
+    decomposition = await decomposeTask({ task: input.task });
+    await sleep(100);
+  }
+  phase = "executing";
+  const executionStart = Date.now();
+  const execution = await executeTask({
+    task: input.task,
+    step: input.step
+  });
+  phase = "verifying";
+  const verification = await selfVerifyTask({
+    task: input.task,
+    output: execution.output
+  });
+  let review;
+  const needsReview = input.runSupervisorReview || !verification.passed;
+  if (needsReview) {
+    phase = "reviewing";
+    review = await conductTaskReview({
+      task: input.task,
+      output: execution.output,
+      reviewType: verification.passed ? "quality" : "supervisor"
+    });
+  }
+  phase = "completed";
+  return {
+    taskId: input.task.id,
+    output: execution.output,
+    tokensUsed: execution.tokensUsed,
+    duration: Date.now() - executionStart,
+    model: execution.model,
+    verification,
+    review,
+    decomposition,
+    phase
+  };
+}
+export {
+  BASELINE_TASK_QUEUE,
+  baselineTaskWorkflow,
+  createActivities,
+  createTemporalClient,
+  getStatusQuery,
+  humanApprovalSignal
+};
+/**
+ * Temporal Activities — SIGNAL-045
+ *
+ * Activity functions executed by the Temporal worker. Each activity wraps a
+ * single operation on the execution engine and is retried independently by
+ * Temporal on failure. Activities are the boundary between Temporal's durable
+ * orchestration and the existing BaselineOS execution infrastructure.
+ *
+ * Retry policy (applied by workflow — see workflows.ts):
+ *   - maximumAttempts: 3
+ *   - initialInterval: 1s, backoffCoefficient: 2, maximumInterval: 30s
+ *   - Non-retryable: ApplicationFailure with nonRetryable=true
+ *
+ * All activities receive their dependencies via context injection through
+ * createActivities(). This keeps activities pure functions for testing.
+ *
+ * @license Apache-2.0
+ */
+/**
+ * Temporal Client Factory — SIGNAL-045
+ *
+ * Creates a Temporal client configured from environment variables.
+ * The client is used by TemporalOrchestrator to submit workflows.
+ *
+ * Environment variables:
+ *   TEMPORAL_ADDRESS     — Temporal frontend address (default: localhost:7233)
+ *   TEMPORAL_NAMESPACE   — Temporal namespace (default: baseline)
+ *   TEMPORAL_TLS         — 'true' to enable TLS (default: false)
+ *
+ * @license Apache-2.0
+ */
+/**
+ * Temporal Workflows — SIGNAL-045
+ *
+ * Durable workflow definitions for BaselineOS task execution.
+ *
+ * Workflows run in Temporal's deterministic sandbox. They orchestrate
+ * activity calls and carry the full execution history, enabling:
+ *   - Automatic retry of failed activities (with backoff)
+ *   - Pause/resume after process restarts
+ *   - Full audit trail via Temporal's event history
+ *   - Human-in-the-loop signals (humanApproval, pause, cancel)
+ *
+ * Main workflow: baselineTaskWorkflow
+ *   1. [Optional] decompose — if task complexity is 'epic' or 'complex'
+ *   2. execute — call the LLM via executeTask activity
+ *   3. selfVerify — agent verifies its own output
+ *   4. [Optional] supervisorReview — for high-priority or failed self-verify
+ *   5. Return WorkflowResult
+ *
+ * Signals:
+ *   humanApproval(approved: boolean, reason: string) — unblocks paused workflows
+ *
+ * Queries:
+ *   getStatus() — returns current workflow phase
+ *
+ * @license Apache-2.0
+ */
+/**
+ * @baselineos/temporal — Temporal.io workflow integration for BaselineOS
+ *
+ * Provides activity definitions, the client wrapper, and the workflow
+ * definitions that BaselineOS uses to execute tasks durably on a Temporal
+ * cluster. The standalone worker script remains in the baselineos package
+ * (it needs a runtime AnthropicEngine instance and would otherwise create
+ * a circular runtime dependency).
+ *
+ * @license Apache-2.0
+ */

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@baselineos/temporal",
+  "version": "1.6.0",
+  "description": "BaselineOS Temporal.io workflow integration — durable workflow execution",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@temporalio/activity": "^1.17.2",
+    "@temporalio/client": "^1.17.2",
+    "@temporalio/worker": "^1.17.2",
+    "@temporalio/workflow": "^1.17.2",
+    "@baselineos/protocol-core": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}