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

package/dist/core-api/sessions.d.ts

@@ -0,0 +1,390 @@
+/**
+ * Interactive session wire contracts — first-class PTY sessions over a live workspace.
+ *
+ * A session is a daemon-owned PTY (it survives control-connection drops); the control plane holds
+ * the durable row and drives every verb over short-lived per-daemon-request connections, so any
+ * API instance can serve any session. Output is DURABLE and SEQUENCE-KEYED: the session's run
+ * record ingests the PTY byte stream (redacted, byte-exact), and the output endpoints serve it by
+ * sequence range — which is what makes detach/reattach and byte-exact history replay work. The
+ * live tail is served as SSE by `GET /v1/sessions/:sessionId/output/stream` (implemented as a raw
+ * streaming route on the same server, outside this schema-derived contract).
+ *
+ * AUTHORIZATION: the session surface enforces scoped bearer tokens when one is presented —
+ * `session:read` (status/output), `session:input` (input/resize/signal), `workspace:exec`
+ * (create/close). Without a bearer token the pre-auth owner model applies unchanged.
+ */
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+export declare const sessionStatusSchema: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+export type SessionStatusWire = typeof sessionStatusSchema.Type;
+export declare const sessionAuthorizationHeadersSchema: Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>;
+export type SessionAuthorizationHeaders = typeof sessionAuthorizationHeadersSchema.Type;
+/**
+ * How a session's leader is wired. `pty` (default) allocates a pseudoterminal — interactive
+ * shells and TUIs. `pipe` gives the leader plain stdio pipes and no tty — the shape for processes
+ * that speak a byte protocol over stdin/stdout (JSON-RPC / NDJSON servers): stdout is the recorded,
+ * attachable output, stderr is recorded as diagnostics only, input feeds stdin, and resize is
+ * rejected.
+ */
+export declare const sessionModeSchema: Schema.Literals<readonly ["pty", "pipe"]>;
+export type SessionMode = typeof sessionModeSchema.Type;
+export declare const createSessionRequestSchema: Schema.Struct<{
+    readonly workspaceId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    /** argv[0] is the program the session runs; the rest its arguments. */
+    readonly argv: Schema.$Array<Schema.String>;
+    /** Working directory inside the workspace (defaults to the workspace working directory). */
+    readonly cwd: Schema.optional<Schema.String>;
+    /** Extra environment for the PTY process (values are NOT secrets — use credentials for those). */
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly cols: Schema.optional<Schema.Int>;
+    readonly rows: Schema.optional<Schema.Int>;
+    readonly term: Schema.optional<Schema.String>;
+    /** Leader wiring; defaults to `pty`. `cols`/`rows`/`term` are ignored for `pipe`. */
+    readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+    /** Opaque caller correlation bag: stored verbatim, echoed on reads, no platform semantics. */
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+export type CreateSessionRequest = typeof createSessionRequestSchema.Type;
+export declare const sessionSchema: Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly workspaceId: Schema.String;
+    /** The interactive run recording this session; its record is the durable evidence. */
+    readonly runId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+    readonly argv: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly cols: Schema.Number;
+    readonly rows: Schema.Number;
+    /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+    readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+    readonly exitCode: Schema.optional<Schema.Number>;
+    readonly exitSignal: Schema.optional<Schema.Number>;
+    readonly errorMessage: Schema.optional<Schema.String>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+    /**
+     * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+     * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+     * where a previous reader stopped.
+     */
+    readonly outputHighWater: Schema.String;
+    readonly createdAt: Schema.String;
+    readonly endedAt: Schema.optional<Schema.String>;
+}>;
+export type SessionWire = typeof sessionSchema.Type;
+export declare const listSessionsQuerySchema: Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+    readonly workspaceId: Schema.optional<Schema.String>;
+    readonly status: Schema.optional<Schema.Literals<readonly ["starting", "running", "exited", "failed"]>>;
+    readonly limit: Schema.optional<Schema.String>;
+}>;
+export type ListSessionsQuery = typeof listSessionsQuerySchema.Type;
+export declare const listSessionsResponseSchema: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly sessionId: Schema.String;
+        readonly workspaceId: Schema.String;
+        /** The interactive run recording this session; its record is the durable evidence. */
+        readonly runId: Schema.String;
+        readonly ownerUserId: Schema.String;
+        readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+        readonly argv: Schema.$Array<Schema.String>;
+        readonly cwd: Schema.optional<Schema.String>;
+        readonly cols: Schema.Number;
+        readonly rows: Schema.Number;
+        /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+        readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+        readonly exitCode: Schema.optional<Schema.Number>;
+        readonly exitSignal: Schema.optional<Schema.Number>;
+        readonly errorMessage: Schema.optional<Schema.String>;
+        readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+        /**
+         * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+         * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+         * where a previous reader stopped.
+         */
+        readonly outputHighWater: Schema.String;
+        readonly createdAt: Schema.String;
+        readonly endedAt: Schema.optional<Schema.String>;
+    }>>;
+}>;
+export type ListSessionsResponse = typeof listSessionsResponseSchema.Type;
+export declare const sessionInputRequestSchema: Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    /** Base64-encoded keystrokes (bytes, not text — binary-safe). */
+    readonly dataBase64: Schema.String;
+}>;
+export type SessionInputRequest = typeof sessionInputRequestSchema.Type;
+export declare const sessionResizeRequestSchema: Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    readonly cols: Schema.Int;
+    readonly rows: Schema.Int;
+}>;
+export type SessionResizeRequest = typeof sessionResizeRequestSchema.Type;
+export declare const sessionSignalRequestSchema: Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    /** POSIX signal number (e.g. 2 = SIGINT, 15 = SIGTERM). */
+    readonly signal: Schema.Int;
+}>;
+export type SessionSignalRequest = typeof sessionSignalRequestSchema.Type;
+export declare const closeSessionRequestSchema: Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+}>;
+export type CloseSessionRequest = typeof closeSessionRequestSchema.Type;
+/**
+ * Byte-exact session output by sequence range. `from` is INCLUSIVE (omit = from the beginning);
+ * chunks carry their sequence so a disconnected reader resumes with `lastSequence + 1`. Output is
+ * as-recorded: redacted upstream by the daemon, PTY output stream only.
+ */
+export declare const getSessionOutputQuerySchema: Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    readonly from: Schema.optional<Schema.String>;
+    readonly limit: Schema.optional<Schema.String>;
+}>;
+export type GetSessionOutputQuery = typeof getSessionOutputQuerySchema.Type;
+export declare const sessionOutputChunkSchema: Schema.Struct<{
+    readonly sequence: Schema.String;
+    /** Base64-encoded PTY output bytes, exactly as recorded. */
+    readonly dataBase64: Schema.String;
+}>;
+export type SessionOutputChunk = typeof sessionOutputChunkSchema.Type;
+export declare const sessionOutputResponseSchema: Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly chunks: Schema.$Array<Schema.Struct<{
+        readonly sequence: Schema.String;
+        /** Base64-encoded PTY output bytes, exactly as recorded. */
+        readonly dataBase64: Schema.String;
+    }>>;
+    /** The cursor to pass as `from` to continue after this page. */
+    readonly nextFrom: Schema.String;
+    /** Session status at read time, so pollers can stop when the session settles. */
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+}>;
+export type SessionOutputResponse = typeof sessionOutputResponseSchema.Type;
+declare const SessionBadRequestError_base: Schema.Class<SessionBadRequestError, Schema.TaggedStruct<"SessionBadRequestError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionBadRequestError extends SessionBadRequestError_base {
+}
+declare const SessionUnauthorizedError_base: Schema.Class<SessionUnauthorizedError, Schema.TaggedStruct<"SessionUnauthorizedError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionUnauthorizedError extends SessionUnauthorizedError_base {
+}
+declare const SessionForbiddenError_base: Schema.Class<SessionForbiddenError, Schema.TaggedStruct<"SessionForbiddenError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionForbiddenError extends SessionForbiddenError_base {
+}
+declare const SessionNotFoundError_base: Schema.Class<SessionNotFoundError, Schema.TaggedStruct<"SessionNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionNotFoundError extends SessionNotFoundError_base {
+}
+declare const SessionConflictError_base: Schema.Class<SessionConflictError, Schema.TaggedStruct<"SessionConflictError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionConflictError extends SessionConflictError_base {
+}
+declare const SessionBadGatewayError_base: Schema.Class<SessionBadGatewayError, Schema.TaggedStruct<"SessionBadGatewayError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionBadGatewayError extends SessionBadGatewayError_base {
+}
+declare const SessionInternalServerError_base: Schema.Class<SessionInternalServerError, Schema.TaggedStruct<"SessionInternalServerError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class SessionInternalServerError extends SessionInternalServerError_base {
+}
+export declare const SessionsGroup: HttpApiGroup.HttpApiGroup<"sessions", HttpApiEndpoint.HttpApiEndpoint<"closeSession", "POST", "/:sessionId/close", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sessionId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly workspaceId: Schema.String;
+    /** The interactive run recording this session; its record is the durable evidence. */
+    readonly runId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+    readonly argv: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly cols: Schema.Number;
+    readonly rows: Schema.Number;
+    /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+    readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+    readonly exitCode: Schema.optional<Schema.Number>;
+    readonly exitSignal: Schema.optional<Schema.Number>;
+    readonly errorMessage: Schema.optional<Schema.String>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+    /**
+     * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+     * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+     * where a previous reader stopped.
+     */
+    readonly outputHighWater: Schema.String;
+    readonly createdAt: Schema.String;
+    readonly endedAt: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"createSession", "POST", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly workspaceId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    /** argv[0] is the program the session runs; the rest its arguments. */
+    readonly argv: Schema.$Array<Schema.String>;
+    /** Working directory inside the workspace (defaults to the workspace working directory). */
+    readonly cwd: Schema.optional<Schema.String>;
+    /** Extra environment for the PTY process (values are NOT secrets — use credentials for those). */
+    readonly env: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly cols: Schema.optional<Schema.Int>;
+    readonly rows: Schema.optional<Schema.Int>;
+    readonly term: Schema.optional<Schema.String>;
+    /** Leader wiring; defaults to `pty`. `cols`/`rows`/`term` are ignored for `pipe`. */
+    readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+    /** Opaque caller correlation bag: stored verbatim, echoed on reads, no platform semantics. */
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly workspaceId: Schema.String;
+    /** The interactive run recording this session; its record is the durable evidence. */
+    readonly runId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+    readonly argv: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly cols: Schema.Number;
+    readonly rows: Schema.Number;
+    /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+    readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+    readonly exitCode: Schema.optional<Schema.Number>;
+    readonly exitSignal: Schema.optional<Schema.Number>;
+    readonly errorMessage: Schema.optional<Schema.String>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+    /**
+     * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+     * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+     * where a previous reader stopped.
+     */
+    readonly outputHighWater: Schema.String;
+    readonly createdAt: Schema.String;
+    readonly endedAt: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionConflictError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getSession", "GET", "/:sessionId", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sessionId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly workspaceId: Schema.String;
+    /** The interactive run recording this session; its record is the durable evidence. */
+    readonly runId: Schema.String;
+    readonly ownerUserId: Schema.String;
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+    readonly argv: Schema.$Array<Schema.String>;
+    readonly cwd: Schema.optional<Schema.String>;
+    readonly cols: Schema.Number;
+    readonly rows: Schema.Number;
+    /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+    readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+    readonly exitCode: Schema.optional<Schema.Number>;
+    readonly exitSignal: Schema.optional<Schema.Number>;
+    readonly errorMessage: Schema.optional<Schema.String>;
+    readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+    /**
+     * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+     * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+     * where a previous reader stopped.
+     */
+    readonly outputHighWater: Schema.String;
+    readonly createdAt: Schema.String;
+    readonly endedAt: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getSessionOutput", "GET", "/:sessionId/output", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sessionId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    readonly from: Schema.optional<Schema.String>;
+    readonly limit: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly sessionId: Schema.String;
+    readonly chunks: Schema.$Array<Schema.Struct<{
+        readonly sequence: Schema.String;
+        /** Base64-encoded PTY output bytes, exactly as recorded. */
+        readonly dataBase64: Schema.String;
+    }>>;
+    /** The cursor to pass as `from` to continue after this page. */
+    readonly nextFrom: Schema.String;
+    /** Session status at read time, so pollers can stop when the session settles. */
+    readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listSessions", "GET", "/", HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly ownerUserId: Schema.String;
+    readonly workspaceId: Schema.optional<Schema.String>;
+    readonly status: Schema.optional<Schema.Literals<readonly ["starting", "running", "exited", "failed"]>>;
+    readonly limit: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly sessionId: Schema.String;
+        readonly workspaceId: Schema.String;
+        /** The interactive run recording this session; its record is the durable evidence. */
+        readonly runId: Schema.String;
+        readonly ownerUserId: Schema.String;
+        readonly status: Schema.Literals<readonly ["starting", "running", "exited", "failed"]>;
+        readonly argv: Schema.$Array<Schema.String>;
+        readonly cwd: Schema.optional<Schema.String>;
+        readonly cols: Schema.Number;
+        readonly rows: Schema.Number;
+        /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+        readonly mode: Schema.optional<Schema.Literals<readonly ["pty", "pipe"]>>;
+        readonly exitCode: Schema.optional<Schema.Number>;
+        readonly exitSignal: Schema.optional<Schema.Number>;
+        readonly errorMessage: Schema.optional<Schema.String>;
+        readonly metadata: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
+        /**
+         * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+         * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+         * where a previous reader stopped.
+         */
+        readonly outputHighWater: Schema.String;
+        readonly createdAt: Schema.String;
+        readonly endedAt: Schema.optional<Schema.String>;
+    }>>;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"resizeSession", "POST", "/:sessionId/resize", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sessionId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    readonly cols: Schema.Int;
+    readonly rows: Schema.Int;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ok: Schema.Boolean;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionConflictError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"sendSessionInput", "POST", "/:sessionId/input", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sessionId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    /** Base64-encoded keystrokes (bytes, not text — binary-safe). */
+    readonly dataBase64: Schema.String;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ok: Schema.Boolean;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionConflictError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"signalSession", "POST", "/:sessionId/signal", HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly sessionId: Schema.String;
+}>>, HttpApiEndpoint.StringTree<never>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ownerUserId: Schema.optional<Schema.String>;
+    /** POSIX signal number (e.g. 2 = SIGINT, 15 = SIGTERM). */
+    readonly signal: Schema.Int;
+}>>, HttpApiEndpoint.StringTree<Schema.Struct<{
+    readonly authorization: Schema.optional<Schema.String>;
+}>>, HttpApiEndpoint.Json<Schema.Struct<{
+    readonly ok: Schema.Boolean;
+}>>, HttpApiEndpoint.Json<typeof SessionBadRequestError | typeof SessionUnauthorizedError | typeof SessionForbiddenError | typeof SessionNotFoundError | typeof SessionConflictError | typeof SessionBadGatewayError | typeof SessionInternalServerError>, never, never>, false>;
+export {};

package/dist/core-api/sessions.js

@@ -0,0 +1,264 @@
+/**
+ * Interactive session wire contracts — first-class PTY sessions over a live workspace.
+ *
+ * A session is a daemon-owned PTY (it survives control-connection drops); the control plane holds
+ * the durable row and drives every verb over short-lived per-daemon-request connections, so any
+ * API instance can serve any session. Output is DURABLE and SEQUENCE-KEYED: the session's run
+ * record ingests the PTY byte stream (redacted, byte-exact), and the output endpoints serve it by
+ * sequence range — which is what makes detach/reattach and byte-exact history replay work. The
+ * live tail is served as SSE by `GET /v1/sessions/:sessionId/output/stream` (implemented as a raw
+ * streaming route on the same server, outside this schema-derived contract).
+ *
+ * AUTHORIZATION: the session surface enforces scoped bearer tokens when one is presented —
+ * `session:read` (status/output), `session:input` (input/resize/signal), `workspace:exec`
+ * (create/close). Without a bearer token the pre-auth owner model applies unchanged.
+ */
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+const NonEmptyString = Schema.String.check(Schema.isNonEmpty(), Schema.isTrimmed());
+export const sessionStatusSchema = Schema.Literals(["starting", "running", "exited", "failed"]);
+export const sessionAuthorizationHeadersSchema = Schema.Struct({
+    authorization: Schema.optional(Schema.String),
+});
+/**
+ * How a session's leader is wired. `pty` (default) allocates a pseudoterminal — interactive
+ * shells and TUIs. `pipe` gives the leader plain stdio pipes and no tty — the shape for processes
+ * that speak a byte protocol over stdin/stdout (JSON-RPC / NDJSON servers): stdout is the recorded,
+ * attachable output, stderr is recorded as diagnostics only, input feeds stdin, and resize is
+ * rejected.
+ */
+export const sessionModeSchema = Schema.Literals(["pty", "pipe"]);
+export const createSessionRequestSchema = Schema.Struct({
+    workspaceId: NonEmptyString,
+    ownerUserId: NonEmptyString,
+    /** argv[0] is the program the session runs; the rest its arguments. */
+    argv: Schema.Array(NonEmptyString).check(Schema.isNonEmpty(), Schema.isMaxLength(64)),
+    /** Working directory inside the workspace (defaults to the workspace working directory). */
+    cwd: Schema.optional(NonEmptyString),
+    /** Extra environment for the PTY process (values are NOT secrets — use credentials for those). */
+    env: Schema.optional(Schema.Record(Schema.String, Schema.String)),
+    cols: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+    rows: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+    term: Schema.optional(NonEmptyString),
+    /** Leader wiring; defaults to `pty`. `cols`/`rows`/`term` are ignored for `pipe`. */
+    mode: Schema.optional(sessionModeSchema),
+    /** Opaque caller correlation bag: stored verbatim, echoed on reads, no platform semantics. */
+    metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+});
+export const sessionSchema = Schema.Struct({
+    sessionId: NonEmptyString,
+    workspaceId: NonEmptyString,
+    /** The interactive run recording this session; its record is the durable evidence. */
+    runId: NonEmptyString,
+    ownerUserId: NonEmptyString,
+    status: sessionStatusSchema,
+    argv: Schema.Array(Schema.String),
+    cwd: Schema.optional(NonEmptyString),
+    cols: Schema.Number,
+    rows: Schema.Number,
+    /** Leader wiring. Absent on servers from before pipe mode shipped, which means `pty`. */
+    mode: Schema.optional(sessionModeSchema),
+    exitCode: Schema.optional(Schema.Number),
+    exitSignal: Schema.optional(Schema.Number),
+    errorMessage: Schema.optional(Schema.String),
+    metadata: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+    /**
+     * Highest ingested output sequence for this session's run (decimal string), or "0" when nothing
+     * has been ingested yet — the resume cursor: `output?from=<highWater + 1>` continues exactly
+     * where a previous reader stopped.
+     */
+    outputHighWater: NonEmptyString,
+    createdAt: Schema.String,
+    endedAt: Schema.optional(Schema.String),
+});
+export const listSessionsQuerySchema = Schema.Struct({
+    ownerUserId: NonEmptyString,
+    workspaceId: Schema.optional(NonEmptyString),
+    status: Schema.optional(sessionStatusSchema),
+    limit: Schema.optional(NonEmptyString),
+});
+export const listSessionsResponseSchema = Schema.Struct({
+    items: Schema.Array(sessionSchema),
+});
+export const sessionInputRequestSchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+    /** Base64-encoded keystrokes (bytes, not text — binary-safe). */
+    dataBase64: NonEmptyString,
+});
+export const sessionResizeRequestSchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+    cols: Schema.Int.check(Schema.isGreaterThan(0)),
+    rows: Schema.Int.check(Schema.isGreaterThan(0)),
+});
+export const sessionSignalRequestSchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+    /** POSIX signal number (e.g. 2 = SIGINT, 15 = SIGTERM). */
+    signal: Schema.Int.check(Schema.isGreaterThan(0)),
+});
+export const closeSessionRequestSchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+});
+/**
+ * Byte-exact session output by sequence range. `from` is INCLUSIVE (omit = from the beginning);
+ * chunks carry their sequence so a disconnected reader resumes with `lastSequence + 1`. Output is
+ * as-recorded: redacted upstream by the daemon, PTY output stream only.
+ */
+export const getSessionOutputQuerySchema = Schema.Struct({
+    ownerUserId: Schema.optional(NonEmptyString),
+    from: Schema.optional(NonEmptyString),
+    limit: Schema.optional(NonEmptyString),
+});
+export const sessionOutputChunkSchema = Schema.Struct({
+    sequence: NonEmptyString, // decimal-string uint64
+    /** Base64-encoded PTY output bytes, exactly as recorded. */
+    dataBase64: Schema.String,
+});
+export const sessionOutputResponseSchema = Schema.Struct({
+    sessionId: NonEmptyString,
+    chunks: Schema.Array(sessionOutputChunkSchema),
+    /** The cursor to pass as `from` to continue after this page. */
+    nextFrom: NonEmptyString,
+    /** Session status at read time, so pollers can stop when the session settles. */
+    status: sessionStatusSchema,
+});
+export class SessionBadRequestError extends Schema.TaggedErrorClass()("SessionBadRequestError", { message: Schema.String }, { httpApiStatus: 400 }) {
+}
+export class SessionUnauthorizedError extends Schema.TaggedErrorClass()("SessionUnauthorizedError", { message: Schema.String }, { httpApiStatus: 401 }) {
+}
+export class SessionForbiddenError extends Schema.TaggedErrorClass()("SessionForbiddenError", { message: Schema.String }, { httpApiStatus: 403 }) {
+}
+export class SessionNotFoundError extends Schema.TaggedErrorClass()("SessionNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+export class SessionConflictError extends Schema.TaggedErrorClass()("SessionConflictError", { message: Schema.String }, { httpApiStatus: 409 }) {
+}
+export class SessionBadGatewayError extends Schema.TaggedErrorClass()("SessionBadGatewayError", { message: Schema.String }, { httpApiStatus: 502 }) {
+}
+export class SessionInternalServerError extends Schema.TaggedErrorClass()("SessionInternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
+}
+const sessionIdParams = Schema.Struct({ sessionId: NonEmptyString });
+export const SessionsGroup = HttpApiGroup.make("sessions")
+    .add(
+// Scope: workspace:exec. Opens the daemon PTY, creates the interactive run + session rows.
+HttpApiEndpoint.post("createSession", "/", {
+    headers: sessionAuthorizationHeadersSchema,
+    payload: createSessionRequestSchema,
+    success: sessionSchema.pipe(HttpApiSchema.status(201)),
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionConflictError,
+        SessionBadGatewayError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.get("listSessions", "/", {
+    headers: sessionAuthorizationHeadersSchema,
+    query: listSessionsQuerySchema,
+    success: listSessionsResponseSchema,
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(
+// Scope: session:read. Status includes the resume cursor (outputHighWater).
+HttpApiEndpoint.get("getSession", "/:sessionId", {
+    params: sessionIdParams,
+    headers: sessionAuthorizationHeadersSchema,
+    query: Schema.Struct({ ownerUserId: Schema.optional(NonEmptyString) }),
+    success: sessionSchema,
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(
+// Scope: session:read. Byte-exact recorded output by sequence range (history + poll tail).
+HttpApiEndpoint.get("getSessionOutput", "/:sessionId/output", {
+    params: sessionIdParams,
+    headers: sessionAuthorizationHeadersSchema,
+    query: getSessionOutputQuerySchema,
+    success: sessionOutputResponseSchema,
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(
+// Scope: session:input.
+HttpApiEndpoint.post("sendSessionInput", "/:sessionId/input", {
+    params: sessionIdParams,
+    headers: sessionAuthorizationHeadersSchema,
+    payload: sessionInputRequestSchema,
+    success: Schema.Struct({ ok: Schema.Boolean }),
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionConflictError,
+        SessionBadGatewayError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(
+// Scope: session:input.
+HttpApiEndpoint.post("resizeSession", "/:sessionId/resize", {
+    params: sessionIdParams,
+    headers: sessionAuthorizationHeadersSchema,
+    payload: sessionResizeRequestSchema,
+    success: Schema.Struct({ ok: Schema.Boolean }),
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionConflictError,
+        SessionBadGatewayError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(
+// Scope: session:input.
+HttpApiEndpoint.post("signalSession", "/:sessionId/signal", {
+    params: sessionIdParams,
+    headers: sessionAuthorizationHeadersSchema,
+    payload: sessionSignalRequestSchema,
+    success: Schema.Struct({ ok: Schema.Boolean }),
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionConflictError,
+        SessionBadGatewayError,
+        SessionInternalServerError,
+    ],
+}))
+    .add(
+// Scope: workspace:exec (closing a terminal is a control action, like opening one).
+HttpApiEndpoint.post("closeSession", "/:sessionId/close", {
+    params: sessionIdParams,
+    headers: sessionAuthorizationHeadersSchema,
+    payload: closeSessionRequestSchema,
+    success: sessionSchema.pipe(HttpApiSchema.status(202)),
+    error: [
+        SessionBadRequestError,
+        SessionUnauthorizedError,
+        SessionForbiddenError,
+        SessionNotFoundError,
+        SessionBadGatewayError,
+        SessionInternalServerError,
+    ],
+}))
+    .annotate(OpenApi.Description, "Interactive PTY sessions: durable, reattachable, sequence-keyed output.");