@sealant/api-contracts-next 0.0.0-next.0 → 0.39.0-next.682

package/dist/core-api/runs.js

@@ -0,0 +1,284 @@
+/**
+ * Run + execution-record wire contracts.
+ *
+ * A `run` is one harness execution; it owns the execution record (the telemetry log). These
+ * endpoints are the network face of the run-detail read path (RunRepo -> THIS contract -> apps/api ->
+ * SDK): register a run, read its metadata, list runs, update its terminal status, and read its
+ * record — timeline, byte-exact scrollback, and the provenance-honest loss report.
+ *
+ * Wire note: per-runtime monotonic uint64 sequences are carried as DECIMAL STRINGS (not JSON numbers)
+ * so values past 2^53 survive; the SDK and API layer convert to/from `bigint`.
+ */
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+import { BudgetExceededError } from "./budgets.js";
+const NonEmptyString = Schema.String.check(Schema.isNonEmpty(), Schema.isTrimmed());
+export const runStatusSchema = Schema.Literals([
+    "queued",
+    "running",
+    "completed",
+    "failed",
+    "cancelled",
+]);
+export const runModeSchema = Schema.Literals(["one-shot", "interactive"]);
+// "pty" is the interactive stream: PTY output as recorded from sessions (StreamKind 5).
+export const ioStreamSchema = Schema.Literals(["stdout", "stderr", "pty"]);
+// ---------------------------------------------------------------------------------------------
+// Run resource
+// ---------------------------------------------------------------------------------------------
+/** The one-shot harness invocation the control plane execs in the workspace. */
+export const runCommandSchema = Schema.Struct({
+    executable: NonEmptyString,
+    args: Schema.Array(Schema.String),
+    cwd: Schema.optional(NonEmptyString),
+});
+export const runSchema = Schema.Struct({
+    runId: NonEmptyString,
+    workspaceId: NonEmptyString,
+    attemptId: Schema.optional(NonEmptyString),
+    ownerUserId: NonEmptyString,
+    harnessId: NonEmptyString,
+    mode: runModeSchema,
+    status: runStatusSchema,
+    prompt: Schema.optional(Schema.String),
+    /** The resolved invocation the control plane executed (server-side runs) — self-describing. */
+    command: Schema.optional(runCommandSchema),
+    /** Opaque caller correlation bag, echoed verbatim (no platform semantics). */
+    metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+    exitCode: Schema.optional(Schema.Number),
+    errorMessage: Schema.optional(Schema.String),
+    startedAt: Schema.optional(Schema.String),
+    finishedAt: Schema.optional(Schema.String),
+    createdAt: Schema.String,
+    updatedAt: Schema.String,
+});
+export const runFileChangeSchema = Schema.Struct({
+    path: NonEmptyString,
+    change: Schema.Literals(["added", "modified", "deleted", "renamed"]),
+    oldPath: Schema.optional(NonEmptyString),
+});
+export const createRunRequestSchema = Schema.Struct({
+    workspaceId: NonEmptyString,
+    harnessId: NonEmptyString,
+    ownerUserId: NonEmptyString,
+    mode: Schema.optional(runModeSchema),
+    prompt: Schema.optional(Schema.String),
+    attemptId: Schema.optional(NonEmptyString),
+    // When present, the control plane EXECUTES the run SERVER-SIDE: the worker docker-execs this command
+    // in the workspace, ingests telemetry, and captures the diff. When absent AND `prompt` is present
+    // for a built-in harness, the control plane CONSTRUCTS the command itself (server-side invoke
+    // knowledge) — which is what lets a re-fetched workspace handle start a harness. An explicit
+    // command always wins (the escape hatch for custom harnesses). Absent both, the run row is
+    // created but not executed (the legacy host-local path where the caller runs it itself).
+    command: Schema.optional(runCommandSchema),
+    /** Opaque caller correlation bag ({ projectId, sessionId, ... }): stored + echoed, no semantics. */
+    metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+});
+export const updateRunRequestSchema = Schema.Struct({
+    /** The run's owner. Required by the control plane: an update that names no owner finds no run. */
+    ownerUserId: Schema.optional(NonEmptyString),
+    status: Schema.optional(runStatusSchema),
+    exitCode: Schema.optional(Schema.Number),
+    errorMessage: Schema.optional(Schema.String),
+    // Terminal-transition capture: callers that observed the run's file changes (e.g. the SSH gateway
+    // closing an interactive session) persist them alongside the status flip.
+    diff: Schema.optional(Schema.String),
+    changedFiles: Schema.optional(Schema.Array(runFileChangeSchema)),
+    /** The caller read the run's changes and the reading failed: nothing is known of them. */
+    changesReadFailed: Schema.optional(Schema.Boolean),
+});
+export const listRunsQuerySchema = Schema.Struct({
+    workspaceId: Schema.optional(NonEmptyString),
+    ownerUserId: Schema.optional(NonEmptyString),
+    status: Schema.optional(runStatusSchema),
+    limit: Schema.optional(NonEmptyString),
+});
+export const listRunsResponseSchema = Schema.Struct({ items: Schema.Array(runSchema) });
+// ---------------------------------------------------------------------------------------------
+// Execution record — timeline
+// ---------------------------------------------------------------------------------------------
+export const timelineEntrySchema = Schema.Struct({
+    eventId: NonEmptyString,
+    sequence: NonEmptyString, // decimal-string uint64
+    kind: NonEmptyString,
+    occurredAt: NonEmptyString, // decimal-string monotonic timestamp
+    summary: Schema.String,
+    ref: Schema.optional(Schema.Unknown),
+    /** Correlation id of the producing process (attribution key for record views). */
+    processId: Schema.optional(NonEmptyString),
+    /** Numeric CaptureMethod / Confidence enums — how the fact was captured, per envelope. */
+    captureMethod: Schema.Number,
+    confidence: Schema.Number,
+});
+/**
+ * Owner scoping on reads: the run must belong to `ownerUserId` (uniform 404 otherwise). The field
+ * stays optional on the wire for older callers, but the control plane requires it: a read that
+ * names no owner finds no run.
+ */
+export const runOwnerQuerySchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+});
+export const getRunTimelineQuerySchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+    fromSequence: Schema.optional(NonEmptyString),
+    toSequence: Schema.optional(NonEmptyString),
+    limit: Schema.optional(NonEmptyString),
+    /**
+     * Comma-separated payload cases (e.g. `processStarted,processExited,fileChange`). Filters the
+     * timeline to those event kinds server-side — the read path for record views that must not pay
+     * for the ioChunk-dominated full log.
+     */
+    kinds: Schema.optional(NonEmptyString),
+});
+export const runTimelineResponseSchema = Schema.Struct({
+    items: Schema.Array(timelineEntrySchema),
+});
+// ---------------------------------------------------------------------------------------------
+// Execution record — single raw event (the full envelope, provenance included)
+// ---------------------------------------------------------------------------------------------
+/**
+ * One stored EventEnvelope, verbatim: correlation ids, both clocks, capture provenance, and the
+ * jsonb payload (bigints stringified at ingest). This is the drill-down read behind a timeline
+ * entry — the timeline carries the summary + ref, this carries the whole record.
+ */
+export const runEventSchema = Schema.Struct({
+    eventId: NonEmptyString,
+    runId: NonEmptyString,
+    runtimeId: NonEmptyString,
+    executionId: Schema.optional(NonEmptyString),
+    sessionId: Schema.optional(NonEmptyString),
+    processId: Schema.optional(NonEmptyString),
+    requestId: Schema.optional(NonEmptyString),
+    schemaVersion: Schema.Number,
+    sequence: NonEmptyString, // decimal-string uint64
+    observedAt: NonEmptyString, // decimal-string int64 wall clock
+    monotonicTimestamp: NonEmptyString, // decimal-string uint64 ordering clock
+    captureMethod: Schema.Number,
+    confidence: Schema.Number,
+    payloadCase: NonEmptyString,
+    payload: Schema.Unknown,
+    ingestedAt: Schema.String,
+});
+// ---------------------------------------------------------------------------------------------
+// Execution record — scrollback (byte-exact terminal output)
+// ---------------------------------------------------------------------------------------------
+export const getRunScrollbackQuerySchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+    processId: NonEmptyString,
+    stream: ioStreamSchema,
+    atSequence: Schema.optional(NonEmptyString),
+    /** Inclusive lower sequence bound — with `atSequence` this selects a sequence RANGE. */
+    fromSequence: Schema.optional(NonEmptyString),
+    /** Maximum chunks to reconstruct (server default 5000). */
+    limit: Schema.optional(NonEmptyString),
+});
+export const runScrollbackResponseSchema = Schema.Struct({
+    processId: NonEmptyString,
+    stream: ioStreamSchema,
+    byteCount: Schema.Number,
+    /** Base64-encoded reconstructed bytes (byte-exact as recorded; redaction happens upstream). */
+    contentBase64: Schema.String,
+});
+// ---------------------------------------------------------------------------------------------
+// Execution record — loss report (provenance honesty)
+// ---------------------------------------------------------------------------------------------
+export const lossSpanSchema = Schema.Struct({
+    kind: Schema.Literals(["dropped_event", "sequence_gap", "watch_overflow", "early_close"]),
+    fromSequence: Schema.optional(NonEmptyString),
+    toSequence: Schema.optional(NonEmptyString),
+    droppedCount: Schema.optional(NonEmptyString),
+    detectedVia: Schema.Literals(["marker", "gap"]),
+    reason: Schema.optional(Schema.String),
+});
+export const runLossReportSchema = Schema.Struct({
+    runId: NonEmptyString,
+    droppedEventCount: NonEmptyString, // decimal-string uint64
+    sequenceGapCount: Schema.Number,
+    watchOverflowCount: Schema.Number,
+    earlyClose: Schema.Boolean,
+    spans: Schema.Array(lossSpanSchema),
+});
+// ---------------------------------------------------------------------------------------------
+// Run changes — the file diff the run produced (captured server-side)
+// ---------------------------------------------------------------------------------------------
+export const runChangesResponseSchema = Schema.Struct({
+    files: Schema.Array(runFileChangeSchema),
+    /** Unified diff of everything that changed (empty until the run has produced changes). */
+    diff: Schema.String,
+    /**
+     * Whether the run's changes were read. `false`: they were not (the run has not ended, no
+     * reading ran for it, or the reading failed), and the empty `files` and `diff` say nothing
+     * about what changed. Absent from a control plane older than the field: read as `true`.
+     */
+    available: Schema.optional(Schema.Boolean),
+    /** Why the changes are not available, when `available` is `false`. */
+    unavailableReason: Schema.optional(Schema.String),
+});
+// ---------------------------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------------------------
+export class RunBadRequestError extends Schema.TaggedErrorClass()("RunBadRequestError", { message: Schema.String }, { httpApiStatus: 400 }) {
+}
+export class RunNotFoundError extends Schema.TaggedErrorClass()("RunNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+export class RunInternalServerError extends Schema.TaggedErrorClass()("RunInternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
+}
+const runIdParams = Schema.Struct({ runId: NonEmptyString });
+const runEventParams = Schema.Struct({ runId: NonEmptyString, sequence: NonEmptyString });
+// ---------------------------------------------------------------------------------------------
+// Group
+// ---------------------------------------------------------------------------------------------
+export const RunsGroup = HttpApiGroup.make("runs")
+    .add(HttpApiEndpoint.post("createRun", "/", {
+    payload: createRunRequestSchema,
+    success: runSchema.pipe(HttpApiSchema.status(201)),
+    error: [BudgetExceededError, RunBadRequestError, RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("listRuns", "/", {
+    query: listRunsQuerySchema,
+    success: listRunsResponseSchema,
+    error: [RunBadRequestError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getRun", "/:runId", {
+    params: runIdParams,
+    query: runOwnerQuerySchema,
+    success: runSchema,
+    error: [RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.patch("updateRun", "/:runId", {
+    params: runIdParams,
+    payload: updateRunRequestSchema,
+    success: runSchema,
+    error: [RunBadRequestError, RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getRunTimeline", "/:runId/timeline", {
+    params: runIdParams,
+    query: getRunTimelineQuerySchema,
+    success: runTimelineResponseSchema,
+    error: [RunBadRequestError, RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getRunEvent", "/:runId/events/:sequence", {
+    params: runEventParams,
+    query: runOwnerQuerySchema,
+    success: runEventSchema,
+    error: [RunBadRequestError, RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getRunScrollback", "/:runId/scrollback", {
+    params: runIdParams,
+    query: getRunScrollbackQuerySchema,
+    success: runScrollbackResponseSchema,
+    error: [RunBadRequestError, RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getRunLoss", "/:runId/loss", {
+    params: runIdParams,
+    query: runOwnerQuerySchema,
+    success: runLossReportSchema,
+    error: [RunNotFoundError, RunInternalServerError],
+}))
+    .add(HttpApiEndpoint.get("getRunChanges", "/:runId/changes", {
+    params: runIdParams,
+    query: runOwnerQuerySchema,
+    success: runChangesResponseSchema,
+    error: [RunNotFoundError, RunInternalServerError],
+}))
+    .annotate(OpenApi.Description, "Runs (harness executions) and their execution record.");