feat(server): add experimental job list endpoint (#60698)

This commit is contained in:
Aiden Cline
2026-11-03 10:32:50 -06:00
committed by GitHub
Unverified
parent 0988cb8366
commit bde737f4d5
18 changed files with 892 additions and 28 deletions
+2
View File
@@ -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),
+13
View File
@@ -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<E = never> = (
input: ExperimentalArtifactsDeleteInput,
) => Effect.Effect<ExperimentalArtifactsDeleteOutput, E>
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<Job.Info>
export type ExperimentalJobListOperation<E = never> = (
input?: ExperimentalJobListInput,
) => Effect.Effect<ExperimentalJobListOutput, E>
export interface ExperimentalApi<E = never> {
readonly persistentPty: {
readonly read: ExperimentalPersistentPtyReadOperation<E>
@@ -2521,6 +2533,7 @@ export interface ExperimentalApi<E = never> {
readonly update: ExperimentalArtifactsUpdateOperation<E>
readonly delete: ExperimentalArtifactsDeleteOperation<E>
}
readonly job: { readonly list: ExperimentalJobListOperation<E> }
}
export type ShellListInput = { readonly location?: { readonly directory?: string | undefined } | undefined }
+18
View File
@@ -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<ExperimentalJobListOutput>()(
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) =>
+21
View File
@@ -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) =>
+49
View File
@@ -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<JobInfo> }["data"]
export type ShellListInput = { readonly location?: { readonly directory?: string | undefined } | undefined }
export type ShellListOutput = { location: LocationPublicRef; data: Array<ShellInfo1> }
+2
View File
@@ -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",
+7 -22
View File
@@ -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<Info[]>
readonly pendingBackground: Effect.Effect<readonly Background[]>
readonly runningBackground: Effect.Effect<readonly Recovery[]>
readonly backgroundJobs: Effect.Effect<readonly JobList.Item[]>
readonly completeBackground: (notificationID: SessionMessage.ID) => Effect.Effect<void>
}
@@ -560,6 +544,7 @@ export const make = Effect.gen(function* () {
cancelSession,
pendingBackground,
runningBackground,
backgroundJobs: JobList.read(db, state.jobs),
completeBackground,
})
})
+126
View File
@@ -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<Entry extends Live>(
db: Database.Interface["db"],
jobs: SynchronizedRef.SynchronizedRef<Map<string, Entry>>,
): Effect.Effect<readonly Job.Info[]> {
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<string>()
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"))
}
+26
View File
@@ -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
+43 -5
View File
@@ -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<Job.Interface, "runningBackground">,
store: Pick<SessionStore.Interface, "get">,
store: Lookup,
sessionID: SessionSchema.ID,
) {
const parents = new Map<SessionSchema.ID, SessionSchema.ID | null>()
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<Job.Interface, "backgroundJobs">,
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<SessionSchema.ID, SessionSchema.ID | null>()
return yield* Effect.filter(items, (item) => descends(store, parents, item.sessionID, sessionID))
})
const descends = Effect.fnUntraced(function* (
store: Pick<SessionStore.Interface, "get">,
store: Lookup,
parents: Map<SessionSchema.ID, SessionSchema.ID | null>,
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
})
+250
View File
@@ -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": {
+7 -1
View File
@@ -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,
)
+45
View File
@@ -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
+60
View File
@@ -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<typeof Time> {}
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<typeof Shell> {}
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<typeof Subagent> {}
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<typeof Image> {}
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
@@ -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,
+26
View File
@@ -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),
}
}),
}
})
@@ -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))
+186
View File
@@ -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<Response>) =>
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<Job.Interface>()
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<string>()
const shellGate = yield* Deferred.make<string>()
const subagentGate = yield* Deferred.make<string>()
const childShellGate = yield* Deferred.make<string>()
const imageGate = yield* Deferred.make<string>()
// 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)
}),
)