@kilocode/protocol 0.0.0-stage → 0.0.0-v2-9

package/dist/groups/permission.d.ts

@@ -0,0 +1,175 @@
+import { Context, Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema } from "effect/http-api";
+import { ConflictError, LocationNotFoundError, PermissionNotFoundError, PermissionSavedNotFoundError, SessionNotFoundError } from "../errors.js";
+export declare const makePermissionGroup: <LocationId extends HttpApiMiddleware.AnyId, LocationService, SessionLocationId extends HttpApiMiddleware.AnyId, SessionLocationService>(locationMiddleware: Context.Key<LocationId, LocationService>, sessionLocationMiddleware: Context.Key<SessionLocationId, SessionLocationService>) => HttpApiGroup.HttpApiGroup<"server.permission", HttpApiEndpoint.HttpApiEndpoint<"permission.request.list", "GET", "/api/permission/request", never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly location: Schema.optional<Schema.Struct<{
+        readonly directory: Schema.optional<Schema.String>;
+    }>>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly location: Schema.Struct<{
+        readonly directory: Schema.brand<Schema.String, "AbsolutePath">;
+    }>;
+    readonly data: Schema.$Array<Schema.Struct<{
+        readonly sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => string & import("effect/Brand").Brand<"SessionID">;
+        };
+        readonly action: Schema.String;
+        readonly resources: Schema.$Array<Schema.String>;
+        readonly save: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+        readonly metadata: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Record<Schema.String, Schema.Unknown>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>, never, never>;
+        readonly source: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"tool">;
+            readonly messageID: Schema.String;
+            readonly id: Schema.String;
+        }>]>>>, Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"tool">;
+            readonly messageID: Schema.String;
+            readonly id: Schema.String;
+        }>]>>, never, never>;
+        readonly message: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+        readonly id: Schema.brand<Schema.String, "Permission.ID"> & {
+            create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+        };
+    }>>;
+}>>, never, LocationId, HttpApiMiddleware.Requires<LocationId>> | HttpApiEndpoint.HttpApiEndpoint<"permission.saved.list", "GET", "/api/permission/saved", never, Schema.toCodecStringTree<Schema.Struct<{
+    readonly projectID: Schema.optional<Schema.brand<Schema.String, "Project.ID"> & {
+        global: string & import("effect/Brand").Brand<"Project.ID">;
+    }>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.brand<Schema.String, "PermissionSaved.ID"> & {
+            create: () => string & import("effect/Brand").Brand<"PermissionSaved.ID">;
+        };
+        readonly projectID: Schema.brand<Schema.String, "Project.ID"> & {
+            global: string & import("effect/Brand").Brand<"Project.ID">;
+        };
+        readonly action: Schema.String;
+        readonly resource: Schema.String;
+        readonly time: Schema.Struct<{
+            readonly created: Schema.decodeTo<Schema.DateTimeUtc, Schema.Finite, never, never>;
+            readonly updated: Schema.decodeTo<Schema.DateTimeUtc, Schema.Finite, never, never>;
+        }>;
+    }>>;
+}>>, never, LocationId, HttpApiMiddleware.Requires<LocationId>> | HttpApiEndpoint.HttpApiEndpoint<"permission.saved.remove", "DELETE", "/api/permission/saved/:id", Schema.toCodecStringTree<Schema.Struct<{
+    id: Schema.brand<Schema.String, "PermissionSaved.ID"> & {
+        create: () => string & import("effect/Brand").Brand<"PermissionSaved.ID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<HttpApiSchema.NoContent>, never, LocationId, HttpApiMiddleware.Requires<LocationId>> | HttpApiEndpoint.HttpApiEndpoint<"permission.saved.update", "PATCH", "/api/permission/saved/:id", Schema.toCodecStringTree<Schema.Struct<{
+    id: Schema.brand<Schema.String, "PermissionSaved.ID"> & {
+        create: () => string & import("effect/Brand").Brand<"PermissionSaved.ID">;
+    };
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly action: Schema.optional<Schema.String>;
+    readonly resource: Schema.optional<Schema.String>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly id: Schema.brand<Schema.String, "PermissionSaved.ID"> & {
+            create: () => string & import("effect/Brand").Brand<"PermissionSaved.ID">;
+        };
+        readonly projectID: Schema.brand<Schema.String, "Project.ID"> & {
+            global: string & import("effect/Brand").Brand<"Project.ID">;
+        };
+        readonly action: Schema.String;
+        readonly resource: Schema.String;
+        readonly time: Schema.Struct<{
+            readonly created: Schema.decodeTo<Schema.DateTimeUtc, Schema.Finite, never, never>;
+            readonly updated: Schema.decodeTo<Schema.DateTimeUtc, Schema.Finite, never, never>;
+        }>;
+    }>;
+}>>, Schema.toCodecJson<typeof ConflictError | typeof PermissionSavedNotFoundError>, LocationId, HttpApiMiddleware.Requires<LocationId>> | HttpApiEndpoint.HttpApiEndpoint<"session.permission.create", "POST", "/api/session/:sessionID/permission", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+    };
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly id: Schema.optional<Schema.brand<Schema.String, "Permission.ID"> & {
+        create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+    }>;
+    readonly action: Schema.String;
+    readonly resources: Schema.$Array<Schema.String>;
+    readonly save: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+    readonly metadata: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Record<Schema.String, Schema.Unknown>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>, never, never>;
+    readonly source: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"tool">;
+        readonly messageID: Schema.String;
+        readonly id: Schema.String;
+    }>]>>>, Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"tool">;
+        readonly messageID: Schema.String;
+        readonly id: Schema.String;
+    }>]>>, never, never>;
+    readonly agent: Schema.optional<Schema.brand<Schema.String, "Agent.ID">>;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly id: Schema.brand<Schema.String, "Permission.ID"> & {
+            create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+        };
+        readonly effect: Schema.Literals<readonly ["allow", "deny", "ask"]>;
+    }>;
+}>>, Schema.toCodecJson<typeof SessionNotFoundError>, SessionLocationId, HttpApiMiddleware.Requires<SessionLocationId>> | HttpApiEndpoint.HttpApiEndpoint<"session.permission.get", "GET", "/api/session/:sessionID/permission/:requestID", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+    };
+    requestID: Schema.brand<Schema.String, "Permission.ID"> & {
+        create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+    };
+}>>, 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">;
+        };
+        readonly action: Schema.String;
+        readonly resources: Schema.$Array<Schema.String>;
+        readonly save: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+        readonly metadata: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Record<Schema.String, Schema.Unknown>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>, never, never>;
+        readonly source: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"tool">;
+            readonly messageID: Schema.String;
+            readonly id: Schema.String;
+        }>]>>>, Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"tool">;
+            readonly messageID: Schema.String;
+            readonly id: Schema.String;
+        }>]>>, never, never>;
+        readonly message: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+        readonly id: Schema.brand<Schema.String, "Permission.ID"> & {
+            create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+        };
+    }>;
+}>>, Schema.toCodecJson<typeof SessionNotFoundError | typeof PermissionNotFoundError>, SessionLocationId, HttpApiMiddleware.Requires<SessionLocationId>> | HttpApiEndpoint.HttpApiEndpoint<"session.permission.list", "GET", "/api/session/:sessionID/permission", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => 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">;
+        };
+        readonly action: Schema.String;
+        readonly resources: Schema.$Array<Schema.String>;
+        readonly save: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Array<Schema.String>>>, Schema.optionalKey<Schema.$Array<Schema.String>>, never, never>;
+        readonly metadata: Schema.decodeTo<Schema.optional<Schema.toType<Schema.$Record<Schema.String, Schema.Unknown>>>, Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>, never, never>;
+        readonly source: Schema.decodeTo<Schema.optional<Schema.toType<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"tool">;
+            readonly messageID: Schema.String;
+            readonly id: Schema.String;
+        }>]>>>, Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"tool">;
+            readonly messageID: Schema.String;
+            readonly id: Schema.String;
+        }>]>>, never, never>;
+        readonly message: Schema.decodeTo<Schema.optional<Schema.toType<Schema.String>>, Schema.optionalKey<Schema.String>, never, never>;
+        readonly id: Schema.brand<Schema.String, "Permission.ID"> & {
+            create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+        };
+    }>>;
+}>>, Schema.toCodecJson<typeof LocationNotFoundError | typeof SessionNotFoundError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"session.permission.reply", "POST", "/api/session/:sessionID/permission/:requestID/reply", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+    };
+    requestID: Schema.brand<Schema.String, "Permission.ID"> & {
+        create: (id?: string) => string & import("effect/Brand").Brand<"Permission.ID">;
+    };
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly decision: Schema.Literals<readonly ["once", "always", "reject"]>;
+    readonly message: Schema.optional<Schema.String>;
+}>>, never, Schema.toCodecJson<HttpApiSchema.NoContent>, Schema.toCodecJson<typeof SessionNotFoundError | typeof PermissionNotFoundError>, SessionLocationId, HttpApiMiddleware.Requires<SessionLocationId>>, false>;

package/dist/groups/permission.js

@@ -0,0 +1,110 @@
+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/http-api";
+import { ConflictError, LocationNotFoundError, PermissionNotFoundError, PermissionSavedNotFoundError, 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: "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: "permission.saved.list",
+    summary: "List saved permissions",
+    description: "Retrieve saved permissions, optionally filtered by project.",
+})))
+    .add(HttpApiEndpoint.patch("permission.saved.update", "/api/permission/saved/:id", {
+    params: { id: PermissionSaved.ID },
+    payload: Schema.Struct({
+        action: Schema.String.pipe(Schema.optional),
+        resource: Schema.String.pipe(Schema.optional),
+    }),
+    success: Schema.Struct({ data: PermissionSaved.Info }),
+    error: [PermissionSavedNotFoundError, ConflictError],
+}).annotateMerge(OpenApi.annotations({
+    identifier: "permission.saved.update",
+    summary: "Update saved permission",
+    description: "Change the action or resource of a saved permission. Fails with a conflict when the project already has a saved permission with the same action and resource.",
+})))
+    .add(HttpApiEndpoint.delete("permission.saved.remove", "/api/permission/saved/:id", {
+    params: { id: PermissionSaved.ID },
+    success: HttpApiSchema.NoContent,
+}).annotateMerge(OpenApi.annotations({
+    identifier: "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: "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, LocationNotFoundError],
+}).annotateMerge(OpenApi.annotations({
+    identifier: "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: "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({
+        decision: Permission.Reply,
+        message: Schema.String.pipe(Schema.optional),
+    }),
+    success: HttpApiSchema.NoContent,
+    error: [SessionNotFoundError, PermissionNotFoundError],
+})
+    .middleware(sessionLocationMiddleware)
+    .annotateMerge(OpenApi.annotations({
+    identifier: "session.permission.reply",
+    summary: "Reply to pending permission request",
+    description: "Respond to a pending permission request owned by a session.",
+})))
+    .annotateMerge(OpenApi.annotations({ title: "permission", description: "Experimental permission routes." }));

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

@@ -0,0 +1,242 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api";
+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 const PERSISTENT_PTY_CONNECT_PATH = "/api/experimental/persistent-pty/:ptyID/connect";
+export declare function hasPersistentPtyConnectTicketURL(url: URL): boolean;
+export declare const PersistentPtyGroup: HttpApiGroup.HttpApiGroup<"server.experimental", 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> | 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.create", "POST", "/api/experimental/session/:sessionID/terminal", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => 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 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 sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => 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;
+        }>;
+    }>;
+}>>, Schema.toCodecJson<typeof InvalidRequestError | 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 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 sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => 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;
+        }>;
+    }>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof PtyNotFoundError>, 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.list", "GET", "/api/experimental/session/:sessionID/terminal", Schema.toCodecStringTree<Schema.Struct<{
+    sessionID: Schema.brand<Schema.String, "SessionID"> & {
+        create: () => string & import("effect/Brand").Brand<"SessionID">;
+    };
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly data: Schema.$Array<Schema.Struct<{
+        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 sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => 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;
+        }>;
+    }>>;
+}>>, Schema.toCodecJson<typeof InvalidRequestError | typeof ServiceUnavailableError>, never, never> | 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">;
+    };
+}>>, 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.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.shutdown", "POST", "/api/experimental/persistent-pty/shutdown", never, never, never, never, Schema.toCodecJson<HttpApiSchema.NoContent>, Schema.toCodecJson<typeof ServiceUnavailableError>, 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 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 sessionID: Schema.brand<Schema.String, "SessionID"> & {
+                create: () => 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 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.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 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 sessionID: Schema.brand<Schema.String, "SessionID"> & {
+            create: () => 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;
+        }>;
+    }>;
+}>>, Schema.toCodecJson<typeof ServiceUnavailableError | typeof PtyNotFoundError>, never, never>, false>;

package/dist/groups/persistent-pty.js

@@ -0,0 +1,92 @@
+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/http-api";
+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 const PERSISTENT_PTY_CONNECT_PATH = "/api/experimental/persistent-pty/:ptyID/connect";
+const PERSISTENT_PTY_CONNECT_URL = /^\/api\/experimental\/persistent-pty\/[^/]+\/connect$/;
+export function hasPersistentPtyConnectTicketURL(url) {
+    return PERSISTENT_PTY_CONNECT_URL.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", PERSISTENT_PTY_CONNECT_PATH, {
+    params: { ptyID: Pty.ID },
+    success: Schema.Boolean,
+    error: [ForbiddenError, PtyNotFoundError, ServiceUnavailableError],
+}).annotateMerge(OpenApi.annotations({
+    identifier: "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." }));