From bde737f4d52eea5889076535f2a5865c5ce69a98 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Tue, 3 Nov 2026 10:32:50 -0600 Subject: [PATCH] feat(server): add experimental job list endpoint (#60698) --- packages/client/script/generate.ts | 2 + packages/client/src/effect/api/api.ts | 13 + .../client/src/effect/generated/client.ts | 18 ++ .../client/src/promise/generated/client.ts | 21 ++ .../client/src/promise/generated/types.ts | 49 ++++ packages/client/test/promise.test.ts | 2 + packages/core/src/job.ts | 29 +- packages/core/src/job/list.ts | 126 +++++++++ packages/core/src/job/recovery.ts | 26 ++ packages/core/src/session/background.ts | 48 +++- packages/protocol/openapi.json | 250 ++++++++++++++++++ packages/protocol/src/groups/experimental.ts | 8 +- packages/protocol/src/groups/job.ts | 45 ++++ packages/schema/src/job.ts | 60 +++++ packages/schema/test/contract-hygiene.test.ts | 8 + packages/server/src/handlers/job.ts | 26 ++ .../server/src/handlers/persistent-pty.ts | 3 + packages/server/test/job.test.ts | 186 +++++++++++++ 18 files changed, 892 insertions(+), 28 deletions(-) create mode 100644 packages/core/src/job/list.ts create mode 100644 packages/core/src/job/recovery.ts create mode 100644 packages/protocol/src/groups/job.ts create mode 100644 packages/schema/src/job.ts create mode 100644 packages/server/src/handlers/job.ts create mode 100644 packages/server/test/job.test.ts diff --git a/packages/client/script/generate.ts b/packages/client/script/generate.ts index 2aa8604988c..4d262aadfd6 100644 --- a/packages/client/script/generate.ts +++ b/packages/client/script/generate.ts @@ -21,6 +21,7 @@ import { Generate } from "@opencode/schema/generate" import { Instruction } from "@opencode/schema/instruction" import { InstructionEntry } from "@opencode/schema/instruction-entry" import { Integration } from "@opencode/schema/integration" +import { Job } from "@opencode/schema/job" import { Location } from "@opencode/schema/location" import { Mcp } from "@opencode/schema/mcp" import { Model } from "@opencode/schema/model" @@ -79,6 +80,7 @@ const effectTypeReferences = [ ...namespaceTypes("Instruction", "@opencode/schema/instruction", Instruction), ...namespaceTypes("InstructionEntry", "@opencode/schema/instruction-entry", InstructionEntry), ...namespaceTypes("Integration", "@opencode/schema/integration", Integration), + ...namespaceTypes("Job", "@opencode/schema/job", Job), typeReference("Location.PublicRef", "@opencode/schema/location", Location.PublicRef), typeReference("Location.PublicInfo", "@opencode/schema/location", Location.PublicInfo), ...namespaceTypes("Mcp", "@opencode/schema/mcp", Mcp), diff --git a/packages/client/src/effect/api/api.ts b/packages/client/src/effect/api/api.ts index 9998568b229..80e16030a67 100644 --- a/packages/client/src/effect/api/api.ts +++ b/packages/client/src/effect/api/api.ts @@ -39,6 +39,7 @@ import type { OpenCodeEvent } from "@opencode/protocol/groups/event" import type { Pty } from "@opencode/schema/pty" import type { Schedule } from "@opencode/schema/schedule" import type { Artifact } from "@opencode/schema/artifact" +import type { Job } from "@opencode/schema/job" import type { Reference } from "@opencode/schema/reference" import type { Worktree } from "@opencode/schema/worktree" import type { Vcs } from "@opencode/schema/vcs" @@ -2492,6 +2493,17 @@ export type ExperimentalArtifactsDeleteOperation = ( input: ExperimentalArtifactsDeleteInput, ) => Effect.Effect +export type ExperimentalJobListInput = { + readonly sessionID?: Session.ID | undefined + readonly kind?: Job.Kind | undefined + readonly status?: Job.Status | undefined + readonly descendants?: boolean | undefined +} +export type ExperimentalJobListOutput = ReadonlyArray +export type ExperimentalJobListOperation = ( + input?: ExperimentalJobListInput, +) => Effect.Effect + export interface ExperimentalApi { readonly persistentPty: { readonly read: ExperimentalPersistentPtyReadOperation @@ -2521,6 +2533,7 @@ export interface ExperimentalApi { readonly update: ExperimentalArtifactsUpdateOperation readonly delete: ExperimentalArtifactsDeleteOperation } + readonly job: { readonly list: ExperimentalJobListOperation } } export type ShellListInput = { readonly location?: { readonly directory?: string | undefined } | undefined } diff --git a/packages/client/src/effect/generated/client.ts b/packages/client/src/effect/generated/client.ts index e837128e444..2631efc70d2 100644 --- a/packages/client/src/effect/generated/client.ts +++ b/packages/client/src/effect/generated/client.ts @@ -267,6 +267,8 @@ import type { ExperimentalArtifactsUpdateOutput, ExperimentalArtifactsDeleteInput, ExperimentalArtifactsDeleteOutput, + ExperimentalJobListInput, + ExperimentalJobListOutput, ShellListInput, ShellListOutput, ShellCreateInput, @@ -1698,6 +1700,21 @@ const EndpointExperimentalArtifactsDelete = }).pipe(Effect.mapError(mapClientError)), ) +const EndpointExperimentalJobList = (raw: RawClient["server.experimental"]) => (input?: ExperimentalJobListInput) => + preserveEffect()( + raw["job.list"]({ + query: { + sessionID: input?.["sessionID"], + kind: input?.["kind"], + status: input?.["status"], + descendants: input?.["descendants"], + }, + }).pipe( + Effect.mapError(mapClientError), + Effect.map((value) => value.data), + ), + ) + const adaptGroupExperimental = (raw: RawClient["server.experimental"]) => ({ persistentPty: { read: EndpointExperimentalPersistentPtyRead(raw), @@ -1727,6 +1744,7 @@ const adaptGroupExperimental = (raw: RawClient["server.experimental"]) => ({ update: EndpointExperimentalArtifactsUpdate(raw), delete: EndpointExperimentalArtifactsDelete(raw), }, + job: { list: EndpointExperimentalJobList(raw) }, }) const EndpointShellList = (raw: RawClient["server.shell"]) => (input?: ShellListInput) => diff --git a/packages/client/src/promise/generated/client.ts b/packages/client/src/promise/generated/client.ts index 3777b5848a1..7cda146ec9f 100644 --- a/packages/client/src/promise/generated/client.ts +++ b/packages/client/src/promise/generated/client.ts @@ -269,6 +269,8 @@ import type { ExperimentalArtifactsDeleteOutput, ExperimentalArtifactsViewInput, ExperimentalArtifactsViewOutput, + ExperimentalJobListInput, + ExperimentalJobListOutput, ShellListInput, ShellListOutput, ShellCreateInput, @@ -1681,6 +1683,25 @@ export function make(options: ClientOptions) { requestOptions, ), }, + job: { + list: (input?: ExperimentalJobListInput, requestOptions?: RequestOptions) => + request<{ readonly data: ExperimentalJobListOutput }>( + { + method: "GET", + path: `/api/experimental/job`, + query: { + sessionID: input?.["sessionID"], + kind: input?.["kind"], + status: input?.["status"], + descendants: input?.["descendants"], + }, + successStatus: 200, + declaredStatuses: [400, 401, 404], + empty: false, + }, + requestOptions, + ).then((value) => value.data), + }, migration: { v1: { status: (requestOptions?: RequestOptions) => diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index 7650139b5e7..746a64c51ab 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -345,6 +345,10 @@ export type ArtifactID = string export type ArtifactTime = { created: number; updated: number } +export type JobStatus = "running" | "completed" | "error" | "cancelled" + +export type JobTime = { started: number; completed?: number } + export type ReferenceGitSource = { type: "git"; repository: string; branch?: string } export type VcsBranch = { current?: string; default?: string } @@ -936,6 +940,40 @@ export type ArtifactInfo = { time: ArtifactTime } +export type JobShell = { + kind: "shell" + id: string + sessionID: SessionID + status: JobStatus + title?: string + time: JobTime + shellID: string + command: string +} + +export type JobSubagent = { + kind: "subagent" + id: string + sessionID: SessionID + status: JobStatus + title?: string + time: JobTime + childSessionID: SessionID + agent: string + description: string +} + +export type JobImage = { + kind: "image" + id: string + sessionID: SessionID + status: JobStatus + title?: string + time: JobTime + path: string + model: string +} + export type VcsInfo = { provider?: string; branch: VcsBranch } export type WebSearchProvider = { id: WebSearchID; name: string } @@ -2193,6 +2231,8 @@ export type ScheduleWhen = ScheduleWhenIn | ScheduleWhenAt | ScheduleWhenEvery | export type ArtifactContent = { info: ArtifactInfo; files: { [x: string]: string } } +export type JobInfo = JobShell | JobSubagent | JobImage + export type SessionInboxMove = { id: SessionMessageID sessionID: SessionID @@ -4645,6 +4685,15 @@ export type ExperimentalArtifactsViewInput = { export type ExperimentalArtifactsViewOutput = globalThis.Uint8Array +export type ExperimentalJobListInput = { + readonly sessionID?: string | undefined + readonly kind?: ("shell" | "subagent" | "image") | undefined + readonly status?: ("running" | "completed" | "error" | "cancelled") | undefined + readonly descendants?: boolean | undefined +} + +export type ExperimentalJobListOutput = { data: Array }["data"] + export type ShellListInput = { readonly location?: { readonly directory?: string | undefined } | undefined } export type ShellListOutput = { location: LocationPublicRef; data: Array } diff --git a/packages/client/test/promise.test.ts b/packages/client/test/promise.test.ts index a3ad7ec2593..bc4cd4ec824 100644 --- a/packages/client/test/promise.test.ts +++ b/packages/client/test/promise.test.ts @@ -63,10 +63,12 @@ test("exposes every standard HTTP API group", () => { "media", "schedule", "artifacts", + "job", "migration", "usage", "config", ]) + expect(Object.keys(client.experimental.job)).toEqual(["list"]) expect(Object.keys(client.experimental.session)).toEqual([ "stats", "import", diff --git a/packages/core/src/job.ts b/packages/core/src/job.ts index 764b8eb7422..fd5d391b396 100644 --- a/packages/core/src/job.ts +++ b/packages/core/src/job.ts @@ -4,41 +4,24 @@ import { asc, eq, or } from "drizzle-orm" import { Array, Cause, Clock, Context, Deferred, Effect, Exit, Layer, Schema, Scope, SynchronizedRef } from "effect" import { makeGlobalNode } from "@opencode/util/effect/app-node" import { Database } from "./database/database.js" +import { JobList } from "./job/list.js" +import { type Recovery, RecoverySchema } from "./job/recovery.js" import { JobTable } from "./job/sql.js" import { SessionMessage } from "./session/message.js" import { SessionSchema } from "./session/schema.js" +export type { Recovery } + const Background = Schema.Struct({ id: Schema.String, notificationID: SessionMessage.ID, - recovery: Schema.Union([ - Schema.Struct({ - kind: Schema.Literal("shell"), - sessionID: SessionSchema.ID, - shellID: Schema.String, - command: Schema.String, - }), - Schema.Struct({ - kind: Schema.Literal("subagent"), - parentSessionID: SessionSchema.ID, - childSessionID: SessionSchema.ID, - agent: Schema.String, - description: Schema.String, - }), - Schema.Struct({ - kind: Schema.Literal("image"), - sessionID: SessionSchema.ID, - path: Schema.String, - model: Schema.String, - }), - ]), + recovery: RecoverySchema, status: Schema.Literals(["running", "completed", "error", "cancelled"]), output: Schema.optionalKey(Schema.String), error: Schema.optionalKey(Schema.String), }) export type Background = typeof Background.Type -export type Recovery = Background["recovery"] export type Status = Background["status"] const decodeBackground = Schema.decodeUnknownResult(Background) @@ -142,6 +125,7 @@ export interface Interface { readonly cancelSession: (sessionID: SessionSchema.ID) => Effect.Effect readonly pendingBackground: Effect.Effect readonly runningBackground: Effect.Effect + readonly backgroundJobs: Effect.Effect readonly completeBackground: (notificationID: SessionMessage.ID) => Effect.Effect } @@ -560,6 +544,7 @@ export const make = Effect.gen(function* () { cancelSession, pendingBackground, runningBackground, + backgroundJobs: JobList.read(db, state.jobs), completeBackground, }) }) diff --git a/packages/core/src/job/list.ts b/packages/core/src/job/list.ts new file mode 100644 index 00000000000..5d4a9561911 --- /dev/null +++ b/packages/core/src/job/list.ts @@ -0,0 +1,126 @@ +export * as JobList from "./list.js" + +import { Job } from "@opencode/schema/job" +import { asc } from "drizzle-orm" +import { Effect, Schema, SynchronizedRef } from "effect" +import type { Database } from "../database/database.js" +import type { Info } from "../job.js" +import { type Recovery, RecoverySchema } from "./recovery.js" +import { JobTable } from "./sql.js" + +export type Item = Job.Info + +export type Live = { + readonly info: Info + readonly isBackgrounded: boolean + readonly recovery?: Recovery +} + +function toItem(input: { + readonly id: string + readonly status: Job.Status + readonly title?: string | null + readonly started: number + readonly completed?: number + readonly recovery: Recovery +}): Job.Info { + const title = input.title ?? undefined + const time: Job.Time = { + started: input.started, + ...(input.completed !== undefined ? { completed: input.completed } : {}), + } + const recovery = input.recovery + if (recovery.kind === "shell") { + return { + kind: "shell", + id: input.id, + sessionID: recovery.sessionID, + status: input.status, + ...(title !== undefined ? { title } : {}), + time, + shellID: recovery.shellID, + command: recovery.command, + } + } + if (recovery.kind === "subagent") { + return { + kind: "subagent", + id: input.id, + sessionID: recovery.parentSessionID, + status: input.status, + ...(title !== undefined ? { title } : {}), + time, + childSessionID: recovery.childSessionID, + agent: recovery.agent, + description: recovery.description, + } + } + return { + kind: "image", + id: input.id, + sessionID: recovery.sessionID, + status: input.status, + ...(title !== undefined ? { title } : {}), + time, + path: recovery.path, + model: recovery.model, + } +} + +export function read( + db: Database.Interface["db"], + jobs: SynchronizedRef.SynchronizedRef>, +): Effect.Effect { + const decodeRecovery = Schema.decodeUnknownOption(RecoverySchema) + return Effect.gen(function* () { + const [rows, active] = yield* Effect.all([ + db + .select() + .from(JobTable) + .orderBy(asc(JobTable.time_created), asc(JobTable.notification_id)) + .all() + .pipe(Effect.orDie), + SynchronizedRef.get(jobs), + ]) + const seen = new Set() + const items: Job.Info[] = [] + for (const row of rows) { + const recovery = decodeRecovery(row.recovery) + if (recovery._tag === "None") continue + seen.add(row.notification_id) + const live = active.get(row.id) + const sameGeneration = live?.info.notificationID === row.notification_id + const status = sameGeneration ? live.info.status : row.status + const completed = sameGeneration + ? live.info.completed_at + : row.status !== "running" + ? row.time_updated + : undefined + items.push( + toItem({ + id: row.id, + status, + title: sameGeneration && live.info.title !== undefined ? live.info.title : row.title, + started: row.time_created, + completed, + recovery: recovery.value, + }), + ) + } + for (const live of active.values()) { + if (!live.isBackgrounded || !live.recovery) continue + if (live.info.notificationID && seen.has(live.info.notificationID)) continue + items.push( + toItem({ + id: live.info.id, + status: live.info.status, + title: live.info.title, + started: live.info.started_at, + completed: live.info.completed_at, + recovery: live.recovery, + }), + ) + } + return items + }).pipe(Effect.withSpan("Job.backgroundJobs")) +} diff --git a/packages/core/src/job/recovery.ts b/packages/core/src/job/recovery.ts new file mode 100644 index 00000000000..c5d499bd621 --- /dev/null +++ b/packages/core/src/job/recovery.ts @@ -0,0 +1,26 @@ +import { Schema } from "effect" +import { SessionSchema } from "../session/schema.js" + +export const RecoverySchema = Schema.Union([ + Schema.Struct({ + kind: Schema.Literal("shell"), + sessionID: SessionSchema.ID, + shellID: Schema.String, + command: Schema.String, + }), + Schema.Struct({ + kind: Schema.Literal("subagent"), + parentSessionID: SessionSchema.ID, + childSessionID: SessionSchema.ID, + agent: Schema.String, + description: Schema.String, + }), + Schema.Struct({ + kind: Schema.Literal("image"), + sessionID: SessionSchema.ID, + path: Schema.String, + model: Schema.String, + }), +]) + +export type Recovery = typeof RecoverySchema.Type diff --git a/packages/core/src/session/background.ts b/packages/core/src/session/background.ts index df8b38bb0ec..65691910f75 100644 --- a/packages/core/src/session/background.ts +++ b/packages/core/src/session/background.ts @@ -1,9 +1,20 @@ export * as SessionBackground from "./background.js" +import type { Kind, Status } from "@opencode/schema/job" import { Effect } from "effect" import type { Job } from "../job.js" import type { SessionSchema } from "./schema.js" -import type { SessionStore } from "./store.js" + +export type Lookup = { + readonly get: (sessionID: SessionSchema.ID) => Effect.Effect<{ readonly parentID?: SessionSchema.ID } | undefined> +} + +export type ListFilter = { + readonly sessionID?: SessionSchema.ID + readonly kind?: Kind + readonly status?: Status + readonly descendants?: boolean +} /** * Background jobs still running for a Session or any of its descendants. A child's own @@ -12,11 +23,12 @@ import type { SessionStore } from "./store.js" */ export const outstanding = Effect.fnUntraced(function* ( jobs: Pick, - store: Pick, + store: Lookup, sessionID: SessionSchema.ID, ) { + const parents = new Map() const owned = yield* Effect.filter(yield* jobs.runningBackground, (recovery) => - descends(store, recovery.kind === "subagent" ? recovery.parentSessionID : recovery.sessionID, sessionID), + descends(store, parents, recovery.kind === "subagent" ? recovery.parentSessionID : recovery.sessionID, sessionID), ) return owned.map((recovery) => { if (recovery.kind === "shell") @@ -38,8 +50,27 @@ export const outstanding = Effect.fnUntraced(function* ( }) }) +/** Active and unconsumed background jobs matching the requested Session, kind, status, and descendant scope. */ +export const list = Effect.fn("SessionBackground.list")(function* ( + jobs: Pick, + store: Lookup, + filter: ListFilter = {}, +) { + const items = (yield* jobs.backgroundJobs).filter( + (item) => + (filter.kind === undefined || item.kind === filter.kind) && + (filter.status === undefined || item.status === filter.status), + ) + if (filter.sessionID === undefined) return items + const sessionID = filter.sessionID + if (!filter.descendants) return items.filter((item) => item.sessionID === sessionID) + const parents = new Map() + return yield* Effect.filter(items, (item) => descends(store, parents, item.sessionID, sessionID)) +}) + const descends = Effect.fnUntraced(function* ( - store: Pick, + store: Lookup, + parents: Map, from: SessionSchema.ID, ancestor: SessionSchema.ID, ) { @@ -48,7 +79,14 @@ const descends = Effect.fnUntraced(function* ( while (current !== undefined && !seen.has(current)) { if (current === ancestor) return true seen.add(current) - current = (yield* store.get(current))?.parentID + const cached = parents.get(current) + if (cached !== undefined) { + current = cached ?? undefined + continue + } + const parentID = (yield* store.get(current))?.parentID + parents.set(current, parentID ?? null) + current = parentID } return false }) diff --git a/packages/protocol/openapi.json b/packages/protocol/openapi.json index c54cc9ebe00..3bd978216e3 100644 --- a/packages/protocol/openapi.json +++ b/packages/protocol/openapi.json @@ -13367,6 +13367,122 @@ "summary": "View local artifact" } }, + "/api/experimental/job": { + "get": { + "tags": ["experimental"], + "operationId": "experimental.job.list", + "parameters": [ + { + "name": "sessionID", + "in": "query", + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Session.ID" + } + ], + "description": "Filter to background jobs owned by this session." + }, + "required": false + }, + { + "name": "kind", + "in": "query", + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Job.Kind" + } + ], + "description": "Filter by background job kind (shell, subagent, or image)." + }, + "required": false + }, + { + "name": "status", + "in": "query", + "schema": { + "anyOf": [ + { + "$ref": "#/components/schemas/Job.Status" + } + ], + "description": "Filter by job status (running, completed, error, or cancelled)." + }, + "required": false + }, + { + "name": "descendants", + "in": "query", + "schema": { + "anyOf": [ + { + "type": "string", + "enum": ["true", "false"] + } + ], + "description": "When sessionID is set, also include background jobs owned by child and nested subagent sessions." + }, + "required": false + } + ], + "security": [], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Job.Info" + } + } + }, + "required": ["data"], + "additionalProperties": false + } + } + } + }, + "400": { + "description": "InvalidRequestError", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/InvalidRequestErrorEncoded" + } + } + } + }, + "401": { + "description": "UnauthorizedError", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UnauthorizedErrorEncoded" + } + } + } + }, + "404": { + "description": "SessionNotFoundError", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SessionNotFoundErrorEncoded" + } + } + } + } + }, + "description": "List active and unconsumed background jobs, optionally filtered by owning session, descendants, or kind. Experimental: may change without compatibility guarantees.", + "summary": "List background jobs" + } + }, "/api/shell": { "get": { "tags": ["shell"], @@ -19809,6 +19925,140 @@ "required": ["_tag", "message"], "additionalProperties": false }, + "Job.Image": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["image"] + }, + "id": { + "type": "string" + }, + "sessionID": { + "$ref": "#/components/schemas/Session.ID" + }, + "status": { + "$ref": "#/components/schemas/Job.Status" + }, + "title": { + "type": "string" + }, + "time": { + "$ref": "#/components/schemas/Job.Time" + }, + "path": { + "type": "string" + }, + "model": { + "type": "string" + } + }, + "required": ["kind", "id", "sessionID", "status", "time", "path", "model"], + "additionalProperties": false + }, + "Job.Info": { + "anyOf": [ + { + "$ref": "#/components/schemas/Job.Shell" + }, + { + "$ref": "#/components/schemas/Job.Subagent" + }, + { + "$ref": "#/components/schemas/Job.Image" + } + ] + }, + "Job.Kind": { + "type": "string", + "enum": ["shell", "subagent", "image"] + }, + "Job.Shell": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["shell"] + }, + "id": { + "type": "string" + }, + "sessionID": { + "$ref": "#/components/schemas/Session.ID" + }, + "status": { + "$ref": "#/components/schemas/Job.Status" + }, + "title": { + "type": "string" + }, + "time": { + "$ref": "#/components/schemas/Job.Time" + }, + "shellID": { + "type": "string" + }, + "command": { + "type": "string" + } + }, + "required": ["kind", "id", "sessionID", "status", "time", "shellID", "command"], + "additionalProperties": false + }, + "Job.Status": { + "type": "string", + "enum": ["running", "completed", "error", "cancelled"] + }, + "Job.Subagent": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": ["subagent"] + }, + "id": { + "type": "string" + }, + "sessionID": { + "$ref": "#/components/schemas/Session.ID" + }, + "status": { + "$ref": "#/components/schemas/Job.Status" + }, + "title": { + "type": "string" + }, + "time": { + "$ref": "#/components/schemas/Job.Time" + }, + "childSessionID": { + "$ref": "#/components/schemas/Session.ID" + }, + "agent": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "required": ["kind", "id", "sessionID", "status", "time", "childSessionID", "agent", "description"], + "additionalProperties": false + }, + "Job.Time": { + "type": "object", + "properties": { + "started": { + "type": "number", + "description": "Start time in milliseconds since the Unix epoch" + }, + "completed": { + "type": "number" + } + }, + "required": ["started"], + "additionalProperties": false + }, "Location.PublicInfo": { "type": "object", "properties": { diff --git a/packages/protocol/src/groups/experimental.ts b/packages/protocol/src/groups/experimental.ts index 3f3cd006e83..908f4b42c66 100644 --- a/packages/protocol/src/groups/experimental.ts +++ b/packages/protocol/src/groups/experimental.ts @@ -1,7 +1,13 @@ import { ArtifactEndpoints } from "./artifact.js" +import { JobEndpoints } from "./job.js" import { MediaGetEndpoint } from "./media.js" import { PersistentPtyGroup } from "./persistent-pty.js" import { ScheduleEndpoints } from "./schedule.js" /** `server.experimental`: routes under /api/experimental, without compatibility guarantees. */ -export const ExperimentalGroup = PersistentPtyGroup.add(MediaGetEndpoint, ...ScheduleEndpoints, ...ArtifactEndpoints) +export const ExperimentalGroup = PersistentPtyGroup.add( + MediaGetEndpoint, + ...ScheduleEndpoints, + ...ArtifactEndpoints, + ...JobEndpoints, +) diff --git a/packages/protocol/src/groups/job.ts b/packages/protocol/src/groups/job.ts new file mode 100644 index 00000000000..0981ef3f48b --- /dev/null +++ b/packages/protocol/src/groups/job.ts @@ -0,0 +1,45 @@ +import { Job } from "@opencode/schema/job" +import { Session } from "@opencode/schema/session" +import { Schema, SchemaGetter } from "effect" +import { HttpApiEndpoint, OpenApi } from "effect/http-api" +import { InvalidRequestError, SessionNotFoundError } from "../errors.js" + +const BooleanFromString = Schema.Literals(["true", "false"]).pipe( + Schema.decodeTo(Schema.Boolean, { + decode: SchemaGetter.transform((value) => value === "true"), + encode: SchemaGetter.transform((value): "true" | "false" => (value ? "true" : "false")), + }), +) + +export const ListQuery = Schema.Struct({ + sessionID: Schema.optional(Session.ID).annotate({ + description: "Filter to background jobs owned by this session.", + }), + kind: Schema.optional(Job.Kind).annotate({ + description: "Filter by background job kind (shell, subagent, or image).", + }), + status: Schema.optional(Job.Status).annotate({ + description: "Filter by job status (running, completed, error, or cancelled).", + }), + descendants: Schema.optional(BooleanFromString).annotate({ + description: "When sessionID is set, also include background jobs owned by child and nested subagent sessions.", + }), +}).annotate({ identifier: "Job.ListQuery" }) +export type ListQuery = typeof ListQuery.Type + +/** Lives in the `server.experimental` group (see `groups/experimental.ts`). */ +export const JobEndpoints = [ + HttpApiEndpoint.get("job.list", "/api/experimental/job", { + query: ListQuery, + success: Schema.Struct({ data: Schema.Array(Job.Info) }), + error: [InvalidRequestError, SessionNotFoundError], + }).annotateMerge( + OpenApi.annotations({ + identifier: "experimental.job.list", + summary: "List background jobs", + description: + "List active and unconsumed background jobs, optionally filtered by owning session, descendants, or kind. Experimental: may change without compatibility guarantees.", + transform: (operation) => ({ ...operation, tags: ["experimental"] }), + }), + ), +] as const diff --git a/packages/schema/src/job.ts b/packages/schema/src/job.ts new file mode 100644 index 00000000000..4587906dcaf --- /dev/null +++ b/packages/schema/src/job.ts @@ -0,0 +1,60 @@ +export * as Job from "./job.js" + +import { Schema } from "effect" +import { optional } from "./schema.js" +import { SessionID } from "./session-id.js" + +export const Kind = Schema.Literals(["shell", "subagent", "image"]).annotate({ identifier: "Job.Kind" }) +export type Kind = typeof Kind.Type + +export const Status = Schema.Literals(["running", "completed", "error", "cancelled"]).annotate({ + identifier: "Job.Status", +}) +export type Status = typeof Status.Type + +export interface Time extends Schema.Schema.Type {} +export const Time = Schema.Struct({ + started: Schema.Finite.annotate({ description: "Start time in milliseconds since the Unix epoch" }), + completed: optional(Schema.Finite).annotate({ + description: "Completion time in milliseconds since the Unix epoch", + }), +}).annotate({ identifier: "Job.Time" }) + +const Base = { + id: Schema.String, + sessionID: SessionID, + status: Status, + title: optional(Schema.String), + time: Time, +} + +export interface Shell extends Schema.Schema.Type {} +export const Shell = Schema.Struct({ + kind: Schema.tag("shell"), + ...Base, + shellID: Schema.String, + command: Schema.String, +}).annotate({ identifier: "Job.Shell" }) + +export interface Subagent extends Schema.Schema.Type {} +export const Subagent = Schema.Struct({ + kind: Schema.tag("subagent"), + ...Base, + childSessionID: SessionID, + agent: Schema.String, + description: Schema.String, +}).annotate({ identifier: "Job.Subagent" }) + +export interface Image extends Schema.Schema.Type {} +export const Image = Schema.Struct({ + kind: Schema.tag("image"), + ...Base, + path: Schema.String, + model: Schema.String, +}).annotate({ identifier: "Job.Image" }) + +export const Info = Schema.Union([Shell, Subagent, Image]).pipe( + Schema.toTaggedUnion("kind"), + Schema.annotate({ identifier: "Job.Info" }), +) +export type Info = typeof Info.Type diff --git a/packages/schema/test/contract-hygiene.test.ts b/packages/schema/test/contract-hygiene.test.ts index a1b7a684570..ae7de76e635 100644 --- a/packages/schema/test/contract-hygiene.test.ts +++ b/packages/schema/test/contract-hygiene.test.ts @@ -6,6 +6,7 @@ import { ConfigAgent } from "../src/config/agent.js" import { ConfigProvider } from "../src/config/provider.js" import { FileSystem } from "../src/filesystem.js" import { Form } from "../src/form.js" +import { Job } from "../src/job.js" import { Mcp } from "../src/mcp.js" import { Model } from "../src/model.js" import { Project } from "../src/project.js" @@ -177,6 +178,13 @@ describe("contract hygiene", () => { Form.Fields, Form.Info, Form.ExternalField, + Job.Kind, + Job.Status, + Job.Time, + Job.Shell, + Job.Subagent, + Job.Image, + Job.Info, Mcp.Resource, Mcp.ResourceTemplate, Mcp.ResourceCatalog, diff --git a/packages/server/src/handlers/job.ts b/packages/server/src/handlers/job.ts new file mode 100644 index 00000000000..07a37fb516d --- /dev/null +++ b/packages/server/src/handlers/job.ts @@ -0,0 +1,26 @@ +import { Job } from "@opencode/core/job" +import { Session } from "@opencode/core/session" +import { SessionBackground } from "@opencode/core/session/background" +import type { ListQuery } from "@opencode/protocol/groups/job" +import { Effect, Option } from "effect" +import { missingSession } from "./session-error" + +/** `job.*` in the `server.experimental` group. */ +export const makeJob = Effect.gen(function* () { + const jobs = yield* Job.Service + const sessions = yield* Session.Service + const lookup = { + get: (sessionID: Session.ID) => sessions.get(sessionID).pipe(Effect.option, Effect.map(Option.getOrUndefined)), + } + + return { + list: Effect.fn("JobHandler.list")(function* (query: ListQuery) { + if (query.sessionID !== undefined) { + yield* sessions.get(query.sessionID).pipe(Effect.catchTag("Session.NotFoundError", missingSession)) + } + return { + data: yield* SessionBackground.list(jobs, lookup, query), + } + }), + } +}) diff --git a/packages/server/src/handlers/persistent-pty.ts b/packages/server/src/handlers/persistent-pty.ts index f5297bb4720..e861cfdecc2 100644 --- a/packages/server/src/handlers/persistent-pty.ts +++ b/packages/server/src/handlers/persistent-pty.ts @@ -19,6 +19,7 @@ import { Socket } from "effect/socket" import { Api } from "../api" import { CorsConfig, isAllowedRequestOrigin } from "../cors" import { makeArtifact } from "./artifact" +import { makeJob } from "./job" import { makeMediaGet } from "./media" import { type Outbound, runPtySocket } from "./pty-socket" import { makeSchedule } from "./schedule" @@ -29,11 +30,13 @@ export const PersistentPtyHandler = HttpApiBuilder.group(Api, "server.experiment const cors = yield* CorsConfig const pty = yield* PersistentPty.Service const artifact = yield* makeArtifact + const job = yield* makeJob const mediaGet = yield* makeMediaGet const schedule = yield* makeSchedule return handlers .handleRaw("media.get", (ctx) => mediaGet(ctx.params.hash, ctx.request)) + .handle("job.list", (ctx) => job.list(ctx.query)) .handle("artifacts.providers", (ctx) => artifact.providers(ctx.query, ctx.request)) .handle("artifacts.list", (ctx) => artifact.list(ctx.query, ctx.request)) .handle("artifacts.create", (ctx) => artifact.create(ctx.query, ctx.payload, ctx.request)) diff --git a/packages/server/test/job.test.ts b/packages/server/test/job.test.ts new file mode 100644 index 00000000000..9ba20473ef4 --- /dev/null +++ b/packages/server/test/job.test.ts @@ -0,0 +1,186 @@ +import fs from "node:fs/promises" +import path from "node:path" +import { expect } from "bun:test" +import { OpenCode } from "@opencode/client" +import { Database } from "@opencode/core/database/database" +import { Job } from "@opencode/core/job" +import { Session } from "@opencode/core/session" +import { makeGlobalNode } from "@opencode/util/effect/app-node" +import { Deferred, Effect, Layer } from "effect" +import { tmpdirScoped } from "../../core/test/fixture/tmpdir" +import { it } from "../../core/test/lib/effect" +import { ServerFetch } from "../src/fetch" + +const client = (handler: (request: Request) => Promise) => + OpenCode.make({ + baseUrl: "http://opencode.local", + fetch: Object.assign((input: string | URL | Request, init?: RequestInit) => handler(new Request(input, init)), { + preconnect: fetch.preconnect, + }), + }) + +it.live("lists background jobs by session, kind, and descendants until completion notice clears them", () => + Effect.gen(function* () { + const dir = (yield* tmpdirScoped("opencode-job-api-")).path + const global = path.join(dir, "global") + const project = path.join(dir, "project") + yield* Effect.promise(() => Promise.all([global, project].map((item) => fs.mkdir(item, { recursive: true })))) + + const captured = yield* Deferred.make() + const jobNode = makeGlobalNode({ + service: Job.Service, + layer: Layer.effect( + Job.Service, + Job.make.pipe(Effect.tap((service) => Deferred.succeed(captured, service))), + ), + deps: [Database.node], + }) + const handler = yield* ServerFetch.make( + { + app: { version: "test" }, + database: { path: path.join(dir, "opencode.db") }, + config: { directory: global, project: false, claude: false }, + models: { fetch: false }, + fs: { filewatcher: false }, + }, + { overrides: [Job.node.replace(jobNode)] }, + ) + const jobs = yield* Deferred.await(captured) + const api = client(handler) + + const root = yield* Effect.promise(() => api.session.create({ location: { directory: project } })) + const child = yield* Effect.promise(() => api.session.create({ parentID: root.id })) + const other = yield* Effect.promise(() => api.session.create({ location: { directory: project } })) + const rootID = Session.ID.make(root.id) + const childID = Session.ID.make(child.id) + const otherID = Session.ID.make(other.id) + + yield* Effect.promise(async () => { + await expect(api.experimental.job.list({ sessionID: Session.ID.create() })).rejects.toMatchObject({ + _tag: "SessionNotFoundError", + }) + }) + + const fgGate = yield* Deferred.make() + const shellGate = yield* Deferred.make() + const subagentGate = yield* Deferred.make() + const childShellGate = yield* Deferred.make() + const imageGate = yield* Deferred.make() + + // Foreground jobs stay invisible until moved to the background. + yield* jobs.start({ + id: "sh_fg", + type: "shell", + title: "echo fg", + recovery: { kind: "shell", sessionID: rootID, shellID: "sh_fg", command: "echo fg" }, + run: Deferred.await(fgGate), + }) + expect(yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id }))).toEqual([]) + + yield* jobs.start({ + id: "sh_root", + type: "shell", + title: "bun test", + recovery: { kind: "shell", sessionID: rootID, shellID: "sh_root", command: "bun test" }, + run: Deferred.await(shellGate), + }) + const shellBg = yield* jobs.background("sh_root") + + yield* jobs.start({ + id: child.id, + type: "subagent", + title: "audit routes", + recovery: { + kind: "subagent", + parentSessionID: rootID, + childSessionID: childID, + agent: "explore", + description: "audit routes", + }, + run: Deferred.await(subagentGate), + }) + const subagentBg = yield* jobs.background(child.id) + + yield* jobs.start({ + id: "sh_child", + type: "shell", + title: "pytest", + recovery: { kind: "shell", sessionID: childID, shellID: "sh_child", command: "pytest" }, + run: Deferred.await(childShellGate), + }) + const childShellBg = yield* jobs.background("sh_child") + + yield* jobs.start({ + id: "img_other", + type: "experimental_image_generate", + title: "diagram", + recovery: { kind: "image", sessionID: otherID, path: "/tmp/diagram", model: "openai/gpt-image-1" }, + run: Deferred.await(imageGate), + }) + const imageBg = yield* jobs.background("img_other") + + // Direct session query returns only root's own shell + subagent jobs, not child's shell or other's image. + const direct = yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id })) + expect(direct).toMatchObject([ + { kind: "shell", id: "sh_root", sessionID: root.id, status: "running", shellID: "sh_root", command: "bun test" }, + { + kind: "subagent", + id: child.id, + sessionID: root.id, + status: "running", + childSessionID: child.id, + agent: "explore", + description: "audit routes", + }, + ]) + + // Kind filter selects shell jobs for that session directly. + const rootShells = yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id, kind: "shell" })) + expect(rootShells.map((item) => item.id)).toEqual(["sh_root"]) + + // Descendants includes child session jobs while excluding unrelated sessions. + const withDescendants = yield* Effect.promise(() => + api.experimental.job.list({ sessionID: root.id, descendants: true }), + ) + expect(withDescendants.map((item) => item.id)).toEqual(["sh_root", child.id, "sh_child"]) + + // Unfiltered list returns every unconsumed background job on the server. + const all = yield* Effect.promise(() => api.experimental.job.list()) + expect(all.map((item) => item.id)).toEqual(["sh_root", child.id, "sh_child", "img_other"]) + + // Settled background work stays visible as "completed" until completeBackground clears its notice. + yield* Deferred.succeed(shellGate, "passed") + yield* jobs.wait({ id: "sh_root" }) + const settled = yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id, kind: "shell" })) + expect(settled).toMatchObject([ + { + kind: "shell", + id: "sh_root", + status: "completed", + time: { started: expect.any(Number), completed: expect.any(Number) }, + }, + ]) + expect( + (yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id, status: "running" }))).map( + (item) => item.id, + ), + ).toEqual([child.id]) + expect( + (yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id, status: "completed" }))).map( + (item) => item.id, + ), + ).toEqual(["sh_root"]) + + if (shellBg?.notificationID) yield* jobs.completeBackground(shellBg.notificationID) + expect(yield* Effect.promise(() => api.experimental.job.list({ sessionID: root.id, kind: "shell" }))).toEqual([]) + + // Cleanup remaining test jobs. + yield* Deferred.succeed(fgGate, "done") + yield* Deferred.succeed(subagentGate, "done") + yield* Deferred.succeed(childShellGate, "done") + yield* Deferred.succeed(imageGate, "done") + if (subagentBg?.notificationID) yield* jobs.completeBackground(subagentBg.notificationID) + if (childShellBg?.notificationID) yield* jobs.completeBackground(childShellBg.notificationID) + if (imageBg?.notificationID) yield* jobs.completeBackground(imageBg.notificationID) + }), +)