@owlmeans/viable-common 0.0.23 → 0.0.25

package/src/connect/entrypoints.ts

@@ -6,16 +6,17 @@ import { connect } from './consts.js'
 import {
   ConnectAttachBodySchema, ConnectConfirmBodySchema, ConnectConvertCreateBodySchema,
   ConnectConvertProceedBodySchema, ConnectCreateBodySchema, ConnectInquiryParamsSchema,
-  ConnectJobParamsSchema, ConnectModifyBodySchema, ConnectOpParamsSchema, ConnectOpResultSchema,
+  ConnectModifyBodySchema, ConnectOpParamsSchema, ConnectOpResultSchema,
   ConnectPipelineParamsSchema, ConnectPipelineResumeBodySchema, ConnectProjectIdSchema,
   ConnectProjectLlmBodySchema, ConnectSessionOpenSchema, ConnectSessionParamsSchema,
-  ConnectWaitQuerySchema, InquiryAnswerSchema,
+  ConnectPullQuerySchema, ConnectStoryParamsSchema, InquiryAnswerSchema,
 } from './schemas.js'
 import type {
   ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
-  ConnectCreateBody, ConnectInquiryAnswerBody, ConnectJob, ConnectJobParams, ConnectModifyBody,
+  ConnectCreateBody, ConnectInquiryAnswerBody, ConnectModifyBody,
   ConnectPipelineParams, ConnectPipelineResumeBody, ConnectProjectLlmBody, ConnectSessionOpen,
-  ConnectSessionParams, ConnectWaitQuery, ConversionStatusView, ConvertCheck,
+  ConnectPipelineState, ConnectProjectStatus, ConnectPullQuery, ConnectSessionParams,
+  ConnectStoryStatus, ConversionStatusView, ConvertCheck,
 } from './types.js'
 import type { ConnectOpResult } from './ops.js'
 import type { ConverterProjectLlmBody } from '../convert/types.js'
@@ -115,7 +116,7 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
       route(connect.op.pull, '/session/:sessionId/ops', {
         parent: base, method: RouteMethod.GET
       }),
-      contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema), query: typed<ConnectWaitQuery>(ConnectWaitQuerySchema) }, typed())
+      contract.request({ params: typed<ConnectSessionParams>(ConnectSessionParamsSchema), query: typed<ConnectPullQuery>(ConnectPullQuerySchema) }, typed())
     ),
     submit: protocol(
       route(connect.op.submit, '/session/:sessionId/ops/:opId', {
@@ -130,7 +131,7 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
     project: {
     create: protocol(
       route(connect.project.create, '/project', { parent: base, method: RouteMethod.POST }),
-      contract.request({ body: typed<ConnectCreateBody>(ConnectCreateBodySchema) }, typed())
+      contract.request({ body: typed<ConnectCreateBody>(ConnectCreateBodySchema) }, typed<ConnectProjectStatus>())
     ),
     list: protocol(
       route(connect.project.list, '/project', { parent: base, method: RouteMethod.GET }),
@@ -146,25 +147,25 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
       route(connect.project.confirm, '/project/:id/confirm', {
         parent: base, method: RouteMethod.POST
       }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectConfirmBody>(ConnectConfirmBodySchema) }, typed())
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectConfirmBody>(ConnectConfirmBodySchema) }, typed<ConnectProjectStatus>())
     ),
     status: protocol(
       route(connect.project.status, '/project/:id/status', {
         parent: base, method: RouteMethod.GET
       }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed())
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectProjectStatus>())
     ),
     reinit: protocol(
       route(connect.project.reinit, '/project/:id/reinit', {
         parent: base, method: RouteMethod.POST
       }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed())
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectProjectStatus>())
     ),
     modify: protocol(
       route(connect.project.modify, '/project/:id/modify', {
         parent: base, method: RouteMethod.POST
       }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectModifyBody>(ConnectModifyBodySchema) }, typed())
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema), body: typed<ConnectModifyBody>(ConnectModifyBodySchema) }, typed<ConnectProjectStatus>())
     ),
     settings: protocol(
       route(connect.project.settings, '/project/:id/settings', {
@@ -187,11 +188,16 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
         body: typed<ConverterProjectLlmBody>(ConverterProjectLlmBodySchema),
       }, typed()),
     ),
-    job: protocol(
-      route(connect.project.job, '/project/:id/job/:jobId', {
+    },
+
+    story: {
+    status: protocol(
+      route(connect.story.status, '/project/:id/story/:storyId/status', {
         parent: base, method: RouteMethod.GET
       }),
-      contract.request({ params: typed<ConnectJobParams>(ConnectJobParamsSchema), query: typed<ConnectWaitQuery>(ConnectWaitQuerySchema) }, typed())
+      contract.request({
+        params: typed<{ id: string, storyId: string }>(ConnectStoryParamsSchema),
+      }, typed<ConnectStoryStatus>())
     ),
 
     },
@@ -207,7 +213,7 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
     convert: {
     create: protocol(
       route(connect.convert.create, '/convert', { parent: base, method: RouteMethod.POST }),
-      contract.request({ body: typed<ConnectConvertCreateBody>(ConnectConvertCreateBodySchema) }, typed<ConnectJob>()),
+      contract.request({ body: typed<ConnectConvertCreateBody>(ConnectConvertCreateBodySchema) }, typed<ConversionStatusView>()),
     ),
     check: protocol(
       route(connect.convert.check, '/convert/:id/check', { parent: base, method: RouteMethod.GET }),
@@ -215,18 +221,18 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
     ),
     start: protocol(
       route(connect.convert.start, '/convert/:id/start', { parent: base, method: RouteMethod.POST }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectJob>()),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),
     ),
     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>()),
+      }, typed<ConversionStatusView>()),
     ),
     cancel: protocol(
       route(connect.convert.cancel, '/convert/:id/cancel', { parent: base, method: RouteMethod.POST }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectJob>()),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),
     ),
     status: protocol(
       route(connect.convert.status, '/convert/:id', { parent: base, method: RouteMethod.GET }),
@@ -234,7 +240,7 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
     ),
     purge: protocol(
       route(connect.convert.purge, '/convert/:id/purge', { parent: base, method: RouteMethod.POST }),
-      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConnectJob>()),
+      contract.request({ params: typed<{ id: string }>(ConnectProjectIdSchema) }, typed<ConversionStatusView>()),
     ),
     },
 
@@ -256,13 +262,13 @@ export const connectProtocols = (opts: ConnectEntrypointOptions) => {
       route(connect.pipeline.state, '/pipeline/:id/:runId', {
         parent: base, method: RouteMethod.GET
       }),
-      contract.request({ params: typed<ConnectPipelineParams>(ConnectPipelineParamsSchema) }, typed())
+      contract.request({ params: typed<ConnectPipelineParams>(ConnectPipelineParamsSchema) }, typed<ConnectPipelineState>())
     ),
     resume: protocol(
       route(connect.pipeline.resume, '/pipeline/:id/:runId/resume', {
         parent: base, method: RouteMethod.POST
       }),
-      contract.request({ params: typed<ConnectPipelineParams>(ConnectPipelineParamsSchema), body: typed<ConnectPipelineResumeBody>(ConnectPipelineResumeBodySchema) }, typed())
+      contract.request({ params: typed<ConnectPipelineParams>(ConnectPipelineParamsSchema), body: typed<ConnectPipelineResumeBody>(ConnectPipelineResumeBodySchema) }, typed<ConnectPipelineState>())
     ),
     },
   }

package/src/connect/index.ts

@@ -3,6 +3,5 @@ export * from './schemas.js'
 export * from './errors.js'
 export * from './entrypoints.js'
 export * from './references.js'
-export * from './jobs.js'
 export type * from './types.js'
 export type * from './ops.js'

package/src/connect/ops.ts

@@ -91,8 +91,6 @@ export interface ConfigureResult {
 export interface ModelTask {
   id: string
   projectId: string
-  /** The job the call belongs to, so a parent can say what it is working on. */
-  jobId?: string
   /** The platform role that asked. Informational; the tier is what decides the model. */
   role: string
   tier: ModelTier
@@ -170,14 +168,13 @@ export interface ConnectInquiryOption {
 /**
  * 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
+ * It carries where it came from — 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

package/src/connect/references.ts

@@ -5,12 +5,12 @@ import { connect } from './consts.js'
 import type { ConnectOp, ConnectOpResult } from './ops.js'
 import type { ConverterProjectLlmBody } from '../convert/index.js'
 import type {
-  ConnectAttachBody, ConnectCapabilitiesView, ConnectConfirmBody, ConnectCreateBody, ConnectJob,
-  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectInquiryAnswerBody, ConnectJobParams,
+  ConnectAttachBody, ConnectCapabilitiesView, ConnectConfirmBody, ConnectCreateBody,
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectInquiryAnswerBody,
   ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody,
   ConnectPipelineState, ConnectProjectLlmBody, ConnectProjectSettings, ConnectProjectStatus,
-  ConnectProjectSummary, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView,
-  ConnectWaitQuery, ConversionStatusView, ConvertCheck,
+  ConnectProjectSummary, ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams,
+  ConnectSessionView, ConnectStoryStatus, ConversionStatusView, ConvertCheck,
 } from './types.js'
 
 type ConnectReference<Request extends RequestShape, Response> =
@@ -26,39 +26,41 @@ export interface ConnectReferences {
     close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
   }
   op: {
-    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectWaitQuery }, ConnectOp[]>
+    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>
     submit: ConnectReference<{
       params: { sessionId: string, opId: string }, body: ConnectOpResult
     }, ConnectOpSubmission>
   }
   project: {
-    create: ConnectReference<{ body: ConnectCreateBody }, ConnectJob>
-    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectJob>
+    create: ConnectReference<{ body: ConnectCreateBody }, ConnectProjectStatus>
+    confirm: ConnectReference<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>
     list: ConnectReference<{}, ConnectProjectSummary[]>
     status: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
     attach: ConnectReference<{ body: ConnectAttachBody }, ConnectProjectStatus>
-    reinit: ConnectReference<{ params: { id: string } }, ConnectJob>
-    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectJob>
+    reinit: ConnectReference<{ params: { id: string } }, ConnectProjectStatus>
+    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
     settings: ConnectReference<{ params: { id: string } }, ConnectProjectSettings>
     llm: ConnectReference<{ params: { id: string }, body: ConnectProjectLlmBody }, ConnectProjectSettings>
     converterLlm: ConnectReference<{
       params: { id: string }, body: ConverterProjectLlmBody
     }, ConnectProjectSettings>
-    job: ConnectReference<{ params: ConnectJobParams, query: ConnectWaitQuery }, ConnectJob>
+  }
+  story: {
+    status: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryStatus>
   }
   files: {
     list: ConnectReference<{ params: { id: string } }, string[]>
   }
   convert: {
-    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConnectJob>
+    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConversionStatusView>
     check: ConnectReference<{ params: { id: string } }, ConvertCheck>
-    start: ConnectReference<{ params: { id: string } }, ConnectJob>
+    start: ConnectReference<{ params: { id: string } }, ConversionStatusView>
     proceed: ConnectReference<{
       params: { id: string }, body: ConnectConvertProceedBody
-    }, ConnectJob>
-    cancel: ConnectReference<{ params: { id: string } }, ConnectJob>
+    }, ConversionStatusView>
+    cancel: ConnectReference<{ params: { id: string } }, ConversionStatusView>
     status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
-    purge: ConnectReference<{ params: { id: string } }, ConnectJob>
+    purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
   }
   inquiry: {
     answer: ConnectReference<{
@@ -69,7 +71,7 @@ export interface ConnectReferences {
     state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
     resume: ConnectReference<{
       params: ConnectPipelineParams, body: ConnectPipelineResumeBody
-    }, ConnectJob>
+    }, ConnectPipelineState>
   }
 }
 
@@ -88,19 +90,19 @@ export const connectRef: ConnectReferences = {
     close: entrypointRef<{ params: ConnectSessionParams }, ConnectSessionView>(connect.session.close),
   },
   op: {
-    pull: entrypointRef<{ params: ConnectSessionParams, query: ConnectWaitQuery }, ConnectOp[]>(connect.op.pull),
+    pull: entrypointRef<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>(connect.op.pull),
     submit: entrypointRef<{
       params: { sessionId: string, opId: string }, body: ConnectOpResult
     }, ConnectOpSubmission>(connect.op.submit),
   },
   project: {
-    create: entrypointRef<{ body: ConnectCreateBody }, ConnectJob>(connect.project.create),
-    confirm: entrypointRef<{ params: { id: string }, body: ConnectConfirmBody }, ConnectJob>(connect.project.confirm),
+    create: entrypointRef<{ body: ConnectCreateBody }, ConnectProjectStatus>(connect.project.create),
+    confirm: entrypointRef<{ params: { id: string }, body: ConnectConfirmBody }, ConnectProjectStatus>(connect.project.confirm),
     list: entrypointRef<{}, ConnectProjectSummary[]>(connect.project.list),
     status: entrypointRef<{ params: { id: string } }, ConnectProjectStatus>(connect.project.status),
     attach: entrypointRef<{ body: ConnectAttachBody }, ConnectProjectStatus>(connect.project.attach),
-    reinit: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.project.reinit),
-    modify: entrypointRef<{ params: { id: string }, body: ConnectModifyBody }, ConnectJob>(connect.project.modify),
+    reinit: entrypointRef<{ params: { id: string } }, ConnectProjectStatus>(connect.project.reinit),
+    modify: entrypointRef<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>(connect.project.modify),
     settings: entrypointRef<{ params: { id: string } }, ConnectProjectSettings>(connect.project.settings),
     llm: entrypointRef<{
       params: { id: string }, body: ConnectProjectLlmBody
@@ -108,20 +110,24 @@ export const connectRef: ConnectReferences = {
     converterLlm: entrypointRef<{
       params: { id: string }, body: ConverterProjectLlmBody
     }, ConnectProjectSettings>(connect.project.converterLlm),
-    job: entrypointRef<{ params: ConnectJobParams, query: ConnectWaitQuery }, ConnectJob>(connect.project.job),
+  },
+  story: {
+    status: entrypointRef<{
+      params: { id: string, storyId: string }
+    }, ConnectStoryStatus>(connect.story.status),
   },
   convert: {
-    create: entrypointRef<{ body: ConnectConvertCreateBody }, ConnectJob>(connect.convert.create),
+    create: entrypointRef<{ body: ConnectConvertCreateBody }, ConversionStatusView>(connect.convert.create),
     check: entrypointRef<{ params: { id: string } }, ConvertCheck>(connect.convert.check),
-    start: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.start),
+    start: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.start),
     proceed: entrypointRef<{
       params: { id: string }, body: ConnectConvertProceedBody
-    }, ConnectJob>(connect.convert.proceed),
-    cancel: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.cancel),
+    }, ConversionStatusView>(connect.convert.proceed),
+    cancel: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.cancel),
     status: entrypointRef<{
       params: { id: string }
     }, ConversionStatusView>(connect.convert.status),
-    purge: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.purge),
+    purge: entrypointRef<{ params: { id: string } }, ConversionStatusView>(connect.convert.purge),
   },
   inquiry: {
     answer: entrypointRef<{
@@ -135,6 +141,6 @@ export const connectRef: ConnectReferences = {
     state: entrypointRef<{ params: ConnectPipelineParams }, ConnectPipelineState>(connect.pipeline.state),
     resume: entrypointRef<{
       params: ConnectPipelineParams, body: ConnectPipelineResumeBody
-    }, ConnectJob>(connect.pipeline.resume),
+    }, ConnectPipelineState>(connect.pipeline.resume),
   },
 }

package/src/connect/schemas.ts

@@ -7,9 +7,9 @@ import {
 import type { ConnectOpResult, InquiryAnswerPayload } from './ops.js'
 import type {
   ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
-  ConnectCreateBody, ConnectJobParams, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
+  ConnectCreateBody, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
   ConnectPipelineResumeBody, ConnectProjectLlmBody, ConnectSession, ConnectSessionOpen,
-  ConnectSessionParams, ConnectWaitQuery
+  ConnectPullQuery, ConnectSessionParams
 } from './types.js'
 
 /**
@@ -140,12 +140,12 @@ export const ConnectOpResultSchema = {
   additionalProperties: false,
 } as unknown as JSONSchemaType<ConnectOpResult>
 
-export const ConnectWaitQuerySchema = {
+export const ConnectPullQuerySchema = {
   type: 'object',
   properties: { wait: { type: 'integer', minimum: 0, maximum: 45, nullable: true } },
   required: [],
   additionalProperties: false,
-} as JSONSchemaType<ConnectWaitQuery>
+} as JSONSchemaType<ConnectPullQuery>
 
 /** Every project-scoped connector route addresses the project by `:id`. */
 export const ConnectProjectIdSchema = {
@@ -162,12 +162,12 @@ export const ConnectOpParamsSchema = {
   additionalProperties: false,
 } as JSONSchemaType<{ sessionId: string, opId: string }>
 
-export const ConnectJobParamsSchema = {
+export const ConnectStoryParamsSchema = {
   type: 'object',
-  properties: { id: idValue, jobId: { type: 'string', minLength: 1, maxLength: 256 } },
-  required: ['id', 'jobId'],
+  properties: { id: idValue, storyId: idValue },
+  required: ['id', 'storyId'],
   additionalProperties: false,
-} as JSONSchemaType<ConnectJobParams>
+} as JSONSchemaType<{ id: string, storyId: string }>
 
 export const ConnectCreateBodySchema = {
   type: 'object',

package/src/connect/types.ts

@@ -4,8 +4,8 @@ import type {
   OriginState, StoryEstimateBand
 } from '../convert/index.js'
 import type {
-  ConnectExecutor, ConnectHarness, ConnectJobBlock, ConnectJobKind, ConnectJobStatus, ConnectLlm,
-  ConnectSessionStatus, ConnectTarget, ConnectTransport, ModelTier
+  ConnectExecutor, ConnectHarness, ConnectLlm, ConnectSessionStatus, ConnectTarget,
+  ConnectTransport, ConnectWaitReason, ModelTier
 } from './consts.js'
 import type { InquiryAnswerPayload, InquiryPayload } from './ops.js'
 
@@ -82,68 +82,22 @@ export interface ConnectSessionView {
   expiresAt: string
 }
 
-/**
- * A derived view of "what the platform is doing for this project right now".
- *
- * Never stored. It is composed per request from the project lock, the slot record, the story
- * card, the latest pipeline run row and the operations queued for the project — the same facts
- * the manager UI reads, arranged for a caller that has one question ("may I stop waiting?") and
- * one follow-up ("what do I call next?").
- *
- * Its `id` is composed and parsed only through `jobIdOf` / `parseJobId`.
- */
-export interface ConnectJob {
-  id: string
-  kind: ConnectJobKind
-  status: ConnectJobStatus
-  /** The project CARD id. */
-  projectId: string
-  /**
-   * The story CARD id — never the story's code.
-   *
-   * The name is kept because a parent agent reads it: a wire field name is that agent's
-   * vocabulary and is never renamed, only re-documented.
-   */
-  storyId?: string
-  runId?: string
-  /** The pipeline step in flight, when a run row says. */
-  phase?: string
-  progress?: ConnectJobProgress
-  blockedOn?: ConnectJobBlock
-  /**
-   * The question a parked run is waiting on — present exactly when it is blocked on one.
-   *
-   * Carried on the job rather than left to a second lookup because a parent reads a job and
-   * nothing else while it polls: a run that stopped for a person, described only as "blocked",
-   * is a run whose parent waits out the timeout for a question it was never shown. It is also
-   * the ONLY way back to a question whose operation timed out while nobody was attached — the
-   * connector's own queue holds nothing at that point.
-   */
-  inquiry?: InquiryPayload
-  /** One sentence a parent agent can show a human. */
-  message?: string
-  /** Present on `Failed`, and on `Done` where the run recorded a warning. */
-  error?: string
-  /** Kind-specific payload once `Done`. */
-  result?: Record<string, unknown>
-  startedAt?: string
-  updatedAt: string
+export interface ConnectPullQuery {
+  /** Seconds to wait before answering; clamped to the pull ceiling. */
+  wait?: number
 }
 
-export interface ConnectJobProgress {
+export interface ConnectRunStatus {
+  runId: string
+  pipeline: string
+  status: string
   step?: string
   completed: string[]
   pending: string[]
-}
-
-export interface ConnectJobParams {
-  id: string
-  jobId: string
-}
-
-export interface ConnectWaitQuery {
-  /** Seconds to wait before answering; clamped to the pull ceiling. */
-  wait?: number
+  warnings?: string[]
+  error?: string
+  startedAt?: string
+  updatedAt?: string
 }
 
 /** What a connector needs to know about a project in one call. */
@@ -181,18 +135,30 @@ export interface ConnectProjectStatus {
   }
   production?: { id: string, status: string, host?: string }
   agent: { locked: boolean, task?: string, lockedAt?: string }
-  run?: {
-    runId: string
-    pipeline: string
-    status: string
-    step?: string
-    completed: string[]
-    pending: string[]
-    error?: string
-  }
+  run?: ConnectRunStatus
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
   session?: ConnectSessionView
   /** Set for a local target: the connector should not offer cloud-only operations. */
   local: boolean
+  updatedAt: string
+}
+
+/** A story card composed with its deterministic development run. */
+export interface ConnectStoryStatus {
+  projectId: string
+  story: {
+    id: string
+    code: string
+    title: string
+    status: string
+    intrinsic: string
+    warning?: string
+  }
+  run?: ConnectRunStatus
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
+  updatedAt: string
 }
 
 /** The record a local project keeps so a later session knows what it is. */
@@ -217,7 +183,7 @@ export interface ConnectProfileSettingsView extends ConnectProfileSettings {
    * The profile's preference for who performs a CONVERSION's model calls.
    *
    * Its own setting rather than a reading of `llmMode`, because the two answer for different
-   * work: a conversion reads somebody else's whole repository, which is the one job where handing
+   * work: a conversion reads somebody else's whole repository, which is the one case where handing
    * the inference to the parent agent is the cheap default rather than the experimental option.
    *
    * OPTIONAL for the same reason {@link ConnectCapabilitiesView.defaults} carries `converterLlm`
@@ -397,6 +363,7 @@ export interface ConversionStatusView {
   runId?: string
   /** Set exactly when `status` is `Waiting`: the question the run stopped on. */
   pendingInquiry?: InquiryPayload
+  waitingFor?: ConnectWaitReason
   lastError?: string
   updatedAt: string
 }
@@ -428,6 +395,8 @@ export interface ConnectPipelineState {
   failedAt?: string
   error?: string
   note?: string
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
   attempts: number
   startedAt: string
   heartbeatAt: string

package/src/convert/schemas.ts

@@ -492,9 +492,10 @@ export const ConversionEstimateSchema = {
     inputTokens: { type: 'number' },
     outputTokens: { type: 'number' },
     usd: { type: 'number' },
-    credits: { type: 'number' },
-    // A delegated conversion runs its model calls on the parent agent, so `usd`/`credits` are 0
-    // and this is what says the zero is a mode rather than a missing price.
+    // Deprecated: kept nullable so a record stored before the change still validates.
+    credits: { type: 'number', nullable: true },
+    // A delegated conversion runs its model calls on the parent agent, so `usd` is 0 and this is
+    // what says the zero is a mode rather than a missing price.
     delegated: { type: 'boolean' },
     basis: {
       type: 'object',
@@ -511,7 +512,7 @@ export const ConversionEstimateSchema = {
     computedAt: isoDate,
   },
   required: [
-    'stage', 'version', 'roles', 'inputTokens', 'outputTokens', 'usd', 'credits', 'delegated',
+    'stage', 'version', 'roles', 'inputTokens', 'outputTokens', 'usd', 'delegated',
     'basis', 'computedAt'
   ],
   additionalProperties: false,
@@ -522,8 +523,9 @@ export const StoryEstimateBandSchema = {
   properties: {
     minUsd: { type: 'number' },
     maxUsd: { type: 'number' },
-    minCredits: { type: 'number' },
-    maxCredits: { type: 'number' },
+    // Deprecated: kept nullable so a record stored before the change still validates.
+    minCredits: { type: 'number', nullable: true },
+    maxCredits: { type: 'number', nullable: true },
     perStory: {
       type: 'array',
       items: {
@@ -539,7 +541,7 @@ export const StoryEstimateBandSchema = {
       },
     },
   },
-  required: ['minUsd', 'maxUsd', 'minCredits', 'maxCredits', 'perStory'],
+  required: ['minUsd', 'maxUsd', 'perStory'],
   additionalProperties: false,
 } as unknown as JSONSchemaType<StoryEstimateBand>
 

package/src/convert/types.ts

@@ -409,9 +409,9 @@ export interface RoleEstimate {
  * What one stage is expected to cost, as the platform stores it on the conversion record.
  *
  * Priced on the agent, where the model presets and the run mode are: a DELEGATED conversion runs
- * its model calls on the parent agent and costs the platform nothing, so `usd` and `credits` are
- * zero and `delegated` says why. `basis` is kept so a user can see what the number was projected
- * from rather than being handed a figure with no provenance.
+ * its model calls on the parent agent and costs the platform nothing, so `usd` is zero and
+ * `delegated` says why. `basis` is kept so a user can see what the number was projected from
+ * rather than being handed a figure with no provenance.
  */
 export interface ConversionEstimate {
   stage: ConversionStage
@@ -420,7 +420,8 @@ export interface ConversionEstimate {
   inputTokens: number
   outputTokens: number
   usd: number
-  credits: number
+  /** @deprecated Credits are USD at the reference rate now — read `usd`. Kept for records stored before the change. */
+  credits?: number
   delegated: boolean
   basis: {
     files: number
@@ -441,8 +442,10 @@ export interface ConversionEstimate {
 export interface StoryEstimateBand {
   minUsd: number
   maxUsd: number
-  minCredits: number
-  maxCredits: number
+  /** @deprecated Credits are USD at the reference rate now — read `minUsd`. Kept for records stored before the change. */
+  minCredits?: number
+  /** @deprecated Credits are USD at the reference rate now — read `maxUsd`. Kept for records stored before the change. */
+  maxCredits?: number
   perStory: { code: string, complexity: number, minUsd: number, maxUsd: number }[]
 }
 

package/src/design/runtime.ts

@@ -40,7 +40,7 @@ export const isEphemeralActor = (actor?: StoryActor): boolean =>
 export interface StoryDesignJob {
   /** The queue it is enqueued onto. */
   queue: string
-  /** The job name, which IS its entrypoint alias — `app.job.<name>`. */
+  /** The job name, which becomes the backend-only `job:<name>` protocol alias. */
   name: string
   /** The processor module, relative to the worker package's `src`. */
   path: string

package/src/planning/consts.ts

@@ -35,7 +35,7 @@ export const VIABLE_SPEC_FLOW = 'viable:spec'
  * The story flow's status keys.
  *
  * Byte-identical to the strings a story has always carried — the frontmatter of
- * `docs/stories/<code>.md`, the connector's job status mapping, the board's columns, their i18n
+ * `docs/stories/<code>.md`, connector status rendering, the board's columns, their i18n
  * keys and every end-to-end selector read these exact values. A key is a wire contract and is
  * never renamed.
  */