feat(agentic-org): git-as-database-and-event-store + observe.ts keystone + constitution gate + metrics/review board

agentic-organization/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+**/*.test.ts
+docs
+.git
+.gitignore
+*.md
+deploy

agentic-organization/Dockerfile

@@ -0,0 +1,26 @@
+# Agentic Organization worker runtime.
+#
+# The code runs directly via `node --experimental-strip-types` (no build step,
+# no bundler) per the repo convention. node:24-slim (Debian) is used over Alpine
+# so the `pg` and @nats-io native paths resolve against glibc cleanly.
+FROM node:24-slim
+
+WORKDIR /app
+
+# Install only production deps first for layer caching. package-lock.json is the
+# pinned dependency graph (@nats-io/jetstream, @nats-io/transport-node, pg).
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+# Copy the source. No compile — strip-types runs the .ts directly.
+COPY tsconfig.json ./
+COPY packages ./packages
+COPY apps ./apps
+
+# Run as the non-root node user (defense in depth; the worker needs no root).
+USER node
+
+# The worker is a long-running process driven by the always-on loop. SIGTERM is
+# handled by the entrypoint (graceful shutdown of cockroach + nats ports).
+ENV NODE_ENV=production
+ENTRYPOINT ["node", "--experimental-strip-types", "apps/workers/src/main.ts"]

agentic-organization/apps/workers/src/adapters/ollama-chat-port.ts

@@ -0,0 +1,64 @@
+/**
+ * Ollama chat adapter — a real ChatCompletionPort backed by a model served by
+ * Ollama (https://ollama.com). Runs entirely in-cluster (no external
+ * credentials): the worker POSTs to the in-cluster Ollama service and the model
+ * returns its choice. This is the agent's live decision backend.
+ *
+ * Bounded by an AbortController timeout so a slow/hung model never stalls the
+ * agent run (the model-backed composer falls back to the deterministic policy
+ * when this throws — the agent stays alive).
+ */
+
+import type { ChatCompletionPort, ChatCompletionRequest } from "../../../../packages/application/src/index.ts";
+
+export type CreateOllamaChatPortInput = {
+  baseUrl: string;
+  model: string;
+  timeoutMs?: number;
+  /** injected for testability; defaults to global fetch */
+  fetchImpl?: typeof fetch;
+};
+
+type OllamaChatResponse = {
+  message?: { content?: string };
+};
+
+export function createOllamaChatPort(input: CreateOllamaChatPortInput): ChatCompletionPort {
+  const fetchImpl = input.fetchImpl ?? fetch;
+  const timeoutMs = input.timeoutMs ?? 20_000;
+  const url = `${input.baseUrl.replace(/\/+$/, "")}/api/chat`;
+
+  return {
+    complete: async (request: ChatCompletionRequest): Promise<string> => {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImpl(url, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            model: input.model,
+            stream: false,
+            options: { temperature: 0 },
+            messages: [
+              { role: "system", content: request.system },
+              { role: "user", content: request.user },
+            ],
+          }),
+          signal: controller.signal,
+        });
+        if (!response.ok) {
+          throw new Error(`ollama chat failed: ${response.status} ${response.statusText}`);
+        }
+        const body = (await response.json()) as OllamaChatResponse;
+        const content = body.message?.content;
+        if (typeof content !== "string") {
+          throw new Error("ollama chat response had no message content");
+        }
+        return content;
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}

agentic-organization/apps/workers/src/adapters/subprocess-sandbox.ts

@@ -0,0 +1,70 @@
+/**
+ * Subprocess sandbox adapter — a real SandboxToolPort that runs a tool as a
+ * bounded, isolated child process:
+ *   - executed in a throwaway temp dir (isolated cwd),
+ *   - with a stripped environment (only PATH), so the tool cannot read worker
+ *     secrets/config,
+ *   - killed (SIGKILL) on timeout, with output size capped,
+ *   - never inherits the parent stdio.
+ *
+ * Result-as-DU: failures (non-zero exit, timeout, spawn error) come back as
+ * { ok:false, reason } — the agent run treats tool failure as supplementary,
+ * never fatal.
+ */
+
+import { execFile } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { SandboxToolPort, SandboxToolRequest, SandboxToolResult } from "../../../../packages/application/src/index.ts";
+
+const MAX_OUTPUT_BYTES = 64 * 1024;
+
+/** POSIX "/..." or Windows "C:\..." / "C:/...". */
+function isAbsolutePath(command: string): boolean {
+  return command.startsWith("/") || /^[A-Za-z]:[\\/]/.test(command);
+}
+
+export function createSubprocessSandbox(): SandboxToolPort {
+  return {
+    run: async (request: SandboxToolRequest): Promise<SandboxToolResult> => {
+      // The contract requires an absolute command path. A relative command would
+      // be resolved via PATH and could execute an unexpected binary, so reject
+      // it as a Result rather than spawning it.
+      if (!isAbsolutePath(request.command)) {
+        return { ok: false, reason: `sandbox command must be an absolute path, got '${request.command}'` };
+      }
+      const workdir = mkdtempSync(join(tmpdir(), "agentic-sandbox-"));
+      try {
+        return await new Promise<SandboxToolResult>((resolve) => {
+          execFile(
+            request.command,
+            [...request.args],
+            {
+              cwd: workdir,
+              timeout: request.timeoutMs,
+              killSignal: "SIGKILL",
+              maxBuffer: MAX_OUTPUT_BYTES,
+              encoding: "utf8",
+              // stripped env: only PATH, so the tool cannot read worker secrets
+              env: { PATH: process.env["PATH"] ?? "/usr/local/bin:/usr/bin:/bin" },
+              windowsHide: true,
+            },
+            (error, stdout) => {
+              if (error !== null) {
+                resolve({ ok: false, reason: error.message });
+                return;
+              }
+              resolve({ ok: true, stdout });
+            },
+          );
+        });
+      } catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+      } finally {
+        rmSync(workdir, { recursive: true, force: true });
+      }
+    },
+  };
+}

agentic-organization/apps/workers/src/composition.ts

@@ -1,3 +1,4 @@
+import type { KeepAliveLane } from "../../../packages/keepalive/src/index.ts";
 import type { NatsJetStreamEventConsumer } from "../../../packages/messaging-nats/src/index.ts";
 import type { OrganizationWorkerHost } from "../../../packages/workers/src/index.ts";
 import {
@@ -11,6 +12,8 @@ export type WorkerRuntimePorts = {
   organizationWorkerHost: OrganizationWorkerHost;
   natsEventConsumer: NatsJetStreamEventConsumer;
   telemetrySink: WorkerRuntimeTelemetrySink;
+  /** optional so in-memory composition paths can omit the durable keep-alive lane */
+  keepAliveLane?: KeepAliveLane;
 };
 
 export type ComposeWorkerRuntimeInput = {
@@ -24,5 +27,6 @@ export function composeWorkerRuntime(input: ComposeWorkerRuntimeInput): WorkerRu
     organizationWorkerHost: input.ports.organizationWorkerHost,
     natsEventConsumer: input.ports.natsEventConsumer,
     telemetrySink: input.ports.telemetrySink,
+    ...(input.ports.keepAliveLane === undefined ? {} : { keepAliveLane: input.ports.keepAliveLane }),
   });
 }

agentic-organization/apps/workers/src/config.ts

@@ -2,6 +2,17 @@ import { WorkerRuntimeConfigError, WorkerRuntimeConfigErrorCode, type WorkerRunt
 
 const decimalIntegerPattern = /^[0-9]+$/;
 
+/**
+ * Default deadline (ms) past which the deterministic keep-alive engine treats
+ * the org as flatlining and raises a self-heal alert. Optional env override;
+ * defaulted so existing deployments do not need a new variable.
+ */
+export const WorkerKeepAliveConfigDefault = {
+  OrgHeartbeatDeadlineMs: 30_000,
+  /** cadence of the independent keep-alive loop (decoupled from the work cycle) */
+  LoopIntervalMs: 5_000,
+} as const;
+
 export const WorkerProcessEnvName = {
   AgenticOrgEnv: "AGENTIC_ORG_ENV",
   AgenticOrgId: "AGENTIC_ORG_ID",
@@ -14,6 +25,10 @@ export const WorkerProcessEnvName = {
   WorkerOutboxBatchSize: "WORKER_OUTBOX_BATCH_SIZE",
   WorkerReactionPlanBatchSize: "WORKER_REACTION_PLAN_BATCH_SIZE",
   WorkerReactionPlanLeaseMs: "WORKER_REACTION_PLAN_LEASE_MS",
+  WorkerKeepAliveOrgHeartbeatDeadlineMs: "WORKER_KEEP_ALIVE_ORG_HEARTBEAT_DEADLINE_MS",
+  /** when set, the agent's composer makes real model calls to this in-cluster endpoint */
+  LlmBaseUrl: "LLM_BASE_URL",
+  LlmModel: "LLM_MODEL",
 } as const;
 
 export type WorkerProcessEnvName = (typeof WorkerProcessEnvName)[keyof typeof WorkerProcessEnvName];
@@ -27,6 +42,11 @@ export type WorkerDurableRuntimeConfig = {
   workerOutboxBatchSize: number;
   workerReactionPlanBatchSize: number;
   workerReactionPlanLeaseMs: number;
+  workerKeepAliveOrgHeartbeatDeadlineMs: number;
+  /** in-cluster model endpoint for the agent's decision backend (optional) */
+  llmBaseUrl?: string;
+  /** model name to ask the endpoint for (optional; required when llmBaseUrl is set) */
+  llmModel?: string;
 };
 
 export type WorkerProcessConfig = WorkerRuntimeConfig & WorkerDurableRuntimeConfig;
@@ -66,9 +86,56 @@ export function parseWorkerRuntimeConfigFromEnv(env: WorkerProcessEnvironment):
       env[WorkerProcessEnvName.WorkerReactionPlanBatchSize],
     ),
     workerReactionPlanLeaseMs: parseWorkerReactionPlanLeaseMs(env[WorkerProcessEnvName.WorkerReactionPlanLeaseMs]),
+    workerKeepAliveOrgHeartbeatDeadlineMs: parseWorkerKeepAliveOrgHeartbeatDeadlineMs(
+      env[WorkerProcessEnvName.WorkerKeepAliveOrgHeartbeatDeadlineMs],
+    ),
+    // optional model backend — only set when both URL and model are provided
+    ...parseLlmConfig(env),
   };
 }
 
+function parseLlmConfig(env: WorkerProcessEnvironment): { llmBaseUrl?: string; llmModel?: string } {
+  const baseUrl = nonEmpty(env[WorkerProcessEnvName.LlmBaseUrl]);
+  const model = nonEmpty(env[WorkerProcessEnvName.LlmModel]);
+  if (baseUrl === undefined && model === undefined) {
+    // neither set → the deterministic composer is used (a valid, intended mode)
+    return {};
+  }
+  if (baseUrl === undefined || model === undefined) {
+    // exactly one set → a misconfiguration; fail loudly rather than silently
+    // dropping the model backend, which would be hard to diagnose in-cluster.
+    throw new WorkerRuntimeConfigError(WorkerRuntimeConfigErrorCode.PartialLlmConfig);
+  }
+  return { llmBaseUrl: baseUrl, llmModel: model };
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed !== undefined && trimmed.length > 0 ? trimmed : undefined;
+}
+
+function parseWorkerKeepAliveOrgHeartbeatDeadlineMs(value: string | undefined): number {
+  return parseOptionalPositiveDecimalInteger(
+    value,
+    WorkerKeepAliveConfigDefault.OrgHeartbeatDeadlineMs,
+    WorkerRuntimeConfigErrorCode.InvalidWorkerKeepAliveOrgHeartbeatDeadlineMs,
+  );
+}
+
+function parseOptionalPositiveDecimalInteger(
+  value: string | undefined,
+  defaultValue: number,
+  errorCode: WorkerRuntimeConfigErrorCode,
+): number {
+  const trimmedValue = value?.trim();
+
+  if (trimmedValue === undefined || trimmedValue.length === 0) {
+    return defaultValue;
+  }
+
+  return parsePositiveDecimalInteger(trimmedValue, errorCode);
+}
+
 function readRequiredEnvValue(
   env: WorkerProcessEnvironment,
   name: WorkerProcessEnvName,

agentic-organization/apps/workers/src/durable-composition.ts

@@ -16,9 +16,13 @@ import {
   type EventPayloadHashCalculator,
   type ReactionPlanActionExecutorPort,
 } from "../../../packages/runtime/src/index.ts";
+import { createKeepAliveLane, type KeepAliveLane } from "../../../packages/keepalive/src/index.ts";
 import { InboundEventConsumerName } from "../../../packages/state/src/index.ts";
 import {
+  createCockroachControlPlaneStateStore,
   createCockroachDurableStateAdapters,
+  createCockroachKeepAliveActionSink,
+  createCockroachKeepAliveSnapshotSource,
   type CockroachOrganizationSqlExecutor,
 } from "../../../packages/state-cockroach/src/index.ts";
 import {
@@ -49,6 +53,7 @@ export type DurableWorkerRuntimePorts = {
   organizationWorkerHost: OrganizationWorkerHost;
   natsEventConsumer: NatsJetStreamEventConsumer;
   telemetrySink: WorkerRuntimeTelemetrySink;
+  keepAliveLane: KeepAliveLane;
 };
 
 export type ComposeDurableWorkerRuntimePortsInput = {
@@ -92,6 +97,7 @@ export function composeDurableWorkerRuntimePorts(
     eventIngestionProcessor,
     deadLetterPublisher: input.durableAdapters.natsDeadLetterPublisher,
   });
+  const keepAliveLane = composeDurableKeepAliveLane(input);
 
   return {
     organizationWorkerHost: createOrganizationWorkerHost({
@@ -104,5 +110,34 @@ export function composeDurableWorkerRuntimePorts(
     }),
     natsEventConsumer,
     telemetrySink: input.durableAdapters.telemetrySink,
+    keepAliveLane,
   };
 }
+
+/**
+ * Compose the deterministic keep-alive control plane on durable Cockroach state:
+ * a control-plane store (org proof-of-life + alert log) -> snapshot source ->
+ * action sink -> lane. The lane ticks the org heartbeat every worker cycle and
+ * routes self-heal signals to durable state — the operator's #1 tenet, real.
+ */
+function composeDurableKeepAliveLane(input: ComposeDurableWorkerRuntimePortsInput): KeepAliveLane {
+  const controlPlaneStore = createCockroachControlPlaneStateStore({
+    executor: input.durableAdapters.cockroachExecutor,
+  });
+
+  return createKeepAliveLane({
+    source: createCockroachKeepAliveSnapshotSource({
+      store: controlPlaneStore,
+      organizationId: input.config.organizationId,
+      orgHeartbeatDeadlineMs: input.config.workerKeepAliveOrgHeartbeatDeadlineMs,
+      // the engine measures org age via the DB clock; this clock only feeds the
+      // (v1-empty) lease-expiry branch — derive epoch ms from the injected ISO now
+      clock: { now: () => Date.parse(input.runtimeUtilities.now()) },
+    }),
+    sink: createCockroachKeepAliveActionSink({
+      store: controlPlaneStore,
+      organizationId: input.config.organizationId,
+      generateAlertId: () => input.runtimeUtilities.createId("ctrl-alert"),
+    }),
+  });
+}

agentic-organization/apps/workers/src/index.ts

@@ -1,4 +1,5 @@
 export {
+  WorkerKeepAliveConfigDefault,
   WorkerProcessEnvName,
   parseWorkerRuntimeConfigFromEnv,
   type WorkerDurableRuntimeConfig,
@@ -93,6 +94,8 @@ export {
   WorkerRuntimeTelemetryEventName,
   createWorkerRuntime,
   type CreateWorkerRuntimeInput,
+  type WorkerKeepAliveLane,
+  type WorkerKeepAliveLaneResult,
   type WorkerRuntime,
   type WorkerRuntimeConfig,
   type WorkerRuntimeFailure,
@@ -161,3 +164,15 @@ export {
   createCockroachWorkItemStateHistoryMetadataMigration,
   type CockroachAnySqlStatement,
 } from "../../../packages/state-cockroach/src/index.ts";
+export {
+  WorkerMainDefault,
+  WorkerMainLogStream,
+  runMain,
+  type RunMainDependencies,
+  type WorkerMainClock,
+  type WorkerMainConstructors,
+  type WorkerMainDurablePorts,
+  type WorkerMainLogRecord,
+  type WorkerMainLogger,
+  type WorkerMainSignalRegistrar,
+} from "./main.ts";