@sealant/sdk-next 0.40.0-next.784 → 0.40.0-next.786

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  import { ResourceInstanceKey, ResourceReachAliases, ResourceWorktreeKey, } from "@sealant/api-contracts";
2
2
  import { Effect, Schema } from "effect";
3
- import { SealantApiClient } from "./api-client.js";
3
+ import { CurrentRequestPriority, SealantApiClient } from "./api-client.js";
4
4
  // ---- workspaces ----
5
5
  export const createWorkspaceOp = (payload, idempotencyKey) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.createWorkspace({
6
6
  payload,
@@ -14,7 +14,7 @@ export const getWorkspaceCreateOp = (idempotencyKey, ownerUserId) => Effect.flat
14
14
  params: { idempotencyKey },
15
15
  query: { ownerUserId },
16
16
  }));
17
- export const cancelWorkspaceCreateOp = (idempotencyKey, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.cancelWorkspaceCreate({ params: { idempotencyKey }, payload }));
17
+ export const cancelWorkspaceCreateOp = (idempotencyKey, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.cancelWorkspaceCreate({ params: { idempotencyKey }, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
18
18
  export const listWorkspacesOp = (query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.listWorkspaces({ query }));
19
19
  export const execWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.execWorkspace({ params: { workspaceId }, payload }));
20
20
  /** An exec as a Linux user: its own route, which a control plane that cannot run one answers 404. */
@@ -24,16 +24,16 @@ export const bindWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantA
24
24
  export const flushWorkspaceCaptureOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.flushWorkspaceCapture({ params: { workspaceId }, payload }));
25
25
  export const getWorkspaceCaptureStatusOp = (workspaceId, query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.getWorkspaceCaptureStatus({ params: { workspaceId }, query }));
26
26
  export const replanWorkspaceCaptureOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.replanWorkspaceCapture({ params: { workspaceId }, payload }));
27
- export const stopWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.stopWorkspace({ params: { workspaceId }, payload }));
28
- export const recoverWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.recoverWorkspace({ params: { workspaceId }, payload }));
29
- export const restartWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.restartWorkspace({ params: { workspaceId }, payload }));
27
+ export const stopWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.stopWorkspace({ params: { workspaceId }, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
28
+ export const recoverWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.recoverWorkspace({ params: { workspaceId }, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
29
+ export const restartWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.restartWorkspace({ params: { workspaceId }, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
30
30
  export const inspectWorkspaceImageOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.inspectWorkspaceImage({ payload }));
31
31
  export const putWorkspaceCredentialsOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.putWorkspaceCredentials({ params: { workspaceId }, payload }));
32
32
  /** Remove unused credential placements in one home. */
33
33
  export const pruneWorkspaceCredentialsOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.pruneWorkspaceCredentials({ params: { workspaceId }, payload }));
34
34
  export const releaseWorkspaceCredentialsOp = (workspaceId, query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.releaseWorkspaceCredentials({ params: { workspaceId }, query }));
35
35
  export const listWorkspaceCredentialsOp = (workspaceId, query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.listWorkspaceCredentials({ params: { workspaceId }, query }));
36
- export const expireWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.expireWorkspace({ params: { workspaceId }, payload }));
36
+ export const expireWorkspaceOp = (workspaceId, payload) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.expireWorkspace({ params: { workspaceId }, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
37
37
  export const clearWorkspaceSshUserOp = (workspaceId, query) => Effect.flatMap(SealantApiClient, (client) => client.workspaces.clearWorkspaceSshUser({ params: { workspaceId }, query }));
38
38
  // ---- runs ----
39
39
  export const createRunOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.runs.createRun({ payload }));
@@ -56,10 +56,10 @@ export const getSessionOp = (sessionId, ownerUserId) => Effect.flatMap(SealantAp
56
56
  }));
57
57
  export const listSessionsOp = (query) => Effect.flatMap(SealantApiClient, (client) => client.sessions.listSessions({ query, headers: {} }));
58
58
  export const getSessionOutputOp = (sessionId, query) => Effect.flatMap(SealantApiClient, (client) => client.sessions.getSessionOutput({ params: { sessionId }, headers: {}, query }));
59
- export const sendSessionInputOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.sendSessionInput({ params: { sessionId }, headers: {}, payload }));
60
- export const resizeSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.resizeSession({ params: { sessionId }, headers: {}, payload }));
61
- export const signalSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.signalSession({ params: { sessionId }, headers: {}, payload }));
62
- export const closeSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.closeSession({ params: { sessionId }, headers: {}, payload }));
59
+ export const sendSessionInputOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.sendSessionInput({ params: { sessionId }, headers: {}, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
60
+ export const resizeSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.resizeSession({ params: { sessionId }, headers: {}, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
61
+ export const signalSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.signalSession({ params: { sessionId }, headers: {}, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
62
+ export const closeSessionOp = (sessionId, payload) => Effect.flatMap(SealantApiClient, (client) => client.sessions.closeSession({ params: { sessionId }, headers: {}, payload })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
63
63
  // ---- access tokens ----
64
64
  export const createAccessTokenOp = (payload) => Effect.flatMap(SealantApiClient, (client) => client.accessTokens.createAccessToken({ payload }));
65
65
  // ---- users ----
@@ -119,7 +119,7 @@ export const listResourceInstancesOp = (resourceDomainId, archived) => Effect.fl
119
119
  export const stopResourceInstanceOp = (resourceDomainId, key, by) => Effect.flatMap(Effect.all([SealantApiClient, instanceKey(key)]), ([client, checked]) => client.resourceInstances.stopResourceInstance({
120
120
  params: { resourceDomainId, key: checked },
121
121
  payload: { by },
122
- }));
122
+ })).pipe(Effect.provideService(CurrentRequestPriority, "interactive"));
123
123
  export const archiveResourceInstanceOp = (resourceDomainId, key) => Effect.flatMap(Effect.all([SealantApiClient, instanceKey(key)]), ([client, checked]) => client.resourceInstances.archiveResourceInstance({
124
124
  params: { resourceDomainId, key: checked },
125
125
  }));
@@ -8,10 +8,12 @@
8
8
  * settle via `run.wait()`). No Postgres pool, no docker-exec, no telemetry sink: this is what makes
9
9
  * @sealant/sdk a plain client that runs anywhere.
10
10
  */
11
+ import { BudgetExceededError } from "@sealant/api-contracts";
11
12
  import { Effect } from "effect";
12
13
  import { SealantError } from "../errors.js";
13
14
  import { makeRun, toRunChangesData } from "../facade/run.js";
14
15
  import { elapsed } from "../internal/clock.js";
16
+ import { toSealantError } from "../internal/map-error.js";
15
17
  import { createRunOp, getRunChangesOp, getRunOp, getWorkspaceOp } from "./operations.js";
16
18
  const TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
17
19
  const POLL_INTERVAL = "500 millis";
@@ -57,21 +59,28 @@ const createHarnessRunEffect = (ctx, init, prompt, options) => Effect.gen(functi
57
59
  const runHarnessEffect = (ctx, init, prompt, options) => Effect.gen(function* () {
58
60
  const created = yield* createHarnessRunEffect(ctx, init, prompt, options);
59
61
  const runId = created.runId;
60
- // Block until the run is terminal, polling the control plane.
61
- const deadline = elapsed() + RUN_TIMEOUT_MS;
62
- let wire = created;
63
- while (!TERMINAL_STATUSES.has(wire.status)) {
64
- if (elapsed() > deadline) {
65
- return yield* Effect.fail(new SealantError(`Timed out waiting for run ${runId} to complete.`, {
66
- code: "run_timeout",
67
- }));
62
+ return yield* Effect.gen(function* () {
63
+ // Block until the run is terminal, polling the control plane.
64
+ const deadline = elapsed() + RUN_TIMEOUT_MS;
65
+ let wire = created;
66
+ while (!TERMINAL_STATUSES.has(wire.status)) {
67
+ if (elapsed() > deadline) {
68
+ return yield* Effect.fail(new SealantError(`Timed out waiting for run ${runId} to complete.`, {
69
+ code: "run_timeout",
70
+ }));
71
+ }
72
+ yield* Effect.sleep(POLL_INTERVAL);
73
+ wire = yield* getRunOp(runId, ctx.config.hostLocal.ownerUserId);
68
74
  }
69
- yield* Effect.sleep(POLL_INTERVAL);
70
- wire = yield* getRunOp(runId, ctx.config.hostLocal.ownerUserId);
71
- }
72
- // Read the changes the run produced (captured server-side).
73
- const changes = toRunChangesData(yield* getRunChangesOp(runId, ctx.config.hostLocal.ownerUserId));
74
- return makeRun(ctx, { wire, changes });
75
+ // Read the changes the run produced (captured server-side).
76
+ const changes = toRunChangesData(yield* getRunChangesOp(runId, ctx.config.hostLocal.ownerUserId));
77
+ return makeRun(ctx, { wire, changes });
78
+ }).pipe(Effect.mapError((error) => error instanceof BudgetExceededError
79
+ ? new SealantError(`Run ${runId} was created, but a follow-up request reached its budget. Resume this run instead of starting it again.`, {
80
+ code: "run_followup_refused",
81
+ cause: toSealantError(error),
82
+ })
83
+ : error));
75
84
  });
76
85
  /** The BLOCKING `harness.run()` implementation, registered into the Workspace facade by the client. */
77
86
  export const runHarness = (ctx, init, prompt, options) => ctx.runtime.run(runHarnessEffect(ctx, init, prompt, options));
package/dist/errors.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { ForwardRefusalReason } from "@sealant/api-contracts";
1
+ import type { RequestBudgetRefusal, ForwardRefusalReason } from "@sealant/api-contracts";
2
2
  import type { ForwardResetCause } from "./types.js";
3
3
  /**
4
4
  * Public SDK errors. The Effect core fails on a typed `Schema.TaggedError` channel; the facade maps
@@ -50,6 +50,26 @@ export declare class SealantApiError extends SealantError {
50
50
  readonly cause?: unknown;
51
51
  });
52
52
  }
53
+ /** A control-plane budget failure, with the server's retry delay and admission metadata. */
54
+ export declare class SealantBudgetExceededError extends SealantApiError {
55
+ readonly name = "SealantBudgetExceededError";
56
+ readonly status = 429;
57
+ /** Which configured budget refused this request. */
58
+ readonly budget: string;
59
+ /** The applicable threshold, including any interactive reserve. */
60
+ readonly limit: number;
61
+ /** Seconds until this budget is expected to have room. */
62
+ readonly retryAfterSeconds: number;
63
+ /** Present only when this HTTP request was refused before its handler did work. */
64
+ readonly refusal?: RequestBudgetRefusal;
65
+ constructor(message: string, options: {
66
+ readonly budget: string;
67
+ readonly limit: number;
68
+ readonly retryAfterSeconds: number;
69
+ readonly refusal?: RequestBudgetRefusal;
70
+ readonly cause?: unknown;
71
+ });
72
+ }
53
73
  /**
54
74
  * Why a workspace forward did not open. Core names every refusal it sends. The SDK adds
55
75
  * `unrecognized-refusal` (Core sent a reason newer than this SDK; it is kept in `wireReason`),
@@ -57,7 +77,7 @@ export declare class SealantApiError extends SealantError {
57
77
  * unreadable) and `transport-unavailable` (no answer could be read at all).
58
78
  */
59
79
  export type ForwardDialReason = ForwardRefusalReason | "unrecognized-refusal" | "protocol-unsupported" | "transport-unavailable";
60
- export type ForwardDialFailure = {
80
+ export type ForwardDialFailure = ({
61
81
  readonly reason: ForwardRefusalReason;
62
82
  readonly status: number;
63
83
  readonly message: string;
@@ -69,6 +89,11 @@ export type ForwardDialFailure = {
69
89
  } | {
70
90
  readonly reason: "protocol-unsupported" | "transport-unavailable";
71
91
  readonly message: string;
92
+ }) & {
93
+ readonly budget?: string;
94
+ readonly limit?: number;
95
+ readonly retryAfterSeconds?: number;
96
+ readonly refusal?: RequestBudgetRefusal;
72
97
  };
73
98
  /** A workspace forward was refused before it opened. Branch on `reason`. */
74
99
  export declare class ForwardDialError extends SealantApiError {
@@ -76,6 +101,11 @@ export declare class ForwardDialError extends SealantApiError {
76
101
  readonly reason: ForwardDialReason;
77
102
  /** The reason Core sent, when this SDK does not know it (`unrecognized-refusal`). */
78
103
  readonly wireReason?: string;
104
+ /** Budget metadata from a refusal after the WebSocket upgrade. */
105
+ readonly budget?: string;
106
+ readonly limit?: number;
107
+ readonly retryAfterSeconds?: number;
108
+ readonly refusal?: RequestBudgetRefusal;
79
109
  constructor(failure: ForwardDialFailure);
80
110
  }
81
111
  /** The requested operation is part of the public surface but not yet implemented in this slice. */
package/dist/errors.js CHANGED
@@ -60,12 +60,42 @@ export class SealantApiError extends SealantError {
60
60
  }
61
61
  }
62
62
  }
63
+ /** A control-plane budget failure, with the server's retry delay and admission metadata. */
64
+ export class SealantBudgetExceededError extends SealantApiError {
65
+ name = "SealantBudgetExceededError";
66
+ status = 429;
67
+ /** Which configured budget refused this request. */
68
+ budget;
69
+ /** The applicable threshold, including any interactive reserve. */
70
+ limit;
71
+ /** Seconds until this budget is expected to have room. */
72
+ retryAfterSeconds;
73
+ /** Present only when this HTTP request was refused before its handler did work. */
74
+ refusal;
75
+ constructor(message, options) {
76
+ super(message, {
77
+ code: "BudgetExceededError",
78
+ status: 429,
79
+ ...(options.cause === undefined ? {} : { cause: options.cause }),
80
+ });
81
+ this.budget = options.budget;
82
+ this.limit = options.limit;
83
+ this.retryAfterSeconds = options.retryAfterSeconds;
84
+ if (options.refusal !== undefined)
85
+ this.refusal = options.refusal;
86
+ }
87
+ }
63
88
  /** A workspace forward was refused before it opened. Branch on `reason`. */
64
89
  export class ForwardDialError extends SealantApiError {
65
90
  name = "ForwardDialError";
66
91
  reason;
67
92
  /** The reason Core sent, when this SDK does not know it (`unrecognized-refusal`). */
68
93
  wireReason;
94
+ /** Budget metadata from a refusal after the WebSocket upgrade. */
95
+ budget;
96
+ limit;
97
+ retryAfterSeconds;
98
+ refusal;
69
99
  constructor(failure) {
70
100
  super(failure.message, {
71
101
  code: "ForwardDialError",
@@ -73,6 +103,14 @@ export class ForwardDialError extends SealantApiError {
73
103
  ...("status" in failure ? { status: failure.status } : {}),
74
104
  });
75
105
  this.reason = failure.reason;
106
+ if (failure.budget !== undefined)
107
+ this.budget = failure.budget;
108
+ if (failure.limit !== undefined)
109
+ this.limit = failure.limit;
110
+ if (failure.retryAfterSeconds !== undefined)
111
+ this.retryAfterSeconds = failure.retryAfterSeconds;
112
+ if (failure.refusal !== undefined)
113
+ this.refusal = failure.refusal;
76
114
  if ("wireReason" in failure) {
77
115
  this.wireReason = failure.wireReason;
78
116
  }
@@ -1,5 +1,6 @@
1
- import type { BoundedForwardTarget, BoundedWorkspaceForward, BoundedWorkspaceForwardOptions, WorkspaceForward, WorkspaceForwardOptions } from "../types.js";
1
+ import type { BoundedForwardTarget, BoundedWorkspaceForward, BoundedWorkspaceForwardOptions, SealantConfig, WorkspaceForward, WorkspaceForwardOptions } from "../types.js";
2
2
  export interface ForwardEndpoint {
3
+ readonly requestPriority?: SealantConfig["requestPriority"];
3
4
  readonly baseUrl: string;
4
5
  readonly apiKey: string | undefined;
5
6
  readonly ownerUserId: string;
@@ -1,6 +1,7 @@
1
1
  import { FORWARD_REFUSAL_STATUS, FORWARD_V2_SUBPROTOCOL, forwardOpenFrameSchema, forwardRefusalReasonSchema, } from "@sealant/api-contracts";
2
2
  import { Option, Schema } from "effect";
3
3
  import { ForwardDialError } from "../errors.js";
4
+ import { resolveRequestPriority } from "../internal/config.js";
4
5
  import { boundedForward } from "./bounded-forward.js";
5
6
  const forwardUrl = (endpoint, path, query) => {
6
7
  const url = new URL(path, endpoint.baseUrl);
@@ -97,25 +98,37 @@ export const openForward = (endpoint, workspaceId, port, options) => {
97
98
  const FORWARD_V2_OPEN_DEADLINE_MS = 30_000;
98
99
  const decodeOpenFrame = Schema.decodeUnknownOption(Schema.fromJsonString(forwardOpenFrameSchema));
99
100
  const isKnownRefusal = Schema.is(forwardRefusalReasonSchema);
100
- const refusalError = (frame) => new ForwardDialError(isKnownRefusal(frame.reason)
101
- ? { reason: frame.reason, status: frame.status, message: frame.message }
102
- : {
103
- reason: "unrecognized-refusal",
104
- wireReason: frame.reason,
105
- status: frame.status,
106
- message: frame.message,
107
- });
101
+ const refusalError = (frame) => {
102
+ const budget = {
103
+ ...(frame.budget === undefined ? {} : { budget: frame.budget }),
104
+ ...(frame.limit === undefined ? {} : { limit: frame.limit }),
105
+ ...(frame.retryAfterSeconds === undefined
106
+ ? {}
107
+ : { retryAfterSeconds: frame.retryAfterSeconds }),
108
+ ...(frame.refusal === undefined ? {} : { refusal: frame.refusal }),
109
+ };
110
+ return new ForwardDialError(isKnownRefusal(frame.reason)
111
+ ? { ...budget, reason: frame.reason, status: frame.status, message: frame.message }
112
+ : {
113
+ ...budget,
114
+ reason: "unrecognized-refusal",
115
+ wireReason: frame.reason,
116
+ status: frame.status,
117
+ message: frame.message,
118
+ });
119
+ };
108
120
  /** A gated Core before v2 answers the route 401, an open one 404. Core with v2 answers 426. */
109
121
  const answeredLikeCoreBeforeV2 = (status) => status === 401 || status === 404;
110
- const failedHandshakeError = async (url, origin, signal) => {
122
+ const failedHandshakeError = async (url, origin, signal, requestPriority) => {
111
123
  const probe = new URL(url.pathname, url);
112
124
  probe.protocol = url.protocol === "wss:" ? "https:" : "http:";
113
125
  const unavailable = (detail) => new ForwardDialError({
114
126
  reason: "transport-unavailable",
115
127
  message: `The forward could not open a WebSocket to ${origin}; ${detail}.`,
116
128
  });
129
+ const headers = { "x-sealant-request-priority": resolveRequestPriority(requestPriority) };
117
130
  try {
118
- const response = await fetch(probe, { signal });
131
+ const response = await fetch(probe, { signal, headers });
119
132
  await response.body?.cancel();
120
133
  if (answeredLikeCoreBeforeV2(response.status)) {
121
134
  return new ForwardDialError({
@@ -206,7 +219,7 @@ export const openForwardV2 = (endpoint, workspaceId, port, options) => {
206
219
  if (phase !== "handshake")
207
220
  return;
208
221
  phase = "probing";
209
- void failedHandshakeError(url, origin, probing.signal).then(fail);
222
+ void failedHandshakeError(url, origin, probing.signal, endpoint.requestPriority).then(fail, fail);
210
223
  });
211
224
  });
212
225
  };
@@ -1,4 +1,7 @@
1
1
  import { closeSessionOp, getSessionOp, getSessionOutputOp, resizeSessionOp, sendSessionInputOp, signalSessionOp, } from "../effect/operations.js";
2
+ import { SealantBudgetExceededError } from "../errors.js";
3
+ import { resolveRequestPriority } from "../internal/config.js";
4
+ import { toSealantError } from "../internal/map-error.js";
2
5
  /**
3
6
  * Open the held-WebSocket terminal attachment (the data plane). One socket:
4
7
  * binary frames are PTY bytes in both directions, text frames are control
@@ -122,7 +125,7 @@ const parseSseFrame = (block) => {
122
125
  return { event, id, data: dataLines.join("\n") };
123
126
  };
124
127
  /** Stream the session's output over SSE. Throws on transport failure (caller falls back). */
125
- async function* streamOverSse(ctx, sessionId, from, signal) {
128
+ async function* streamOverSse(ctx, sessionId, from, signal, priority) {
126
129
  const config = ctx.config;
127
130
  const fetchImpl = config.fetch ?? fetch;
128
131
  const url = new URL(`/v1/sessions/${sessionId}/output/stream`, config.baseUrl);
@@ -131,10 +134,17 @@ async function* streamOverSse(ctx, sessionId, from, signal) {
131
134
  const response = await fetchImpl(url, {
132
135
  headers: {
133
136
  accept: "text/event-stream",
137
+ "x-sealant-request-priority": priority,
134
138
  ...(config.apiKey === undefined ? {} : { authorization: `Bearer ${config.apiKey}` }),
135
139
  },
136
140
  ...(signal === undefined ? {} : { signal }),
137
141
  });
142
+ if (response.status === 429) {
143
+ const body = await response.json().catch(() => undefined);
144
+ const error = toSealantError(body);
145
+ if (error instanceof SealantBudgetExceededError)
146
+ throw error;
147
+ }
138
148
  if (!response.ok || response.body === null) {
139
149
  throw new Error(`session output stream failed: HTTP ${response.status}`);
140
150
  }
@@ -214,14 +224,17 @@ export const makeInteractiveSession = (ctx, wire) => {
214
224
  const signal = options?.signal;
215
225
  async function* iterate() {
216
226
  let cursor = from;
227
+ const priority = resolveRequestPriority(ctx.config.requestPriority);
217
228
  try {
218
- for await (const chunk of streamOverSse(ctx, sessionId, cursor, signal)) {
229
+ for await (const chunk of streamOverSse(ctx, sessionId, cursor, signal, priority)) {
219
230
  yield chunk;
220
231
  cursor = chunk.sequence + 1n;
221
232
  }
222
233
  return;
223
234
  }
224
235
  catch (error) {
236
+ if (error instanceof SealantBudgetExceededError)
237
+ throw error;
225
238
  if (signal?.aborted === true) {
226
239
  return;
227
240
  }
@@ -2,7 +2,7 @@ import { sessionArgvIssue } from "@sealant/api-contracts";
2
2
  import { applyDotfiles } from "../effect/apply-dotfiles.js";
3
3
  import { execWorkspace } from "../effect/exec-workspace.js";
4
4
  import { bindWorkspaceOp, flushWorkspaceCaptureOp, getWorkspaceCaptureStatusOp, createSessionAsUserOp, createSessionOp, expireWorkspaceOp, clearWorkspaceSshUserOp, getSessionOp, getWorkspaceOp, listSessionsOp, replanWorkspaceCaptureOp, recoverWorkspaceOp, restartWorkspaceOp, listWorkspaceCredentialsOp, putWorkspaceCredentialsOp, pruneWorkspaceCredentialsOp, releaseWorkspaceCredentialsOp, stopWorkspaceOp, } from "../effect/operations.js";
5
- import { SealantApiError, SealantError, SealantNotImplementedError } from "../errors.js";
5
+ import { SealantApiError, SealantBudgetExceededError, SealantError, SealantNotImplementedError, } from "../errors.js";
6
6
  import { elapsed } from "../internal/clock.js";
7
7
  import { mapAccountRef } from "../internal/credentials.js";
8
8
  import { parseTtlSeconds } from "../internal/duration.js";
@@ -312,6 +312,7 @@ const olderControlPlaneRefusal = (argv, error) => {
312
312
  };
313
313
  export const makeWorkspace = (ctx, init) => {
314
314
  const endpoint = {
315
+ requestPriority: ctx.config.requestPriority,
315
316
  baseUrl: ctx.config.baseUrl,
316
317
  apiKey: ctx.config.apiKey,
317
318
  ownerUserId: ctx.config.hostLocal.ownerUserId,
@@ -709,7 +710,14 @@ export const makeWorkspace = (ctx, init) => {
709
710
  };
710
711
  const deadline = elapsed() + STOP_TIMEOUT_MS;
711
712
  for (;;) {
712
- const details = await ctx.runtime.run(getWorkspaceOp(init.id, ctx.config.hostLocal.ownerUserId));
713
+ const details = await ctx.runtime
714
+ .run(getWorkspaceOp(init.id, ctx.config.hostLocal.ownerUserId))
715
+ .catch((error) => {
716
+ if (error instanceof SealantBudgetExceededError) {
717
+ throw new SealantError(`A stop for workspace ${init.id} was accepted, but a follow-up request reached its budget. Read the workspace again to observe its status.`, { code: "workspace_stop_observation_refused", cause: error });
718
+ }
719
+ throw error;
720
+ });
713
721
  // `cancelled`: a stop before the image was built cancelled the launch; `failed` with no
714
722
  // runtime: the build failed. Either way no runtime ever ran.
715
723
  if (details.status === "stopped" ||
package/dist/index.d.ts CHANGED
@@ -16,7 +16,7 @@
16
16
  */
17
17
  export { Sealant } from "./client.js";
18
18
  export { claudeCode, codex, customHarness, opencode, pi } from "./harness.js";
19
- export { ForwardDialError, type ForwardDialFailure, type ForwardDialReason, ForwardResetError, SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
19
+ export { ForwardDialError, type ForwardDialFailure, type ForwardDialReason, ForwardResetError, SealantApiError, SealantBudgetExceededError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
20
20
  export type * from "./types.js";
21
21
  export type { EnsuredScope, ScopeBudget, ScopeBudgetDimension, ScopeBudgetLimits, ScopeBudgets, ScopeClient, ScopeInfo, ScopeMember, ScopeMemberDecision, ScopeMemberPage, ScopeMembers, ScopesNamespace, } from "./scopes.js";
22
22
  export type { ScopeArchivedVolume, ScopeExecResult, ScopeInstance, ScopeInstances, ScopeInstanceSpec, ScopeInstanceState, ScopeInstanceStopReason, ScopeWorkspaces, } from "./scope-instances.js";
package/dist/index.js CHANGED
@@ -16,7 +16,7 @@
16
16
  */
17
17
  export { Sealant } from "./client.js";
18
18
  export { claudeCode, codex, customHarness, opencode, pi } from "./harness.js";
19
- export { ForwardDialError, ForwardResetError, SealantApiError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
19
+ export { ForwardDialError, ForwardResetError, SealantApiError, SealantBudgetExceededError, SealantError, SealantNotImplementedError, SealantRuntimeError, } from "./errors.js";
20
20
  // The workspace environment policy (`CreateOptions.env` validation) is public API: downstream
21
21
  // products validate at their own boundaries with the exact rules the platform enforces.
22
22
  export { findWorkspaceEnvReservedRule, findWorkspaceSecretEnvReservedRule, formatWorkspaceEnvIssue, parseWorkspaceEnv, parseWorkspaceSecretEnv, WORKSPACE_ENV_MAX_ENTRIES, WORKSPACE_ENV_MAX_NAME_LENGTH, WORKSPACE_ENV_MAX_TOTAL_BYTES, WORKSPACE_ENV_MAX_VALUE_BYTES, WORKSPACE_ENV_NAME_PATTERN, WORKSPACE_ENV_SECRET_MARKERS, } from "@sealant/api-contracts/workspace-environment";
@@ -7,7 +7,7 @@
7
7
  * payloads. The owner comes from `SealantConfig.ownerUserId` when a product acts on behalf of a
8
8
  * specific user (one client per user), else from the environment with docker-compose defaults.
9
9
  */
10
- import type { SealantConfig } from "../types.js";
10
+ import type { RequestPriority, SealantConfig } from "../types.js";
11
11
  export interface SealantHostLocalConfig {
12
12
  /** Owner principal the control plane attributes workspaces/runs to (pre-auth). */
13
13
  readonly ownerUserId: string;
@@ -15,10 +15,13 @@ export interface SealantHostLocalConfig {
15
15
  readonly registryId: string;
16
16
  }
17
17
  export interface SealantInternalConfig {
18
+ readonly requestPriority?: SealantConfig["requestPriority"];
18
19
  readonly baseUrl: string;
19
20
  readonly apiKey: string | undefined;
20
21
  readonly fetch: typeof fetch | undefined;
21
22
  readonly hostLocal: SealantHostLocalConfig;
22
23
  }
24
+ /** Resolve the caller's priority at dispatch, before falling back to the operation default. */
25
+ export declare const resolveRequestPriority: (configured: SealantConfig["requestPriority"], operationDefault?: RequestPriority) => RequestPriority;
23
26
  /** Resolves the public config plus host-local needs (from env, with docker-compose defaults). */
24
27
  export declare const resolveInternalConfig: (config: SealantConfig) => SealantInternalConfig;
@@ -1,6 +1,8 @@
1
1
  const DEFAULT_OWNER_USER_ID = "usr_local";
2
2
  // Must match the control-plane's REGISTRY_NAME (defaults to "default"); the API 404s otherwise.
3
3
  const DEFAULT_REGISTRY_ID = "default";
4
+ /** Resolve the caller's priority at dispatch, before falling back to the operation default. */
5
+ export const resolveRequestPriority = (configured, operationDefault = "normal") => typeof configured === "function" ? configured() : (configured ?? operationDefault);
4
6
  const env = (key) => {
5
7
  const value = process.env[key];
6
8
  return value === undefined || value.length === 0 ? undefined : value;
@@ -8,6 +10,7 @@ const env = (key) => {
8
10
  /** Resolves the public config plus host-local needs (from env, with docker-compose defaults). */
9
11
  export const resolveInternalConfig = (config) => ({
10
12
  baseUrl: config.baseUrl,
13
+ ...(config.requestPriority === undefined ? {} : { requestPriority: config.requestPriority }),
11
14
  apiKey: config.apiKey,
12
15
  fetch: config.fetch,
13
16
  hostLocal: {
@@ -1,8 +1,2 @@
1
- /**
2
- * Maps any failure crossing the Effect boundary onto a plain public `SealantError`. The Effect core
3
- * fails with `@sealant/api-contracts` tagged errors (e.g. `WorkspaceNotFoundError`), Effect HTTP-client
4
- * errors, or schema decode errors; the runtime squashes the `Cause` to its failure value and hands it
5
- * here. This is the single funnel that keeps Effect internals out of the public, Promise-based API.
6
- */
7
1
  import { SealantError } from "../errors.js";
8
2
  export declare const toSealantError: (cause: unknown) => SealantError;
@@ -4,7 +4,9 @@
4
4
  * errors, or schema decode errors; the runtime squashes the `Cause` to its failure value and hands it
5
5
  * here. This is the single funnel that keeps Effect internals out of the public, Promise-based API.
6
6
  */
7
- import { SealantApiError, SealantError } from "../errors.js";
7
+ import { BudgetExceededError } from "@sealant/api-contracts";
8
+ import { Option, Schema } from "effect";
9
+ import { SealantApiError, SealantBudgetExceededError, SealantError } from "../errors.js";
8
10
  const asRecord = (value) => typeof value === "object" && value !== null ? value : undefined;
9
11
  const extractStatus = (record) => {
10
12
  if (record === undefined) {
@@ -33,6 +35,18 @@ export const toSealantError = (cause) => {
33
35
  : typeof cause === "string"
34
36
  ? cause
35
37
  : "Sealant operation failed.";
38
+ if (tag === "BudgetExceededError") {
39
+ const budget = Schema.decodeUnknownOption(BudgetExceededError)(cause);
40
+ if (Option.isSome(budget)) {
41
+ return new SealantBudgetExceededError(message, {
42
+ budget: budget.value.budget,
43
+ limit: budget.value.limit,
44
+ retryAfterSeconds: budget.value.retryAfterSeconds,
45
+ ...(budget.value.refusal === undefined ? {} : { refusal: budget.value.refusal }),
46
+ cause,
47
+ });
48
+ }
49
+ }
36
50
  if (typeof tag === "string") {
37
51
  const status = extractStatus(record);
38
52
  const reason = nonEmptyString(record?.["code"]);
@@ -1,5 +1,5 @@
1
1
  import type { SdkRuntime } from "./effect/runtime.js";
2
- import type { SealantInternalConfig } from "./internal/config.js";
2
+ import { type SealantInternalConfig } from "./internal/config.js";
3
3
  /**
4
4
  * What an instance runs. It has no field for privileged mode, capabilities, host networking, host
5
5
  * paths, devices, the Docker socket or shared namespaces; a spec sent with one is refused (400
@@ -6,7 +6,9 @@
6
6
  */
7
7
  import { RESOURCE_INSTANCE_EXEC, } from "@sealant/api-contracts";
8
8
  import { archiveResourceDomainOp, archiveResourceInstanceOp, getResourceInstanceOp, linkResourceWorkspaceOp, listResourceInstancesOp, stopResourceInstanceOp, upResourceInstanceOp, } from "./effect/operations.js";
9
- import { SealantApiError, SealantError } from "./errors.js";
9
+ import { SealantApiError, SealantBudgetExceededError, SealantError } from "./errors.js";
10
+ import { resolveRequestPriority } from "./internal/config.js";
11
+ import { toSealantError } from "./internal/map-error.js";
10
12
  const date = (value) => new Date(value);
11
13
  const maybeDate = (value) => (value === null ? null : new Date(value));
12
14
  const toState = (state) => {
@@ -106,6 +108,7 @@ const exec = async (config, scopeId, key, options) => {
106
108
  method: "POST",
107
109
  headers: {
108
110
  "content-type": "application/octet-stream",
111
+ "x-sealant-request-priority": resolveRequestPriority(config.requestPriority),
109
112
  ...(config.apiKey === undefined ? {} : { authorization: `Bearer ${config.apiKey}` }),
110
113
  },
111
114
  body: execBody(frame, options.stdin),
@@ -114,6 +117,11 @@ const exec = async (config, scopeId, key, options) => {
114
117
  const response = await (config.fetch ?? fetch)(new URL(path, config.baseUrl), init);
115
118
  const body = await response.json().catch(() => undefined);
116
119
  if (!response.ok) {
120
+ if (response.status === 429) {
121
+ const error = toSealantError(body);
122
+ if (error instanceof SealantBudgetExceededError)
123
+ throw error;
124
+ }
117
125
  const tag = isRecord(body) && typeof body["_tag"] === "string" ? body["_tag"] : undefined;
118
126
  const message = isRecord(body) && typeof body["message"] === "string"
119
127
  ? body["message"]
package/dist/types.d.ts CHANGED
@@ -16,6 +16,8 @@
16
16
  */
17
17
  import type { ReadableStream as NodeReadableStream, WritableStream as NodeWritableStream } from "node:stream/web";
18
18
  import type { ConnectedAccountLogin, ConnectedAccountLoginClass, ForwardBinding, ForwardResetReason } from "@sealant/api-contracts";
19
+ /** A request hint. Interactive requests may use the server's reserved capacity. */
20
+ export type RequestPriority = "normal" | "interactive";
19
21
  /**
20
22
  * Public client configuration. Intentionally minimal: a base URL and an API key. Host-local
21
23
  * concerns required by the current slice (owner identity, registry, direct database access) live in
@@ -23,6 +25,11 @@ import type { ConnectedAccountLogin, ConnectedAccountLoginClass, ForwardBinding,
23
25
  * when the Effect core lands.
24
26
  */
25
27
  export interface SealantConfig {
28
+ /**
29
+ * Request priority, resolved at each HTTP dispatch. A configured value or provider overrides
30
+ * operation defaults. When unset, requests use normal priority and controls use interactive.
31
+ */
32
+ readonly requestPriority?: RequestPriority | (() => RequestPriority);
26
33
  /** Base URL of the Sealant control-plane API (e.g. `http://localhost:8080`). */
27
34
  readonly baseUrl: string;
28
35
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sealant/sdk-next",
3
- "version": "0.40.0-next.784",
3
+ "version": "0.40.0-next.786",
4
4
  "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -26,12 +26,12 @@
26
26
  "node": ">=20"
27
27
  },
28
28
  "dependencies": {
29
- "@sealant/api-contracts": "npm:@sealant/api-contracts-next@0.40.0-next.784"
29
+ "@sealant/api-contracts": "npm:@sealant/api-contracts-next@0.40.0-next.786"
30
30
  },
31
31
  "peerDependencies": {
32
32
  "effect": "^4.0.5"
33
33
  },
34
- "gitHead": "7a1ab24adbf054ba14347516e5a0680e330f3e5e",
34
+ "gitHead": "1c95b9b2df6c068034efdcdeb05d253e5e842100",
35
35
  "publishConfig": {
36
36
  "access": "public"
37
37
  }