@opencode/protocol 0.0.0-reserved → 2.0.1

package/dist/groups/permission.js

@@ -0,0 +1,109 @@
+import { Agent } from "@opencode/schema/agent";
+import { Location } from "@opencode/schema/location";
+import { Permission } from "@opencode/schema/permission";
+import { PermissionSaved } from "@opencode/schema/permission-saved";
+import { Project } from "@opencode/schema/project";
+import { Session } from "@opencode/schema/session";
+import { Context, Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+import { PermissionNotFoundError, SessionNotFoundError } from "../errors.js";
+import { LocationQuery, locationQueryOpenApi } from "./location.js";
+export const makePermissionGroup = (locationMiddleware, sessionLocationMiddleware) => HttpApiGroup.make("server.permission")
+    .add(HttpApiEndpoint.get("permission.request.list", "/api/permission/request", {
+    query: LocationQuery,
+    success: Location.response(Schema.Array(Permission.Request)),
+})
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.permission.request.list",
+    summary: "List pending permission requests",
+    description: "Retrieve pending permission requests for a location.",
+})))
+    .add(HttpApiEndpoint.get("permission.saved.list", "/api/permission/saved", {
+    query: Schema.Struct({ projectID: Project.ID.pipe(Schema.optional) }),
+    success: Schema.Struct({ data: Schema.Array(PermissionSaved.Info) }),
+}).annotateMerge(OpenApi.annotations({
+    identifier: "v2.permission.saved.list",
+    summary: "List saved permissions",
+    description: "Retrieve saved permissions, optionally filtered by project.",
+})))
+    .add(HttpApiEndpoint.delete("permission.saved.remove", "/api/permission/saved/:id", {
+    params: { id: PermissionSaved.ID },
+    success: HttpApiSchema.NoContent,
+}).annotateMerge(OpenApi.annotations({
+    identifier: "v2.permission.saved.remove",
+    summary: "Remove saved permission",
+    description: "Remove a saved permission by ID.",
+})))
+    // Effect applies group middleware only to endpoints already added; session endpoints use session placement below.
+    .middleware(locationMiddleware)
+    .add(HttpApiEndpoint.post("session.permission.create", "/api/session/:sessionID/permission", {
+    params: { sessionID: Session.ID },
+    payload: Schema.Struct({
+        id: Permission.ID.pipe(Schema.optional),
+        action: Permission.Request.fields.action,
+        resources: Permission.Request.fields.resources,
+        save: Permission.Request.fields.save,
+        metadata: Permission.Request.fields.metadata,
+        source: Permission.Request.fields.source,
+        agent: Agent.ID.pipe(Schema.optional),
+    }),
+    success: Schema.Struct({
+        data: Schema.Struct({ id: Permission.ID, effect: Permission.Effect }),
+    }),
+    error: SessionNotFoundError,
+})
+    .middleware(sessionLocationMiddleware)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.session.permission.create",
+    summary: "Create permission request",
+    description: "Evaluate and, when approval is required, create a permission request for a session.",
+})))
+    .add(HttpApiEndpoint.get("session.permission.list", "/api/session/:sessionID/permission", {
+    params: { sessionID: Session.ID },
+    success: Schema.Struct({ data: Schema.Array(Permission.Request) }),
+    error: SessionNotFoundError,
+}).annotateMerge(OpenApi.annotations({
+    identifier: "v2.session.permission.list",
+    summary: "List session permission requests",
+    description: "Retrieve pending permission requests owned by a session.",
+})))
+    .add(HttpApiEndpoint.get("session.permission.get", "/api/session/:sessionID/permission/:requestID", {
+    params: { sessionID: Session.ID, requestID: Permission.ID },
+    success: Schema.Struct({ data: Permission.Request }),
+    error: [SessionNotFoundError, PermissionNotFoundError],
+})
+    .middleware(sessionLocationMiddleware)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.session.permission.get",
+    summary: "Get permission request",
+    description: "Retrieve a pending permission request owned by a session.",
+})))
+    .add(HttpApiEndpoint.post("session.permission.reply", "/api/session/:sessionID/permission/:requestID/reply", {
+    params: { sessionID: Session.ID, requestID: Permission.ID },
+    payload: Schema.Struct({
+        reply: Permission.Reply,
+        message: Schema.String.pipe(Schema.optional),
+    }),
+    success: HttpApiSchema.NoContent,
+    error: [SessionNotFoundError, PermissionNotFoundError],
+})
+    .middleware(sessionLocationMiddleware)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.session.permission.reply",
+    summary: "Reply to pending permission request",
+    description: "Respond to a pending permission request owned by a session.",
+})))
+    .add(HttpApiEndpoint.put("session.permission.rules", "/api/session/:sessionID/permission/rules", {
+    params: { sessionID: Session.ID },
+    payload: Schema.Struct({ permissions: Permission.Ruleset }),
+    success: HttpApiSchema.NoContent,
+    error: SessionNotFoundError,
+})
+    .middleware(sessionLocationMiddleware)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.session.permission.rules",
+    summary: "Replace session permission rules",
+    description: "Replace the session-scoped permission rules. Rules are evaluated after the agent's rules, and the last matching rule wins.",
+})))
+    .annotateMerge(OpenApi.annotations({ title: "permission", description: "Experimental permission routes." }));

package/dist/groups/persistent-pty.d.ts

@@ -0,0 +1,249 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi";
+import { ForbiddenError, InvalidRequestError, PtyNotFoundError, ServiceUnavailableError } from "../errors.js";
+import { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE } from "./pty.js";
+export { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE };
+export declare function hasPersistentPtyConnectTicketURL(url: URL): boolean;
+export declare const PersistentPtyGroup: HttpApiGroup.HttpApiGroup<"server.experimental", HttpApiEndpoint.HttpApiEndpoint<"persistentPty.read", "GET", "/api/experimental/session/:sessionID/terminal/read", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+        descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+    };
+}>>, Schema.toCodecStringTree<Schema.Struct<{
+    lines: Schema.optional<Schema.compose<Schema.Int, Schema.NumberFromString>>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.NullOr<Schema.Struct<{
+        readonly ptyID: Schema.brand<Schema.String, "PtyID"> & {
+            create: () => string & import("effect/Brand").Brand<"PtyID">;
+            ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+        };
+        readonly title: Schema.String;
+        readonly cwd: Schema.String;
+        readonly foregroundProcess: Schema.NullOr<Schema.String>;
+        readonly screen: Schema.Struct<{
+            readonly text: Schema.String;
+            readonly cols: Schema.Int;
+            readonly rows: Schema.Int;
+            readonly cursor: Schema.Struct<{
+                readonly x: Schema.Int;
+                readonly y: Schema.Int;
+            }>;
+        }>;
+    }>>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.list", "GET", "/api/experimental/session/:sessionID/terminal", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+        descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => string & import("effect/Brand").Brand<"SessionID">;
+            descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+        };
+        readonly foregroundProcess: Schema.NullOr<Schema.String>;
+        readonly size: Schema.Struct<{
+            readonly cols: Schema.Int;
+            readonly rows: Schema.Int;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly head: Schema.Int;
+            readonly tail: Schema.Int;
+        }>;
+        readonly id: Schema.brand<Schema.String, "PtyID"> & {
+            create: () => string & import("effect/Brand").Brand<"PtyID">;
+            ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+        };
+        readonly title: Schema.String;
+        readonly command: Schema.String;
+        readonly args: Schema.$Array<Schema.String>;
+        readonly cwd: Schema.String;
+        readonly status: Schema.Literals<readonly ["running", "exited"]>;
+        readonly pid: Schema.Int;
+        readonly exitCode: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Int>>, Schema.optionalKey<Schema.Int>, never, never>;
+    }>>;
+}>>, Schema.toCodecJson<typeof InvalidRequestError | typeof ServiceUnavailableError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.create", "POST", "/api/experimental/session/:sessionID/terminal", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+        descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+    };
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly command: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+    readonly args: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+    readonly title: Schema.String;
+    readonly env: Schema.$Record<Schema.String, Schema.String>;
+    readonly size: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Struct<{
+        readonly cols: Schema.Int;
+        readonly rows: Schema.Int;
+    }>>>, Schema.optionalKey<Schema.Struct<{
+        readonly cols: Schema.Int;
+        readonly rows: Schema.Int;
+    }>>, never, never>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => string & import("effect/Brand").Brand<"SessionID">;
+            descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+        };
+        readonly foregroundProcess: Schema.NullOr<Schema.String>;
+        readonly size: Schema.Struct<{
+            readonly cols: Schema.Int;
+            readonly rows: Schema.Int;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly head: Schema.Int;
+            readonly tail: Schema.Int;
+        }>;
+        readonly id: Schema.brand<Schema.String, "PtyID"> & {
+            create: () => string & import("effect/Brand").Brand<"PtyID">;
+            ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+        };
+        readonly title: Schema.String;
+        readonly command: Schema.String;
+        readonly args: Schema.$Array<Schema.String>;
+        readonly cwd: Schema.String;
+        readonly status: Schema.Literals<readonly ["running", "exited"]>;
+        readonly pid: Schema.Int;
+        readonly exitCode: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Int>>, Schema.optionalKey<Schema.Int>, never, never>;
+    }>;
+}>>, Schema.toCodecJson<typeof InvalidRequestError | typeof ServiceUnavailableError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.shutdown", "POST", "/api/experimental/persistent-pty/shutdown", never, never, never, never, Schema.toCodecJson<HttpApiSchema.NoContent>, Schema.toCodecJson<typeof ServiceUnavailableError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.handoff", "POST", "/api/experimental/persistent-pty/handoff", never, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly handoff: Schema.NullOr<Schema.Struct<{
+        readonly directory: Schema.String;
+        readonly instanceID: Schema.String;
+        readonly ticket: Schema.String;
+        readonly expiresAt: Schema.Number;
+    }>>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.get", "GET", "/api/experimental/persistent-pty/:ptyID", Schema.toCodecStringTree<Schema.Struct<{
+    ptyID: Schema.brand<Schema.String, "PtyID"> & {
+        create: () => string & import("effect/Brand").Brand<"PtyID">;
+        ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => string & import("effect/Brand").Brand<"SessionID">;
+            descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+        };
+        readonly foregroundProcess: Schema.NullOr<Schema.String>;
+        readonly size: Schema.Struct<{
+            readonly cols: Schema.Int;
+            readonly rows: Schema.Int;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly head: Schema.Int;
+            readonly tail: Schema.Int;
+        }>;
+        readonly id: Schema.brand<Schema.String, "PtyID"> & {
+            create: () => string & import("effect/Brand").Brand<"PtyID">;
+            ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+        };
+        readonly title: Schema.String;
+        readonly command: Schema.String;
+        readonly args: Schema.$Array<Schema.String>;
+        readonly cwd: Schema.String;
+        readonly status: Schema.Literals<readonly ["running", "exited"]>;
+        readonly pid: Schema.Int;
+        readonly exitCode: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Int>>, Schema.optionalKey<Schema.Int>, never, never>;
+    }>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof PtyNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.update", "PUT", "/api/experimental/persistent-pty/:ptyID", Schema.toCodecStringTree<Schema.Struct<{
+    ptyID: Schema.brand<Schema.String, "PtyID"> & {
+        create: () => string & import("effect/Brand").Brand<"PtyID">;
+        ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+    };
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly attachmentID: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+    readonly size: Schema.Struct<{
+        readonly cols: Schema.Int;
+        readonly rows: Schema.Int;
+    }>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => string & import("effect/Brand").Brand<"SessionID">;
+            descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+        };
+        readonly foregroundProcess: Schema.NullOr<Schema.String>;
+        readonly size: Schema.Struct<{
+            readonly cols: Schema.Int;
+            readonly rows: Schema.Int;
+        }>;
+        readonly output: Schema.Struct<{
+            readonly head: Schema.Int;
+            readonly tail: Schema.Int;
+        }>;
+        readonly id: Schema.brand<Schema.String, "PtyID"> & {
+            create: () => string & import("effect/Brand").Brand<"PtyID">;
+            ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+        };
+        readonly title: Schema.String;
+        readonly command: Schema.String;
+        readonly args: Schema.$Array<Schema.String>;
+        readonly cwd: Schema.String;
+        readonly status: Schema.Literals<readonly ["running", "exited"]>;
+        readonly pid: Schema.Int;
+        readonly exitCode: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Int>>, Schema.optionalKey<Schema.Int>, never, never>;
+    }>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof PtyNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.snapshot", "GET", "/api/experimental/persistent-pty/:ptyID/snapshot", Schema.toCodecStringTree<Schema.Struct<{
+    ptyID: Schema.brand<Schema.String, "PtyID"> & {
+        create: () => string & import("effect/Brand").Brand<"PtyID">;
+        ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly info: Schema.Struct<{
+            readonly sessionID: Schema.brand<Schema.String, "SessionID"> & {
+                create: () => string & import("effect/Brand").Brand<"SessionID">;
+                descending: (id?: string) => string & import("effect/Brand").Brand<"SessionID">;
+            };
+            readonly foregroundProcess: Schema.NullOr<Schema.String>;
+            readonly size: Schema.Struct<{
+                readonly cols: Schema.Int;
+                readonly rows: Schema.Int;
+            }>;
+            readonly output: Schema.Struct<{
+                readonly head: Schema.Int;
+                readonly tail: Schema.Int;
+            }>;
+            readonly id: Schema.brand<Schema.String, "PtyID"> & {
+                create: () => string & import("effect/Brand").Brand<"PtyID">;
+                ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+            };
+            readonly title: Schema.String;
+            readonly command: Schema.String;
+            readonly args: Schema.$Array<Schema.String>;
+            readonly cwd: Schema.String;
+            readonly status: Schema.Literals<readonly ["running", "exited"]>;
+            readonly pid: Schema.Int;
+            readonly exitCode: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Int>>, Schema.optionalKey<Schema.Int>, never, never>;
+        }>;
+        readonly text: Schema.String;
+        readonly checkpoint: Schema.Uint8Array;
+        readonly cursor: Schema.Struct<{
+            readonly x: Schema.Int;
+            readonly y: Schema.Int;
+        }>;
+    }>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof PtyNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.remove", "DELETE", "/api/experimental/persistent-pty/:ptyID", Schema.toCodecStringTree<Schema.Struct<{
+    ptyID: Schema.brand<Schema.String, "PtyID"> & {
+        create: () => string & import("effect/Brand").Brand<"PtyID">;
+        ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<HttpApiSchema.NoContent>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof PtyNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.connectToken", "POST", "/api/experimental/persistent-pty/:ptyID/connect-token", Schema.toCodecStringTree<Schema.Struct<{
+    ptyID: Schema.brand<Schema.String, "PtyID"> & {
+        create: () => string & import("effect/Brand").Brand<"PtyID">;
+        ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+    };
+}>>, never, never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly "x-opencode-ticket": Schema.optional<Schema.String>;
+}>>, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly ticket: Schema.String;
+        readonly expires_in: Schema.Int;
+    }>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof ForbiddenError | typeof PtyNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"persistentPty.connect", "GET", "/api/experimental/persistent-pty/:ptyID/connect", Schema.toCodecStringTree<Schema.Struct<{
+    ptyID: Schema.brand<Schema.String, "PtyID"> & {
+        create: () => string & import("effect/Brand").Brand<"PtyID">;
+        ascending: (id?: string) => string & import("effect/Brand").Brand<"PtyID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<Schema.Boolean>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof ForbiddenError | typeof PtyNotFoundError>, never, never>, false>;

package/dist/groups/persistent-pty.js

@@ -0,0 +1,91 @@
+import { PersistentPty } from "@opencode/schema/persistent-pty";
+import { Pty } from "@opencode/schema/pty";
+import { PtyTicket } from "@opencode/schema/pty-ticket";
+import { Session } from "@opencode/schema/session";
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+import { ForbiddenError, InvalidRequestError, PtyNotFoundError, ServiceUnavailableError } from "../errors.js";
+import { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE } from "./pty.js";
+export { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE };
+const CONNECT_PATH = /^\/api\/experimental\/persistent-pty\/[^/]+\/connect$/;
+export function hasPersistentPtyConnectTicketURL(url) {
+    return CONNECT_PATH.test(url.pathname) && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY);
+}
+const errors = [InvalidRequestError, ServiceUnavailableError];
+const terminalErrors = [PtyNotFoundError, ServiceUnavailableError];
+export const PersistentPtyGroup = HttpApiGroup.make("server.experimental")
+    .add(HttpApiEndpoint.get("persistentPty.read", "/api/experimental/session/:sessionID/terminal/read", {
+    params: { sessionID: Session.ID },
+    query: {
+        lines: Schema.NumberFromString.pipe(Schema.decodeTo(PersistentPty.ReadLines), Schema.optional),
+    },
+    success: Schema.Struct({ data: Schema.NullOr(PersistentPty.ReadResult) }),
+    error: [ServiceUnavailableError],
+}).annotateMerge(OpenApi.annotations({
+    summary: "Read the session's most recently controlled terminal",
+    description: "Read the last physical rows without changing selection or taking control. Omitted lines uses the live terminal height; larger counts include retained history. Blank rows are preserved. Screen dimensions and cursor remain relative to the live screen. Returns null when no current terminal exists. Selection is server-local and resets on restart. Experimental: may change without compatibility guarantees.",
+})))
+    .add(HttpApiEndpoint.get("persistentPty.list", "/api/experimental/session/:sessionID/terminal", {
+    params: { sessionID: Session.ID },
+    success: Schema.Struct({ data: Schema.Array(PersistentPty.Info) }),
+    error: errors,
+}))
+    .add(HttpApiEndpoint.post("persistentPty.create", "/api/experimental/session/:sessionID/terminal", {
+    params: { sessionID: Session.ID },
+    payload: PersistentPty.CreateInput,
+    success: Schema.Struct({ data: PersistentPty.Info }),
+    error: errors,
+}))
+    .add(HttpApiEndpoint.post("persistentPty.shutdown", "/api/experimental/persistent-pty/shutdown", {
+    success: HttpApiSchema.NoContent,
+    error: [ServiceUnavailableError],
+}))
+    .add(HttpApiEndpoint.post("persistentPty.handoff", "/api/experimental/persistent-pty/handoff", {
+    success: Schema.Struct({ handoff: Schema.NullOr(PersistentPty.Handoff) }),
+    error: [ServiceUnavailableError],
+}))
+    .add(HttpApiEndpoint.get("persistentPty.get", "/api/experimental/persistent-pty/:ptyID", {
+    params: { ptyID: Pty.ID },
+    success: Schema.Struct({ data: PersistentPty.Info }),
+    error: terminalErrors,
+}))
+    .add(HttpApiEndpoint.put("persistentPty.update", "/api/experimental/persistent-pty/:ptyID", {
+    params: { ptyID: Pty.ID },
+    payload: PersistentPty.UpdateInput,
+    success: Schema.Struct({ data: PersistentPty.Info }),
+    error: terminalErrors,
+}))
+    .add(HttpApiEndpoint.get("persistentPty.snapshot", "/api/experimental/persistent-pty/:ptyID/snapshot", {
+    params: { ptyID: Pty.ID },
+    success: Schema.Struct({ data: PersistentPty.Snapshot }),
+    error: terminalErrors,
+}))
+    .add(HttpApiEndpoint.delete("persistentPty.remove", "/api/experimental/persistent-pty/:ptyID", {
+    params: { ptyID: Pty.ID },
+    success: HttpApiSchema.NoContent,
+    error: terminalErrors,
+}))
+    .add(HttpApiEndpoint.post("persistentPty.connectToken", "/api/experimental/persistent-pty/:ptyID/connect-token", {
+    params: { ptyID: Pty.ID },
+    headers: Schema.Struct({ [PTY_CONNECT_TOKEN_HEADER]: Schema.optional(Schema.String) }),
+    success: Schema.Struct({ data: PtyTicket.ConnectToken }),
+    error: [ForbiddenError, PtyNotFoundError, ServiceUnavailableError],
+}))
+    .add(HttpApiEndpoint.get("persistentPty.connect", "/api/experimental/persistent-pty/:ptyID/connect", {
+    params: { ptyID: Pty.ID },
+    success: Schema.Boolean,
+    error: [ForbiddenError, PtyNotFoundError, ServiceUnavailableError],
+}).annotateMerge(OpenApi.annotations({
+    identifier: "v2.persistentPty.connect",
+    summary: "Connect to a persistent PTY",
+    description: "Stream persistent PTY output through the OpenCode server.",
+    transform: (operation) => ({
+        ...operation,
+        "x-websocket": true,
+        parameters: [
+            ...(operation.parameters ?? []),
+            ...["cursor", "role", "attachment_id", "takeover", "input_protocol", PTY_CONNECT_TICKET_QUERY].map((name) => ({ in: "query", name, schema: { type: "string" } })),
+        ],
+    }),
+})))
+    .annotateMerge(OpenApi.annotations({ title: "persistentPty", description: "Prototype persistent PTY routes." }));

package/dist/groups/plugin.d.ts

@@ -0,0 +1,91 @@
+import { Location } from "@opencode/schema/location";
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/unstable/httpapi";
+import { InvalidRequestError, ServiceUnavailableError } from "../errors.js";
+export declare const PluginGroup: HttpApiGroup.HttpApiGroup<"server.plugin", HttpApiEndpoint.HttpApiEndpoint<"plugin.list", "GET", "/api/plugin", never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly location: Schema.optional<Schema.Struct<{
+        readonly directory: Schema.optional<Schema.String>;
+        readonly workspace: Schema.optional<Schema.String>;
+    }>>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly location: typeof Location.Info;
+    readonly data: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.decodeTo<Schema.optional<Schema.toType<Schema.brand<Schema.String, "Plugin.ID">>>, Schema.optionalKey<Schema.brand<Schema.String, "Plugin.ID">>, never, never>;
+        readonly source: Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"builtin">;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"package">;
+            readonly target: Schema.String;
+            readonly version: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+            readonly outdated: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+            readonly updating: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"local">;
+            readonly path: Schema.String;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"sdk">;
+        }>]>;
+        readonly features: Schema.Struct<{
+            readonly server: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+            readonly tui: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+            readonly rpc: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+        }>;
+        readonly state: Schema.Union<readonly [Schema.Struct<{
+            readonly status: Schema.Literal<"active">;
+        }>, Schema.Struct<{
+            readonly status: Schema.Literal<"failed">;
+            readonly error: Schema.String;
+            readonly ref: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+        }>]>;
+    }>>;
+}>>, never, never, never> | HttpApiEndpoint.HttpApiEndpoint<"plugin.awaitActivation", "POST", "/api/plugin/await-activation", never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly location: Schema.optional<Schema.Struct<{
+        readonly directory: Schema.optional<Schema.String>;
+        readonly workspace: Schema.optional<Schema.String>;
+    }>>;
+}>>, never, never, Schema.toCodecJson<HttpApiSchema.NoContent>, never, never, never> | HttpApiEndpoint.HttpApiEndpoint<"plugin.check", "POST", "/api/plugin/check", never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly location: Schema.optional<Schema.Struct<{
+        readonly directory: Schema.optional<Schema.String>;
+        readonly workspace: Schema.optional<Schema.String>;
+    }>>;
+}>>, Schema.toCodecJson<Schema.Struct<{
+    readonly target: Schema.optional<Schema.String>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly location: typeof Location.Info;
+    readonly data: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.decodeTo<Schema.optional<Schema.toType<Schema.brand<Schema.String, "Plugin.ID">>>, Schema.optionalKey<Schema.brand<Schema.String, "Plugin.ID">>, never, never>;
+        readonly source: Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"builtin">;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"package">;
+            readonly target: Schema.String;
+            readonly version: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+            readonly outdated: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+            readonly updating: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"local">;
+            readonly path: Schema.String;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"sdk">;
+        }>]>;
+        readonly features: Schema.Struct<{
+            readonly server: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+            readonly tui: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+            readonly rpc: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Literal<true>>>, Schema.optionalKey<Schema.Literal<true>>, never, never>;
+        }>;
+        readonly state: Schema.Union<readonly [Schema.Struct<{
+            readonly status: Schema.Literal<"active">;
+        }>, Schema.Struct<{
+            readonly status: Schema.Literal<"failed">;
+            readonly error: Schema.String;
+            readonly ref: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+        }>]>;
+    }>>;
+}>>, Schema.toCodecJson<typeof InvalidRequestError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"plugin.update", "POST", "/api/plugin/update", never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly location: Schema.optional<Schema.Struct<{
+        readonly directory: Schema.optional<Schema.String>;
+        readonly workspace: Schema.optional<Schema.String>;
+    }>>;
+}>>, Schema.toCodecJson<Schema.Struct<{
+    readonly targets: Schema.$Array<Schema.String>;
+}>>, never, Schema.toCodecJson<HttpApiSchema.NoContent>, Schema.toCodecJson<typeof InvalidRequestError | typeof ServiceUnavailableError>, never, never>, false>;

package/dist/groups/plugin.js

@@ -0,0 +1,55 @@
+import { Location } from "@opencode/schema/location";
+import { Plugin } from "@opencode/schema/plugin";
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+import { InvalidRequestError, ServiceUnavailableError } from "../errors.js";
+import { LocationQuery, locationQueryOpenApi } from "./location.js";
+export const PluginGroup = HttpApiGroup.make("server.plugin")
+    .add(HttpApiEndpoint.get("plugin.list", "/api/plugin", {
+    query: LocationQuery,
+    success: Location.response(Schema.Array(Plugin.Info)),
+})
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.plugin.list",
+    summary: "List plugins",
+    description: "Retrieve enabled server plugins and their current status.",
+})))
+    .add(HttpApiEndpoint.post("plugin.awaitActivation", "/api/plugin/await-activation", {
+    query: LocationQuery,
+    success: HttpApiSchema.NoContent,
+})
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.plugin.awaitActivation",
+    summary: "Wait for plugin activation",
+    description: "Wait for configured plugin activation at a Location to settle, including missing-package installs. Completion does not imply every plugin succeeded or background resource discovery finished. Cancelling this wait does not cancel activation.",
+})))
+    .add(HttpApiEndpoint.post("plugin.check", "/api/plugin/check", {
+    query: LocationQuery,
+    payload: Schema.Struct({ target: Schema.String.pipe(Schema.optional) }),
+    success: Location.response(Schema.Array(Plugin.Info)),
+    error: InvalidRequestError,
+})
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.plugin.check",
+    summary: "Check plugin updates",
+    description: "Check one or all package plugins for available updates.",
+})))
+    .add(HttpApiEndpoint.post("plugin.update", "/api/plugin/update", {
+    query: LocationQuery,
+    payload: Schema.Struct({ targets: Schema.Array(Schema.String) }),
+    success: HttpApiSchema.NoContent,
+    error: [InvalidRequestError, ServiceUnavailableError],
+})
+    .annotateMerge(locationQueryOpenApi)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "v2.plugin.update",
+    summary: "Update plugins",
+    description: "Update package plugins concurrently and notify active locations to reload them. Responds once every update has finished; fails when any update fails.",
+})))
+    .annotateMerge(OpenApi.annotations({
+    title: "plugin",
+    description: "Experimental plugin routes.",
+}));