@celestia-island/plana-types 0.1.4 → 0.1.5

package/bindings/gateway.ts

@@ -135,7 +135,28 @@ export type QuotaState = { remaining: bigint, limit: bigint, allowed: boolean, }
  * `rescue.diagnose` params. The diagnostics bundle is opaque to the
  * protocol (the model defines its shape).
  */
-export type RescueDiagnoseParams = { bundle: JsonValue, };
+export type RescueDiagnoseParams = { bundle: JsonValue, 
+/**
+ * Ask for deferred mode (default false = the blocking behaviour that
+ * every current deployment serves).
+ *
+ * The diagnostic LLM call has a budget of minutes, which far exceeds
+ * the service profile's dispatch stall limit (a liveness guard measured
+ * in seconds — see `plana-rpc-server`'s crate docs). A server that
+ * implements deferred mode answers `deferred: true` immediately with
+ * [`RescueDiagnoseStarted`] instead of holding the dispatch, and the
+ * caller collects the [`RescueDiagnoseResult`] through the built-in
+ * deferred-op methods (`ops.result {op_id}` / the advisory
+ * `ops.settled` notification).
+ *
+ * **Adoption is a follow-up**: the reference gateway still drops this
+ * flag and blocks until the model returns, so a client must not send
+ * `deferred: true` until its target deployment has adopted it (it will
+ * otherwise block, and answer the stall error past the limit). The flag
+ * is defined here so the adoption is mechanical, and it is additive: a
+ * server that ignores it keeps behaving exactly as before.
+ */
+deferred?: boolean, };
 
 /**
  * `rescue.diagnose.progress` notification params.
@@ -147,7 +168,16 @@ export type RescueDiagnoseProgressParams = {
 step: number, };
 
 /**
- * `rescue.diagnose` result.
+ * `rescue.diagnose` result. Exactly one of the two shapes is returned,
+ * selected by [`RescueDiagnoseParams::deferred`]:
+ *
+ * - `deferred: false` (default) → a completed diagnosis.
+ * - `deferred: true` → [`RescueDiagnoseStarted`]: the op reference and its
+ *   validity window.
+ *
+ * A client tells them apart by the presence of `op_id` (the deferred start)
+ * versus `diagnosis` (the completed result); the two shapes share no field
+ * name, so the discrimination is unambiguous.
  */
 export type RescueDiagnoseResult = { 
 /**
@@ -163,6 +193,28 @@ model: string,
  */
 generated_at: string, };
 
+/**
+ * `rescue.diagnose` result when [`RescueDiagnoseParams::deferred`] is set:
+ * the work was handed off, this is what to collect it with.
+ *
+ * The shape is the generic deferred-op answer
+ * (`plana::jsonrpc::deferred::DeferredOpCreated`) — declared here as well so
+ * the gateway's published TypeScript bindings carry it without depending on
+ * a generated file outside this package. [`DeferredOpCreated`] remains the
+ * canonical definition; a parity test pins the two to the same wire shape.
+ */
+export type RescueDiagnoseStarted = { 
+/**
+ * Opaque, unguessable deferred-operation reference.
+ */
+op_id: string, 
+/**
+ * Remaining validity of `op_id` in seconds, measured from creation
+ * (the 10–30 minute band; the collect call still works after a
+ * reconnect inside the window).
+ */
+expires_in: bigint, };
+
 /**
  * `rescue.open_session` params. The ticket is the one-shot opaque
  * credential issued by the OAuth callback redirect; it is consumed

package/bindings/ops.ts

@@ -0,0 +1,149 @@
+// Vendored snapshot of packages/plana/bindings/ops.ts (ts-rs generated) so the
+// published npm tarball carries the deferred-operation wire shapes: npm `files`
+// cannot reach a sibling package's directory, exactly as with
+// `protocol-core-httpTypes.ts` above. Re-sync after `cargo test -p plana`
+// whenever the deferred types in packages/plana/src/jsonrpc/deferred.rs or the
+// JSON-RPC error object change.
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { JsonValue } from "./serde_json/JsonValue";
+
+/**
+ * Immediate answer of a handler that switched to deferred mode.
+ *
+ * `expires_in` is the **remaining** validity in seconds measured from
+ * creation, not from the moment of serialization — a client that reconnects
+ * half-way through the window sees the shrunk remainder.
+ */
+export type DeferredOpCreated = { 
+/**
+ * The opaque client-facing reference.
+ */
+op_id: DeferredOpRef, 
+/**
+ * Remaining validity of `op_id`, in seconds.
+ */
+expires_in: bigint, };
+
+/**
+ * Current state of a deferred operation, as answered by `ops.result`.
+ *
+ * Exactly one of `result` / `error` is present once the status is terminal;
+ * both are absent while the status is `pending`.
+ */
+export type DeferredOpOutcome = { 
+/**
+ * The collected reference (echoed so a multiplexed client can route).
+ */
+op_id: DeferredOpRef, 
+/**
+ * Current lifecycle status.
+ */
+status: DeferredOpStatus, 
+/**
+ * The method whose handler deferred the work — audit and debugging
+ * surface; the outcome is meaningless without knowing what it is a
+ * result of.
+ */
+method: string, 
+/**
+ * Remaining validity of this entry, in seconds. Once it reaches zero the
+ * entry is gone and the id answers `-32053`.
+ */
+expires_in: bigint, 
+/**
+ * Whether a cancellation was requested through `ops.cancel` while the
+ * operation was still pending (advisory — the worker may not honour it).
+ */
+cancel_requested: boolean, 
+/**
+ * Present iff `status == completed`.
+ */
+result?: JsonValue, 
+/**
+ * Present iff `status == failed`.
+ */
+error?: JsonRpcError, };
+
+/**
+ * Client-facing reference to a deferred operation.
+ *
+ * Opaque, unguessable and stable for the whole validity window: the id is
+ * the same string before and after a reconnect, so a client (or a different
+ * client, e.g. a browser tab resuming a rescue session) can collect with it
+ * while the entry is retained — the registry's retention cap can evict a
+ * settled outcome early, the id string itself never changes. Treat it as a
+ * bearer value — whoever holds it can read the outcome.
+ */
+export type DeferredOpRef = string;
+
+/**
+ * `ops.settled` notification params.
+ *
+ * Advisory only: it says *that* an operation settled, never *what* it
+ * produced — the client still calls `ops.result` to collect the payload.
+ * That keeps a single authoritative collection path.
+ */
+export type DeferredOpSettledParams = { 
+/**
+ * The reference that settled.
+ */
+op_id: DeferredOpRef, 
+/**
+ * Its new status.
+ */
+status: DeferredOpStatus, };
+
+/**
+ * Lifecycle of a deferred operation.
+ *
+ * A cancellation request does **not** add a state: `ops.cancel` only sets a
+ * flag the worker may observe, and a cancelled operation settles as
+ * [`DeferredOpStatus::Failed`] with `-32055` (`error_codes::OPS_CANCELLED`)
+ * when the worker honours it. That keeps the state machine to the three
+ * states a client actually has to handle.
+ */
+export type DeferredOpStatus = "pending" | "completed" | "failed";
+
+/**
+ * The JSON-RPC 2.0 error object. Also generated into the TypeScript
+ * bindings, because it is the payload a client must parse out of a
+ * deferred outcome (`plana::jsonrpc::deferred`).
+ */
+export type JsonRpcError = { code: bigint, message: string, data?: JsonValue, };
+
+/**
+ * `ops.cancel` params.
+ */
+export type OpsCancelParams = { 
+/**
+ * The reference to ask cancellation for.
+ */
+op_id: DeferredOpRef, };
+
+/**
+ * `ops.cancel` result.
+ */
+export type OpsCancelResult = { 
+/**
+ * The reference the request was recorded for.
+ */
+op_id: DeferredOpRef, 
+/**
+ * The status observed at request time.
+ */
+status: DeferredOpStatus, 
+/**
+ * True when the request was recorded for a still-pending operation (so
+ * the worker can observe it); false when the operation had already
+ * settled and there was nothing to cancel.
+ */
+cancel_requested: boolean, };
+
+/**
+ * `ops.result` params.
+ */
+export type OpsResultParams = { 
+/**
+ * The reference to collect.
+ */
+op_id: DeferredOpRef, };

package/bindings/protocol-core-httpTypes.ts

@@ -1,10 +1,11 @@
-// Vendored snapshot of packages/protocol-core/bindings/httpTypes.ts (ts-rs
-// generated) so the published npm tarball is self-contained: npm `files`
-// cannot reach parent directories, and index.ts previously imported
-// `../protocol-core/bindings/httpTypes`, which is absent from the tarball and
-// breaks registry installs. Distinct filename to avoid colliding with this
-// crate's own ts-rs-generated bindings/httpTypes.ts. Re-sync when
-// protocol-core's HttpTypes bindings change.
+// Vendored snapshot of the plana foundation's generated bindings
+// (packages/plana/bindings/httpTypes.ts — the former
+// packages/protocol-core/bindings/httpTypes.ts, which the protocol-core
+// re-export shim no longer owns) so the published npm tarball is
+// self-contained: npm `files` cannot reach a sibling package's directory.
+// Distinct filename to avoid colliding with this crate's own ts-rs-generated
+// bindings/httpTypes.ts. Re-sync when the foundation's HttpTypes bindings
+// change (`cargo test -p plana` then re-copy).
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
 
 /**

package/index.ts

@@ -39,6 +39,9 @@ export * from "./bindings/gateway";
 export * from "./bindings/httpTypes";
 export * from "./bindings/mdd";
 export * from "./bindings/model";
+// Deferred-operation wire shapes (vendored snapshot of plana's generated
+// bindings): no name on this file's surface collides with the exports above.
+export * from "./bindings/ops";
 export * from "./bindings/ws/agentLifecycle";
 export * from "./bindings/ws/auth";
 export * from "./bindings/ws/bridgeNetwork";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/plana-types",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/celestia-island/plana"