@smthrs/control 0.0.0-stage → 1.0.0-rc.4

package/src/JevSessionChecker.ts

@@ -0,0 +1,127 @@
+/**
+ * Session activity judged by the host's existing evaluator.
+ * @since 1.0.0
+ */
+
+import * as Fault from "@smthrs/flow/Fault"
+import type * as Evaluator from "@smthrs/model/Evaluator"
+import { Effect, Schema } from "effect"
+import type { HealthChecker, ProbeReport } from "./Health.ts"
+
+/** The configured judge could not produce a usable observation.
+ * @category errors
+ * @since 1.0.0
+ */
+export class JevProbeError extends Schema.TaggedError<JevProbeError>()("JevProbeError", {
+  reason: Schema.Literals(["unconfigured", "http", "timeout", "unreachable", "malformed"]),
+  status: Schema.optional(Schema.Number)
+}) {}
+Fault.register(
+  "JevProbeError",
+  {
+    unconfigured: "policy",
+    http: "dependency",
+    timeout: "dependency",
+    unreachable: "dependency",
+    malformed: "dependency"
+  } satisfies Fault.Rows<JevProbeError["reason"]>,
+  "reason"
+)
+/** Maximum terminal evidence retained for one judgment.
+ * @category constants
+ * @since 1.0.0
+ */
+export const jevStateTailCharacters = 4 * 1024
+/** Subscription judgments have a bounded deadline.
+ * @category constants
+ * @since 1.0.0
+ */
+export const jevRequestTimeoutMs = 45_000
+/** Probe budget, longer than the request deadline.
+ * @category constants
+ * @since 1.0.0
+ */
+export const jevProbeTimeoutMs = 50_000
+/** Minimum confidence for an activity report.
+ * @category constants
+ * @since 1.0.0
+ */
+export const jevConfidenceFloor = 0.7
+/** The host evaluator and its bounded request deadline.
+ * @category models
+ * @since 1.0.0
+ */
+export interface JevSessionCheckerOptions {
+  readonly evaluator?: Evaluator.Evaluator | undefined
+  readonly timeoutMs?: number | undefined
+}
+const lifecycleReport: ProbeReport = { activity: "unknown", reason: "ok" }
+const activityCriteria = {
+  "working": "the agent is executing tools, editing files, or producing work",
+  "idle": "the agent finished and is producing nothing",
+  "needs-input": "the agent asked the person a question, requested approval or a credential, and is waiting"
+} as const
+
+const questions = {
+  activity: {
+    type: "choice",
+    instructions: "Read the tail of this agent session's output. What is the agent doing right now?",
+    criteria: activityCriteria
+  },
+  question: {
+    type: "boolean",
+    instructions: "Does the output end with the agent waiting for a person to answer?"
+  }
+} as const
+
+/** Uses the same judge as flow completion, with no independent auth path.
+ * @category constructors
+ * @since 1.0.0
+ */
+export const makeJevSessionChecker = (options: JevSessionCheckerOptions = {}): HealthChecker => ({
+  id: "jev.session",
+  defaults: { timeoutMs: jevProbeTimeoutMs, ttlMs: 60_000 },
+  probe: (context) =>
+    Effect.gen(function*() {
+      const session = context.session
+      const tail = session?.outputTail
+      if (session === undefined || !session.alive || tail === undefined || tail === "") return lifecycleReport
+      if (options.evaluator === undefined) return yield* Effect.fail(new JevProbeError({ reason: "unconfigured" }))
+      const result = yield* options.evaluator.evaluate({
+        state: { alive: session.alive, exitCode: session.exitCode, outputTail: tail.slice(-jevStateTailCharacters) },
+        questions
+      }).pipe(
+        Effect.mapError((error) =>
+          new JevProbeError({
+            reason: error.code === "timeout"
+              ? "timeout"
+              : error.code === "refused"
+              ? "http"
+              : error.code === "unreachable"
+              ? "unreachable"
+              : "malformed",
+            ...(error.status === undefined ? {} : { status: error.status })
+          })
+        ),
+        Effect.timeoutOrElse({
+          duration: options.timeoutMs ?? jevRequestTimeoutMs,
+          orElse: () => Effect.fail(new JevProbeError({ reason: "timeout" }))
+        })
+      )
+      const answer = result.answers.activity
+      if (answer?.type !== "choice" || !Object.hasOwn(activityCriteria, answer.choice)) {
+        return yield* Effect.fail(new JevProbeError({ reason: "malformed" }))
+      }
+      const confidence = result.confidence?.activity ?? answer.probabilities?.[answer.choice] ?? 0
+      if (!Number.isFinite(confidence) || confidence < jevConfidenceFloor || confidence > 1) return lifecycleReport
+      const choice = answer.choice as keyof typeof activityCriteria
+      return choice === "needs-input"
+        ? { activity: choice, reason: "prompt-detected" }
+        : { activity: choice, reason: "ok" }
+    })
+})
+/** Registered but unconfigured until a host supplies its evaluator.
+ * @category constants
+ * @since 1.0.0
+ */
+export const jevSessionChecker: HealthChecker = makeJevSessionChecker()

package/src/Lineage.ts

@@ -0,0 +1,203 @@
+/**
+ * Run ancestry as the control plane reads it.
+ *
+ * A run's ancestry is recorded by whoever created the run, in four different
+ * places: the run row's `parent_run_id`, `lineage_id`, and `round_ordinal`
+ * columns; the `flows_run_parents` edge a spawn writes; the `created` and
+ * `handed-off` run decisions the engine journals; and the `fork-created`
+ * marker time travel writes on a forked child. This module owns the one
+ * vocabulary they all project onto — {@link Origin} — and the pure functions
+ * that do the projecting, so the durable runtime and the watch stream cannot
+ * disagree about what a run's ancestry means.
+ *
+ * The two event types named here are produced by `@smthrs/engine-store` and
+ * `@smthrs/time-travel`. They are named as strings rather than imported
+ * because the control plane reads journals, not engines: a control plane that
+ * depended on the engine could not project a journal written by a different
+ * one.
+ *
+ * @since 0.1.0
+ */
+
+import { Schema } from "effect"
+import type { ControlEvent } from "./ControlSchema.ts"
+
+/**
+ * How a run came to exist.
+ *
+ * The three values are the lineage-edge kinds of
+ * `docs/pages/concepts/time-travel.md`: a `child` is a run its parent spawned, a
+ * `fork` is a run branched off a parent frame, and a `continuation` is a later
+ * round of one trampoline lineage. A rewind is deliberately absent — it
+ * truncates a run in place and creates none — and a run with no ancestor has
+ * no origin at all.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const Origin = Schema.Literals(["child", "fork", "continuation"])
+
+/**
+ * How a run came to exist.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Origin = typeof Origin.Type
+
+/**
+ * The ancestry facts an origin is decided from.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Ancestry {
+  readonly parentRunId?: string | undefined
+  readonly roundOrdinal?: number | undefined
+  /** Whether a `fork-created` marker names this run. */
+  readonly forked?: boolean | undefined
+}
+
+/**
+ * The journal event type carrying an engine run decision.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const runDecisionEventType = "flows.engine.run-decision"
+
+/**
+ * The journal event type time travel writes on a forked child.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const forkCreatedEventType = "flows.time-travel.fork-created"
+
+/**
+ * The kind `watch` reports a derived ancestry delta under.
+ *
+ * @category constants
+ * @since 0.1.0
+ */
+export const lineageEventType = "control.run.lineage"
+
+/**
+ * Decides how a run came to exist from its ancestry facts.
+ *
+ * A fork wins over a plain child because a fork records `parent_run_id` too:
+ * without the marker every fork would be reported as an ordinary child.
+ *
+ * @param ancestry the run's recorded ancestry
+ * @category projections
+ * @since 0.1.0
+ */
+export const originOf = (ancestry: Ancestry): Origin | undefined => {
+  if (ancestry.forked === true) return "fork"
+  if (ancestry.roundOrdinal !== undefined && ancestry.roundOrdinal > 0) return "continuation"
+  return ancestry.parentRunId === undefined ? undefined : "child"
+}
+
+const record = (value: unknown): Readonly<Record<string, unknown>> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? value as Readonly<Record<string, unknown>>
+    : undefined
+
+const text = (value: unknown): string | undefined => typeof value === "string" && value.length > 0 ? value : undefined
+
+const ordinal = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined
+
+/**
+ * Derives the ancestry edge one journal entry discloses, if it discloses one.
+ *
+ * Three entries do, and each names a different pair:
+ *
+ * | Entry | Ancestor | Descendant |
+ * | --- | --- | --- |
+ * | `created` naming `parentExecutionId`, at round 0 or with no round | the spawning run | the entry's run |
+ * | `handed-off` naming `nextExecutionId` | the entry's run | the next round |
+ * | `fork-created` | the forked-from run | the entry's run |
+ *
+ * The handoff is what carries a trampoline, and a continuation round's own
+ * `created` decision is deliberately skipped. The engine journals BOTH in one
+ * transaction: `RunDriver` creates the next round with
+ * `{decision: "created", lineageId, roundOrdinal, parentExecutionId}` and then
+ * records `{decision: "handed-off", nextExecutionId}` on the round that
+ * finished. Both name the same pair, so deriving from both would report one
+ * run as a `child` of its predecessor on one entry and a `continuation` of it
+ * on the other. The handoff is the one kept, because it reaches a consumer
+ * watching the run that hands off — which is the run an operator is already
+ * following when a trampoline advances.
+ *
+ * A `created` decision at round 0, or with no round at all, is an ordinary
+ * spawn and derives a `child` edge.
+ *
+ * Everything else derives nothing. This is a projection over entries the
+ * control plane did not write, so an entry it does not recognize is not an
+ * error.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export const derive = (event: ControlEvent): ControlEvent | undefined => {
+  if (event.runId === undefined) return undefined
+  const payload = record(event.payload)
+  if (payload === undefined) return undefined
+  const edge = event.kind === forkCreatedEventType
+    ? { runId: event.runId, parentRunId: text(payload["parentRunId"]), forked: true }
+    : event.kind !== runDecisionEventType
+    ? undefined
+    : payload["decision"] === "created"
+    // A continuation round's `created` names its predecessor too. The handoff
+    // the previous round journals in the SAME transaction already discloses
+    // that edge, so deriving here as well would contradict it.
+    ? (ordinal(payload["roundOrdinal"]) ?? 0) > 0
+      ? undefined
+      : { runId: event.runId, parentRunId: text(payload["parentExecutionId"]), forked: false }
+    : payload["decision"] === "handed-off"
+    ? {
+      runId: text(payload["nextExecutionId"]),
+      parentRunId: event.runId,
+      forked: false,
+      lineageId: text(payload["lineageId"]),
+      roundOrdinal: ordinal(payload["roundOrdinal"])
+    }
+    : undefined
+  if (edge === undefined || edge.runId === undefined || edge.parentRunId === undefined) return undefined
+  const lineageId = "lineageId" in edge ? edge.lineageId : undefined
+  const roundOrdinal = "roundOrdinal" in edge ? edge.roundOrdinal : undefined
+  const origin = originOf({
+    parentRunId: edge.parentRunId,
+    ...(roundOrdinal === undefined ? {} : { roundOrdinal }),
+    forked: edge.forked
+  })
+  return {
+    sequence: event.sequence,
+    kind: lineageEventType,
+    runId: event.runId,
+    occurredAt: event.occurredAt,
+    payload: {
+      runId: edge.runId,
+      parentRunId: edge.parentRunId,
+      ...(lineageId === undefined ? {} : { lineageId }),
+      ...(roundOrdinal === undefined ? {} : { roundOrdinal }),
+      /* v8 ignore next -- `originOf` answers nothing only without a parent, and the guard above already refused an edge with no parent */
+      ...(origin === undefined ? {} : { origin })
+    }
+  }
+}
+
+/**
+ * Expands one projected entry into itself plus any ancestry delta it
+ * discloses.
+ *
+ * @param event the projected journal entry
+ * @category projections
+ * @since 0.1.0
+ */
+export const expand = (event: ControlEvent): ReadonlyArray<ControlEvent> => {
+  const derived = derive(event)
+  return derived === undefined ? [event] : [event, derived]
+}

package/src/Migrations.ts

@@ -0,0 +1,56 @@
+/**
+ * Control-plane and credential schema migrations.
+ *
+ * This package reserves the migration block immediately after time travel.
+ * Hosts compose this set with the journal and run-store sets before opening a
+ * shared control database.
+ *
+ * @since 0.1.0
+ */
+
+import * as DatabaseMigrations from "@smthrs/database/Migrations"
+import * as Layer from "effect/Layer"
+import { initial } from "./migrations/0001_control_tables.ts"
+import { runKeys } from "./migrations/0002_run_keys.ts"
+import { signalCommands } from "./migrations/0003_signal_commands.ts"
+import { approvalDecisions } from "./migrations/0004_approval_decisions.ts"
+import { signalPrincipals } from "./migrations/0005_signal_principals.ts"
+import { runPrincipals } from "./migrations/0006_run_principals.ts"
+import { resumeConsent } from "./migrations/0007_resume_consent.ts"
+
+/**
+ * The control package's namespaced migration set.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const set: DatabaseMigrations.MigrationSet = {
+  namespace: "control",
+  idOffset: DatabaseMigrations.idBlock * 6,
+  migrations: {
+    "0001_control_tables": initial,
+    "0002_run_keys": runKeys,
+    "0003_signal_commands": signalCommands,
+    "0004_approval_decisions": approvalDecisions,
+    "0005_signal_principals": signalPrincipals,
+    "0006_run_principals": runPrincipals,
+    "0007_resume_consent": resumeConsent
+  }
+}
+
+/**
+ * Creates every durable control-plane and credential table.
+ *
+ * @category migrations
+ * @since 0.1.0
+ */
+export const run = DatabaseMigrations.run([set])
+
+/**
+ * Layer that runs control migrations before exposing the database to control
+ * services.
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export const layer = Layer.effectDiscard(run)