@owlmeans/viable-common 0.0.11 → 0.0.13

package/src/connect/consts.ts

@@ -67,8 +67,20 @@ export enum ConnectExecutor {
   Files = 'files',
   Shell = 'shell',
   Git = 'git',
-  /** The parent agent will answer model tasks. Present exactly when `llm` is `Local`. */
+  /**
+   * The parent agent PERFORMS the model calls of a run: each one arrives as a `ModelTask`, is run
+   * in a clean subagent and submitted back. Present exactly when `llm` is `Local`.
+   */
   Model = 'model',
+  /**
+   * A PERSON can be asked a question and their answer brought back.
+   *
+   * Advertised always, and by every connector: a parent agent has a human in front of it by
+   * definition, which is the whole reason the platform can ask one anything at all. It is not a
+   * narrower `Model` — a model task is inference the platform pays for either way, an inquiry is
+   * a decision only a person can make, and a run that cannot ask assumes instead.
+   */
+  Human = 'human',
 }
 
 /** What one operation asks a connector to do. */
@@ -79,6 +91,14 @@ export enum ConnectOpKind {
   ModelTask = 'model-task',
   /** Write the target's configuration (its `.env` files) and report what services are reachable. */
   Configure = 'configure',
+  /**
+   * Put one question to the person the connector is working for, and bring back their answer.
+   *
+   * An operation like any other — queued to the project, redelivered to whichever session is
+   * attached, answered against its own op id — because the alternative was a second channel with
+   * its own delivery, expiry and reattachment rules for the one payload that already had them.
+   */
+  Inquiry = 'inquiry',
 }
 
 /** How a connector is receiving operations. */
@@ -197,6 +217,18 @@ export enum ConnectJobKind {
   StoryDevelop = 'story-develop',
   FreeFlight = 'free-flight',
   PipelineResume = 'pipeline-resume',
+  /**
+   * The four stages of a conversion, plus the purge.
+   *
+   * One kind per stage rather than one for the whole conversion: each stage is its own platform
+   * pipeline run, ends at a decision the user makes, and is looked up by the pipeline alias its
+   * kind names. A single `convert` kind would match whichever run row happened to be newest.
+   */
+  ConvertIntake = 'convert-intake',
+  ConvertAnalysis = 'convert-analysis',
+  ConvertExtraction = 'convert-extraction',
+  ConvertImplementation = 'convert-implementation',
+  ConvertPurge = 'convert-purge',
 }
 
 export enum ConnectJobStatus {
@@ -216,8 +248,50 @@ export enum ConnectJobBlock {
   LocalOp = 'local-op',
   /** The local target has no database configured and the run needs one. */
   Env = 'env',
+  /** A question is waiting for a person and nobody has answered it. */
+  Question = 'question',
 }
 
+/**
+ * The shapes a question can take on the wire.
+ *
+ * Mirrors `InquiryKind` in `@owlmeans/llm-common` value for value, and is deliberately a SEPARATE
+ * name rather than an import: the connect module is the wire contract and owns its own vocabulary
+ * — the same reason `ModelTask` mirrors `DelegatedTask` — which also keeps `manager-api`, which
+ * does not depend on the model runtime, free of `@owlmeans/llm-common`. Values are byte-identical,
+ * so the platform's mapper is a widening rather than a translation table, and a test pins that.
+ */
+export enum ConnectInquiryKind {
+  /** Pick one of the offered options, or several when `multiple` is set. */
+  Choice = 'choice',
+  /** Free text. */
+  Text = 'text',
+  /** Yes or no. */
+  Confirm = 'confirm',
+}
+
+/**
+ * How long the platform waits for a person to answer one question.
+ *
+ * The same forty-five minutes a model task gets, and for the same reason: the bound exists so a
+ * parent that has gone away eventually fails the step rather than holding a project lock forever,
+ * not to pace somebody who is thinking.
+ */
+export const CONNECT_INQUIRY_TIMEOUT_MS = 2_700_000
+
+/** Options one choice question may offer. Beyond this it is a text question with a hint. */
+export const CONNECT_INQUIRY_MAX_OPTIONS = 12
+
+/**
+ * The ceiling on an answer's text.
+ *
+ * ONE ceiling for the whole stack: the twin is `DEFAULT_INQUIRY_ANSWER_CHARS` in
+ * `@owlmeans/llm-common`, and the two must stay equal. Two ceilings means the layer with the
+ * larger one truncates silently at the smaller, and the caller records an assumption about an
+ * answer the person actually gave.
+ */
+export const CONNECT_INQUIRY_MAX_TEXT = 2_000
+
 /**
  * How long a session survives without a sign of life.
  *
@@ -295,6 +369,7 @@ export const CONNECT_EVENT_SESSION = 'connect:session'
 export const CONNECT_OP_PUBSUB = 'connect-op-pubsub'
 export const CONNECT_RESULT_PUBSUB = 'connect-result-pubsub'
 export const CONNECT_OP_STORE = 'connect-op-store'
+export const CONNECT_RESULT_STORE = 'connect-result-store'
 export const CONNECT_SESSION_PUBSUB = 'connect-session-pubsub'
 
 /** The backend resource alias for session records. */
@@ -333,8 +408,22 @@ export const connect = Object.freeze({
     modify: 'viable:manager-api:connect:project:modify',
     settings: 'viable:manager-api:connect:project:settings',
     llm: 'viable:manager-api:connect:project:llm',
+    /** The per-project converter inference mode. Separate from `llm`: it is not a paid capability. */
+    converterLlm: 'viable:manager-api:connect:project:converter-llm',
     job: 'viable:manager-api:connect:project:job',
   }),
+  convert: Object.freeze({
+    create: 'viable:manager-api:connect:convert:create',
+    check: 'viable:manager-api:connect:convert:check',
+    start: 'viable:manager-api:connect:convert:start',
+    proceed: 'viable:manager-api:connect:convert:proceed',
+    cancel: 'viable:manager-api:connect:convert:cancel',
+    status: 'viable:manager-api:connect:convert:status',
+    purge: 'viable:manager-api:connect:convert:purge',
+  }),
+  inquiry: Object.freeze({
+    answer: 'viable:manager-api:connect:inquiry:answer',
+  }),
   story: Object.freeze({
     list: 'viable:manager-api:connect:story:list',
     get: 'viable:manager-api:connect:story:get',
@@ -343,6 +432,9 @@ export const connect = Object.freeze({
     delete: 'viable:manager-api:connect:story:delete',
     develop: 'viable:manager-api:connect:story:develop',
   }),
+  files: Object.freeze({
+    list: 'viable:manager-api:connect:files:list',
+  }),
   pipeline: Object.freeze({
     state: 'viable:manager-api:connect:pipeline:state',
     resume: 'viable:manager-api:connect:pipeline:resume',

package/src/connect/entrypoints.ts

@@ -1,20 +1,26 @@
 import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
-import type { EntrypointTree } from '@owlmeans/entrypoint'
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
 import { route, RouteMethod, socket } from '@owlmeans/route'
+import { ConverterProjectLlmBodySchema } from '../convert/schemas.js'
 import { connect } from './consts.js'
 import {
-  ConnectAttachBodySchema, ConnectConfirmBodySchema, ConnectCreateBodySchema,
+  ConnectAttachBodySchema, ConnectConfirmBodySchema, ConnectConvertCreateBodySchema,
+  ConnectConvertProceedBodySchema, ConnectCreateBodySchema, ConnectInquiryParamsSchema,
   ConnectJobParamsSchema, ConnectModifyBodySchema, ConnectOpParamsSchema, ConnectOpResultSchema,
   ConnectPipelineParamsSchema, ConnectPipelineResumeBodySchema, ConnectProjectIdSchema,
   ConnectProjectLlmBodySchema, ConnectSessionOpenSchema, ConnectSessionParamsSchema,
-  ConnectStoryBodySchema, ConnectStoryParamsSchema, ConnectStoryQuerySchema, ConnectWaitQuerySchema
+  ConnectStoryBodySchema, ConnectStoryParamsSchema, ConnectStoryQuerySchema, ConnectWaitQuerySchema,
+  InquiryAnswerSchema,
 } from './schemas.js'
 import type {
-  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectJobParams, ConnectModifyBody,
+  ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
+  ConnectCreateBody, ConnectInquiryAnswerBody, ConnectJob, ConnectJobParams, ConnectModifyBody,
   ConnectPipelineParams, ConnectPipelineResumeBody, ConnectProjectLlmBody, ConnectSessionOpen,
-  ConnectSessionParams, ConnectStoryBody, ConnectStoryQuery, ConnectWaitQuery,
+  ConnectSessionParams, ConnectStoryBody, ConnectStoryQuery, ConnectWaitQuery, ConversionStatusView,
+  ConvertCheck,
 } from './types.js'
 import type { ConnectOpResult } from './ops.js'
+import type { ConverterProjectLlmBody } from '../convert/types.js'
 
 /**
  * What the platform injects when it mounts the connector routes.
@@ -36,8 +42,8 @@ export interface ConnectEntrypointOptions {
    * back by itself when a plan lapses.
    */
   localLlm?: { alias: string, params: string[] }
-  /** The parent of the socket route — the platform's own websocket base. */
-  updateBase: string
+  /** The platform-owned websocket-base protocol that carries session updates. */
+  updateBase: EntrypointProtocol<OpenRequest, OpenValue>
   /** Path prefix; defaults to `/connect`. */
   path?: string
 }
@@ -49,7 +55,7 @@ export interface ConnectEntrypointOptions {
  * server-side and onto client entrypoints in the SDK — the same declarations both times, which is
  * what makes a path or a schema impossible to get wrong on one side only.
  */
-export const connectProtocols = (opts: ConnectEntrypointOptions): EntrypointTree => {
+export const connectProtocols = (opts: ConnectEntrypointOptions) => {
   const prefix = opts.path ?? '/connect'
   const ownership = opts.gate != null
     ? { guards: opts.guard, gate: opts.gate }
@@ -58,45 +64,48 @@ export const connectProtocols = (opts: ConnectEntrypointOptions): EntrypointTree
     ? { gate: opts.localLlm }
     : undefined
 
+  const base = openProtocol(route(connect.base, prefix), ownership)
+
   return {
-    base: openProtocol(route(connect.base, prefix), ownership),
+    base,
 
-    capabilities: openProtocol(route(connect.capabilities, '/capabilities', {
-      parent: connect.base, method: RouteMethod.GET
-    })),
+    capabilities: protocol(
+      route(connect.capabilities, '/capabilities', { parent: base, method: RouteMethod.GET }),
+      contract(typed()),
+    ),
 
     // --- session ---------------------------------------------------------------------------
     session: {
     open: protocol(
-      route(connect.session.open, '/session', { parent: connect.base, method: RouteMethod.POST }),
+      route(connect.session.open, '/session', { parent: base, method: RouteMethod.POST }),
       contract.request({ body: typed<ConnectSessionOpen>(ConnectSessionOpenSchema) }, typed())
     ),
     openDelegated: protocol(
       route(connect.session.openDelegated, '/session/delegated', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ body: typed<ConnectSessionOpen>(ConnectSessionOpenSchema) }, typed()), paid
     ),
     get: protocol(
       route(connect.session.get, '/session/:sessionId', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
     ),
     heartbeat: protocol(
       route(connect.session.heartbeat, '/session/:sessionId/heartbeat', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
     ),
     close: protocol(
       route(connect.session.close, '/session/:sessionId/close', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
     ),
     socket: protocol(
-      route(connect.session.socket, '/connect/:sessionId', socket(opts.updateBase)),
+      route(connect.session.socket, '/connect/:sessionId', socket({ parent: opts.updateBase })),
       contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema) }, typed())
     ),
 
@@ -106,13 +115,13 @@ export const connectProtocols = (opts: ConnectEntrypointOptions): EntrypointTree
     op: {
     pull: protocol(
       route(connect.op.pull, '/session/:sessionId/ops', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema), query: typed<ConnectWaitQuery>(ConnectWaitQuerySchema) }, typed())
     ),
     submit: protocol(
       route(connect.op.submit, '/session/:sessionId/ops/:opId', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<{ sessionId: string, opId: string }>(ConnectOpParamsSchema), body: typed<ConnectOpResult>(ConnectOpResultSchema) }, typed())
     ),
@@ -122,57 +131,67 @@ export const connectProtocols = (opts: ConnectEntrypointOptions): EntrypointTree
     // --- project ---------------------------------------------------------------------------
     project: {
     create: protocol(
-      route(connect.project.create, '/project', { parent: connect.base, method: RouteMethod.POST }),
+      route(connect.project.create, '/project', { parent: base, method: RouteMethod.POST }),
       contract.request({ body: typed<ConnectCreateBody>(ConnectCreateBodySchema) }, typed())
     ),
-    list: openProtocol(route(connect.project.list, '/project', {
-      parent: connect.base, method: RouteMethod.GET
-    })),
+    list: protocol(
+      route(connect.project.list, '/project', { parent: base, method: RouteMethod.GET }),
+      contract(typed()),
+    ),
     attach: protocol(
       route(connect.project.attach, '/project/attach', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ body: typed<ConnectAttachBody>(ConnectAttachBodySchema) }, typed())
     ),
     confirm: protocol(
       route(connect.project.confirm, '/project/:id/confirm', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectConfirmBody>(ConnectConfirmBodySchema) }, typed())
     ),
     status: protocol(
       route(connect.project.status, '/project/:id/status', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed())
     ),
     reinit: protocol(
       route(connect.project.reinit, '/project/:id/reinit', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed())
     ),
     modify: protocol(
       route(connect.project.modify, '/project/:id/modify', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectModifyBody>(ConnectModifyBodySchema) }, typed())
     ),
     settings: protocol(
       route(connect.project.settings, '/project/:id/settings', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed())
     ),
     llm: protocol(
       route(connect.project.llm, '/project/:id/llm', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectProjectLlmBody>(ConnectProjectLlmBodySchema) }, typed()), paid
     ),
+    converterLlm: protocol(
+      route(connect.project.converterLlm, '/project/:id/converter-llm', {
+        parent: base, method: RouteMethod.POST,
+      }),
+      contract.request({
+        params: typed<{ id: string }>(ConnectProjectIdSchema),
+        body: typed<ConverterProjectLlmBody>(ConverterProjectLlmBodySchema),
+      }, typed()),
+    ),
     job: protocol(
       route(connect.project.job, '/project/:id/job/:jobId', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<ConnectJobParams>(ConnectJobParamsSchema), query: typed<ConnectWaitQuery>(ConnectWaitQuerySchema) }, typed())
     ),
@@ -182,51 +201,105 @@ export const connectProtocols = (opts: ConnectEntrypointOptions): EntrypointTree
     // --- stories ---------------------------------------------------------------------------
     story: {
     list: protocol(
-      route(connect.story.list, '/story/:id', { parent: connect.base, method: RouteMethod.GET }),
+      route(connect.story.list, '/story/:id', { parent: base, method: RouteMethod.GET }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), query: typed<ConnectStoryQuery>(ConnectStoryQuerySchema) }, typed())
     ),
     create: protocol(
-      route(connect.story.create, '/story/:id', { parent: connect.base, method: RouteMethod.POST }),
+      route(connect.story.create, '/story/:id', { parent: base, method: RouteMethod.POST }),
       contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectStoryBody>(ConnectStoryBodySchema) }, typed())
     ),
     get: protocol(
       route(connect.story.get, '/story/:id/:storyId', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<{ id: string, storyId: string }>(ConnectStoryParamsSchema) }, typed())
     ),
     update: protocol(
       route(connect.story.update, '/story/:id/:storyId', {
-        parent: connect.base, method: RouteMethod.PUT
+        parent: base, method: RouteMethod.PUT
       }),
       contract.request({ params: typed<{ id: string, storyId: string }>(ConnectStoryParamsSchema), body: typed<ConnectStoryBody>(ConnectStoryBodySchema) }, typed())
     ),
     delete: protocol(
       route(connect.story.delete, '/story/:id/:storyId', {
-        parent: connect.base, method: RouteMethod.DELETE
+        parent: base, method: RouteMethod.DELETE
       }),
       contract.request({ params: typed<{ id: string, storyId: string }>(ConnectStoryParamsSchema) }, typed())
     ),
     develop: protocol(
       route(connect.story.develop, '/story/:id/:storyId/develop', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<{ id: string, storyId: string }>(ConnectStoryParamsSchema) }, typed())
     ),
 
     },
 
+    // --- generated files and conversion ----------------------------------------------------
+    files: {
+    list: protocol(
+      route(connect.files.list, '/project/:id/files', { parent: base, method: RouteMethod.GET }),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<string[]>()),
+    ),
+    },
+
+    convert: {
+    create: protocol(
+      route(connect.convert.create, '/convert', { parent: base, method: RouteMethod.POST }),
+      contract.request({ body: typed<ConnectConvertCreateBody>(ConnectConvertCreateBodySchema) }, typed<ConnectJob>()),
+    ),
+    check: protocol(
+      route(connect.convert.check, '/convert/:id/check', { parent: base, method: RouteMethod.GET }),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConvertCheck>()),
+    ),
+    start: protocol(
+      route(connect.convert.start, '/convert/:id/start', { parent: base, method: RouteMethod.POST }),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectJob>()),
+    ),
+    proceed: protocol(
+      route(connect.convert.proceed, '/convert/:id/proceed', { parent: base, method: RouteMethod.POST }),
+      contract.request({
+        params: typed<{ id: string }>(ConnectProjectIdSchema),
+        body: typed<ConnectConvertProceedBody>(ConnectConvertProceedBodySchema),
+      }, typed<ConnectJob>()),
+    ),
+    cancel: protocol(
+      route(connect.convert.cancel, '/convert/:id/cancel', { parent: base, method: RouteMethod.POST }),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectJob>()),
+    ),
+    status: protocol(
+      route(connect.convert.status, '/convert/:id', { parent: base, method: RouteMethod.GET }),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),
+    ),
+    purge: protocol(
+      route(connect.convert.purge, '/convert/:id/purge', { parent: base, method: RouteMethod.POST }),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectJob>()),
+    ),
+    },
+
+    inquiry: {
+    answer: protocol(
+      route(connect.inquiry.answer, '/project/:id/inquiry/:inquiryId', {
+        parent: base, method: RouteMethod.POST,
+      }),
+      contract.request({
+        params: typed<{ id: string, inquiryId: string }>(ConnectInquiryParamsSchema),
+        body: typed<ConnectInquiryAnswerBody>(InquiryAnswerSchema),
+      }, typed()),
+    ),
+    },
+
     // --- pipelines -------------------------------------------------------------------------
     pipeline: {
     state: protocol(
       route(connect.pipeline.state, '/pipeline/:id/:runId', {
-        parent: connect.base, method: RouteMethod.GET
+        parent: base, method: RouteMethod.GET
       }),
       contract.request({ params: typed<ConnectPipelineParams>(ConnectPipelineParamsSchema) }, typed())
     ),
     resume: protocol(
       route(connect.pipeline.resume, '/pipeline/:id/:runId/resume', {
-        parent: connect.base, method: RouteMethod.POST
+        parent: base, method: RouteMethod.POST
       }),
       contract.request({ params: typed<ConnectPipelineParams>(ConnectPipelineParamsSchema), body: typed<ConnectPipelineResumeBody>(ConnectPipelineResumeBodySchema) }, typed())
     ),

package/src/connect/errors.ts

@@ -82,6 +82,49 @@ export class ConnectOpUnknown extends ConnectError {
   }
 }
 
+/**
+ * The organization cannot pay for the action a connector just asked for.
+ *
+ * Only `type` and `message` survive a marshal/unmarshal round trip, so the fields a caller needs
+ * to phrase a kind refusal — which action, how short, and where to top up — travel packed into the
+ * message and are parsed back out in `finalizeUnmarshal()`. The URL is `encodeURIComponent`-ed
+ * because it is the one field that could itself contain a colon.
+ */
+export class ConnectOutOfCredits extends ConnectError {
+  public static override typeName = `OutOfCredits${ConnectError.typeName}`
+
+  public gate = ''
+  public requiredUsd = 0
+  public balanceUsd = 0
+  public topUpUrl = ''
+
+  /** Build the packed message a caller passes to the constructor. */
+  static encode(gate: string, requiredUsd: number, balanceUsd: number, topUpUrl: string): string {
+    return `${gate}:${requiredUsd}:${balanceUsd}:${encodeURIComponent(topUpUrl)}`
+  }
+
+  constructor(message: string = 'error') {
+    super(`out-of-credits:${message}`)
+    this.type = ConnectOutOfCredits.typeName
+    this.applyFields()
+  }
+
+  private applyFields(): void {
+    const marker = 'out-of-credits:'
+    const at = this.message.indexOf(marker)
+    if (at < 0) return
+    const [gate, requiredUsd, balanceUsd, encodedUrl] = this.message.slice(at + marker.length).split(':')
+    this.gate = gate ?? ''
+    this.requiredUsd = Number(requiredUsd ?? 0) || 0
+    this.balanceUsd = Number(balanceUsd ?? 0) || 0
+    this.topUpUrl = encodedUrl != null && encodedUrl !== '' ? decodeURIComponent(encodedUrl) : ''
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyFields()
+  }
+}
+
 ResilientError.registerErrorClass(ConnectError)
 ResilientError.registerErrorClass(ConnectSessionNotFound)
 ResilientError.registerErrorClass(ConnectSessionGone)
@@ -89,3 +132,4 @@ ResilientError.registerErrorClass(ConnectOpTimeout)
 ResilientError.registerErrorClass(ConnectOpRefused)
 ResilientError.registerErrorClass(LocalSlotUnsupported)
 ResilientError.registerErrorClass(ConnectOpUnknown)
+ResilientError.registerErrorClass(ConnectOutOfCredits)

package/src/connect/ops.ts

@@ -1,6 +1,7 @@
 import type { SlotCommandPayload } from '../slot/index.js'
 import type {
-  ConnectOpErrorKind, ConnectOpKind, ModelTaskMode, ModelTaskResultKind, ModelTaskRole, ModelTier
+  ConnectInquiryKind, ConnectOpErrorKind, ConnectOpKind, ModelTaskMode, ModelTaskResultKind,
+  ModelTaskRole, ModelTier
 } from './consts.js'
 import type { ConnectServices } from './types.js'
 
@@ -17,7 +18,7 @@ export interface ConnectOp {
   projectId: string
   sessionId: string
   kind: ConnectOpKind
-  payload: SlotCommandPayload | ModelTask | ConfigurePayload
+  payload: SlotCommandPayload | ModelTask | ConfigurePayload | InquiryPayload
   createdAt: string
   /** When the asker stops waiting. A connector past this may skip the work and say so. */
   deadlineAt: string
@@ -158,3 +159,50 @@ export interface ModelTaskUsage {
   inputTokens?: number
   outputTokens?: number
 }
+
+/** One option a {@link ConnectInquiryKind.Choice} question offers. */
+export interface ConnectInquiryOption {
+  value: string
+  label: string
+  description?: string
+}
+
+/**
+ * One question put to the person the connector is working for.
+ *
+ * It carries where it came from — the job, the run and the step — because an answer is recorded
+ * against the run that asked and re-read when that run resumes. `expiresAt` is what makes an
+ * unanswered question fail its step instead of parking a project lock forever.
+ */
+export interface InquiryPayload {
+  id: string
+  projectId: string
+  jobId?: string
+  runId?: string
+  /** The pipeline step that asked, so a resumed run can match the answer to the place it belongs. */
+  step?: string
+  kind: ConnectInquiryKind
+  question: string
+  /** What the asker already knows, so the person is not asked to go and find it out. */
+  context?: string
+  options?: ConnectInquiryOption[]
+  multiple?: boolean
+  /** Whether a choice question also accepts text the options do not cover. */
+  allowText?: boolean
+  /** What the asker will assume if nobody answers. Recorded as an assumption when it is used. */
+  default?: string | string[]
+  expiresAt: string
+}
+
+/**
+ * The answer to one question.
+ *
+ * `declined` is a real answer and not an absence: it says a person saw the question and chose not
+ * to decide, which the asker records as an assumption rather than waiting out the timeout.
+ */
+export interface InquiryAnswerPayload {
+  inquiryId: string
+  value?: string | string[]
+  text?: string
+  declined?: boolean
+}