@owlmeans/viable-common 0.0.11 → 0.0.13

package/src/connect/references.ts

@@ -3,13 +3,15 @@ import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
 import type { EntrypointReference } from '@owlmeans/context'
 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,
-  ConnectJobParams, ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams,
-  ConnectPipelineResumeBody, ConnectPipelineState, ConnectProjectLlmBody, ConnectProjectSettings,
-  ConnectProjectStatus, ConnectProjectSummary, ConnectSessionOpen, ConnectSessionParams,
-  ConnectSessionView, ConnectStoryBody, ConnectStoryDeletion, ConnectStoryItem, ConnectStoryList,
-  ConnectStoryMutation, ConnectStoryQuery, ConnectWaitQuery,
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectInquiryAnswerBody, ConnectJobParams,
+  ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody,
+  ConnectPipelineState, ConnectProjectLlmBody, ConnectProjectSettings, ConnectProjectStatus,
+  ConnectProjectSummary, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView,
+  ConnectStoryBody, ConnectStoryDeletion, ConnectStoryItem, ConnectStoryList, ConnectStoryMutation,
+  ConnectStoryQuery, ConnectWaitQuery, ConversionStatusView, ConvertCheck,
 } from './types.js'
 
 type ConnectReference<Request extends RequestShape, Response> =
@@ -40,6 +42,9 @@ export interface ConnectReferences {
     modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectJob>
     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: {
@@ -52,6 +57,25 @@ export interface ConnectReferences {
     delete: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryDeletion>
     develop: ConnectReference<{ params: { id: string, storyId: string } }, ConnectJob>
   }
+  files: {
+    list: ConnectReference<{ params: { id: string } }, string[]>
+  }
+  convert: {
+    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConnectJob>
+    check: ConnectReference<{ params: { id: string } }, ConvertCheck>
+    start: ConnectReference<{ params: { id: string } }, ConnectJob>
+    proceed: ConnectReference<{
+      params: { id: string }, body: ConnectConvertProceedBody
+    }, ConnectJob>
+    cancel: ConnectReference<{ params: { id: string } }, ConnectJob>
+    status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+    purge: ConnectReference<{ params: { id: string } }, ConnectJob>
+  }
+  inquiry: {
+    answer: ConnectReference<{
+      params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
+    }, unknown>
+  }
   pipeline: {
     state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
     resume: ConnectReference<{
@@ -92,8 +116,29 @@ export const connectRef: ConnectReferences = {
     llm: entrypointRef<{
       params: { id: string }, body: ConnectProjectLlmBody
     }, ConnectProjectSettings>(connect.project.llm),
+    converterLlm: entrypointRef<{
+      params: { id: string }, body: ConverterProjectLlmBody
+    }, ConnectProjectSettings>(connect.project.converterLlm),
     job: entrypointRef<{ params: ConnectJobParams, query: ConnectWaitQuery }, ConnectJob>(connect.project.job),
   },
+  convert: {
+    create: entrypointRef<{ body: ConnectConvertCreateBody }, ConnectJob>(connect.convert.create),
+    check: entrypointRef<{ params: { id: string } }, ConvertCheck>(connect.convert.check),
+    start: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.start),
+    proceed: entrypointRef<{
+      params: { id: string }, body: ConnectConvertProceedBody
+    }, ConnectJob>(connect.convert.proceed),
+    cancel: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.cancel),
+    status: entrypointRef<{
+      params: { id: string }
+    }, ConversionStatusView>(connect.convert.status),
+    purge: entrypointRef<{ params: { id: string } }, ConnectJob>(connect.convert.purge),
+  },
+  inquiry: {
+    answer: entrypointRef<{
+      params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
+    }, unknown>(connect.inquiry.answer),
+  },
   story: {
     list: entrypointRef<{ params: { id: string }, query: ConnectStoryQuery }, ConnectStoryList>(connect.story.list),
     get: entrypointRef<{ params: { id: string, storyId: string } }, ConnectStoryItem>(connect.story.get),
@@ -104,6 +149,9 @@ export const connectRef: ConnectReferences = {
     delete: entrypointRef<{ params: { id: string, storyId: string } }, ConnectStoryDeletion>(connect.story.delete),
     develop: entrypointRef<{ params: { id: string, storyId: string } }, ConnectJob>(connect.story.develop),
   },
+  files: {
+    list: entrypointRef<{ params: { id: string } }, string[]>(connect.files.list),
+  },
   pipeline: {
     state: entrypointRef<{ params: ConnectPipelineParams }, ConnectPipelineState>(connect.pipeline.state),
     resume: entrypointRef<{

package/src/connect/schemas.ts

@@ -1,16 +1,30 @@
 import type { JSONSchemaType } from 'ajv'
+import { ConversionDecision, OriginKind } from '../convert/consts.js'
 import {
-  ConnectExecutor, ConnectHarness, ConnectLlm, ConnectOpErrorKind, ConnectSessionStatus,
+  CONNECT_INQUIRY_MAX_TEXT, ConnectHarness, ConnectLlm, ConnectOpErrorKind, ConnectSessionStatus,
   ConnectTarget, ConnectTransport, ModelTaskResultKind, ModelTier
 } from './consts.js'
-import type { ConnectOpResult } from './ops.js'
+import type { ConnectOpResult, InquiryAnswerPayload } from './ops.js'
 import type {
-  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectJobParams, ConnectLlmBody,
-  ConnectModifyBody, ConnectPipelineParams, ConnectPipelineResumeBody, ConnectProjectLlmBody,
-  ConnectSession, ConnectSessionOpen, ConnectSessionParams, ConnectStoryBody, ConnectStoryQuery,
-  ConnectWaitQuery
+  ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
+  ConnectCreateBody, ConnectJobParams, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
+  ConnectPipelineResumeBody, ConnectProjectLlmBody, ConnectSession, ConnectSessionOpen,
+  ConnectSessionParams, ConnectStoryBody, ConnectStoryQuery, ConnectWaitQuery
 } from './types.js'
 
+/**
+ * A nullable ENUM carries `null` as one of its values.
+ *
+ * `nullable` and `enum` are separate Ajv keywords, checked independently: `nullable: true` widens
+ * the TYPE check to admit `null` and the `enum` check then refuses the very same value, so the
+ * field can only ever be OMITTED — never sent empty. That is not the same thing here. A connector
+ * is somebody else's process putting JSON on the wire and it serialises an unset optional as
+ * `null` as readily as it drops the key, and in `ConnectProjectLlmBody.llmMode` the `null` MEANS
+ * something ("inherit the profile's setting") and has no other spelling. So every `enum` beside a
+ * `nullable: true` is written `[...Object.values(X), null]`. `tests/convert.spec.ts` walks every
+ * schema this package exports and fails on the pair written apart.
+ */
+
 const idValue = { type: 'string', minLength: 1, maxLength: 128 } as const
 const textValue = { type: 'string', minLength: 1, maxLength: 65536 } as const
 
@@ -26,7 +40,11 @@ export const ConnectCapabilitiesSchema = {
     },
     subagents: { type: 'boolean' },
     effortControl: { type: 'boolean' },
-    executors: { type: 'array', items: { type: 'string', enum: Object.values(ConnectExecutor) } },
+    // Deliberately NOT `enum: Object.values(ConnectExecutor)`. The SDK and the platform ship
+    // separately, so a connector built against a newer package advertises an executor kind this
+    // platform has never heard of — and an enum turns that into a refused session rather than an
+    // unused capability. Forward tolerance: an unknown value is simply not matched by anything.
+    executors: { type: 'array', items: { type: 'string', maxLength: 32 } },
     services: {
       type: 'object',
       nullable: true,
@@ -81,7 +99,7 @@ export const ConnectSessionSchema = {
     clientVersion: { type: 'string', maxLength: 64 },
     capabilities: ConnectCapabilitiesSchema,
     status: { type: 'string', enum: Object.values(ConnectSessionStatus) },
-    transport: { type: 'string', enum: Object.values(ConnectTransport), nullable: true },
+    transport: { type: 'string', enum: [...Object.values(ConnectTransport), null], nullable: true },
     openedAt: { type: 'object', format: 'date-time', required: [] },
     lastSeenAt: { type: 'object', format: 'date-time', required: [] },
     closedAt: { type: 'object', format: 'date-time', required: [], nullable: true },
@@ -113,7 +131,7 @@ export const ConnectOpResultSchema = {
       properties: {
         type: { type: 'string', maxLength: 256 },
         message: { type: 'string', maxLength: 8192 },
-        kind: { type: 'string', enum: Object.values(ConnectOpErrorKind), nullable: true },
+        kind: { type: 'string', enum: [...Object.values(ConnectOpErrorKind), null], nullable: true },
       },
       required: ['type', 'message'],
       additionalProperties: false,
@@ -176,7 +194,7 @@ export const ConnectCreateBodySchema = {
   type: 'object',
   properties: {
     prompt: { type: 'string', minLength: 1, maxLength: 16384 },
-    target: { type: 'string', enum: Object.values(ConnectTarget), nullable: true },
+    target: { type: 'string', enum: [...Object.values(ConnectTarget), null], nullable: true },
   },
   required: ['prompt'],
   additionalProperties: false,
@@ -189,7 +207,7 @@ export const ConnectConfirmBodySchema = {
     description: { type: 'string', maxLength: 16384, nullable: true },
     specification: { type: 'string', maxLength: 262144, nullable: true },
     vision: { type: 'string', maxLength: 16384, nullable: true },
-    target: { type: 'string', enum: Object.values(ConnectTarget), nullable: true },
+    target: { type: 'string', enum: [...Object.values(ConnectTarget), null], nullable: true },
   },
   required: [],
   additionalProperties: false,
@@ -232,10 +250,81 @@ export const ConnectPipelineResumeBodySchema = {
   properties: {
     from: { type: 'string', maxLength: 128, nullable: true },
     force: { type: 'boolean', nullable: true },
+    // Keyed by inquiry id, so the key space is open by construction and cannot be enumerated.
+    // The values are validated where they are read, against InquiryAnswerSchema.
+    answers: { type: 'object', additionalProperties: true, required: [], nullable: true },
   },
   required: [],
   additionalProperties: false,
-} as JSONSchemaType<ConnectPipelineResumeBody>
+} as unknown as JSONSchemaType<ConnectPipelineResumeBody>
+
+/**
+ * One answer to one question.
+ *
+ * `value` is a union — one choice or several — expressed as `oneOf`, never as a `nullable` with no
+ * `type`: Ajv refuses that, and this schema is compiled at route registration, so the refusal
+ * takes the whole API down at boot rather than failing the one call that carried the value.
+ */
+export const InquiryAnswerSchema = {
+  type: 'object',
+  properties: {
+    inquiryId: idValue,
+    value: {
+      oneOf: [
+        { type: 'string', maxLength: CONNECT_INQUIRY_MAX_TEXT },
+        {
+          type: 'array',
+          items: { type: 'string', maxLength: CONNECT_INQUIRY_MAX_TEXT },
+          maxItems: 32,
+        },
+      ],
+    },
+    text: { type: 'string', maxLength: CONNECT_INQUIRY_MAX_TEXT, nullable: true },
+    declined: { type: 'boolean', nullable: true },
+  },
+  required: ['inquiryId'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<InquiryAnswerPayload>
+
+/** The two ids an answer is addressed by: the project it belongs to and the question it answers. */
+export const ConnectInquiryParamsSchema = {
+  type: 'object',
+  properties: { id: idValue, inquiryId: idValue },
+  required: ['id', 'inquiryId'],
+  additionalProperties: false,
+} as JSONSchemaType<{ id: string, inquiryId: string }>
+
+export const ConnectConvertCreateBodySchema = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', minLength: 1, maxLength: 128, nullable: true },
+    about: { type: 'string', maxLength: 16384, nullable: true },
+    target: { type: 'string', enum: [...Object.values(ConnectTarget), null], nullable: true },
+    origin: {
+      type: 'object',
+      nullable: true,
+      properties: {
+        kind: { type: 'string', enum: Object.values(OriginKind) },
+        repoUrl: { type: 'string', maxLength: 2048, nullable: true },
+        branch: { type: 'string', maxLength: 256, nullable: true },
+      },
+      required: ['kind'],
+      additionalProperties: false,
+    },
+  },
+  required: [],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConnectConvertCreateBody>
+
+export const ConnectConvertProceedBodySchema = {
+  type: 'object',
+  properties: {
+    decision: { type: 'string', enum: Object.values(ConversionDecision) },
+    note: { type: 'string', maxLength: 4096, nullable: true },
+  },
+  required: ['decision'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConnectConvertProceedBody>
 
 export const ConnectLlmBodySchema = {
   type: 'object',
@@ -246,7 +335,7 @@ export const ConnectLlmBodySchema = {
 
 export const ConnectProjectLlmBodySchema = {
   type: 'object',
-  properties: { llmMode: { type: 'string', enum: Object.values(ConnectLlm), nullable: true } },
+  properties: { llmMode: { type: 'string', enum: [...Object.values(ConnectLlm), null], nullable: true } },
   required: ['llmMode'],
   additionalProperties: false,
 } as unknown as JSONSchemaType<ConnectProjectLlmBody>

package/src/connect/types.ts

@@ -1,7 +1,13 @@
+import type {
+  ArchitectureCase, ConversionDecision, ConversionEstimate, ConversionStackRef, ConversionStage,
+  ConversionStatus, ConvertibilityReason, ConvertibilityVerdict, OriginKind, OriginShape,
+  OriginState, StoryEstimateBand
+} from '../convert/index.js'
 import type {
   ConnectExecutor, ConnectHarness, ConnectJobBlock, ConnectJobKind, ConnectJobStatus, ConnectLlm,
   ConnectSessionStatus, ConnectTarget, ConnectTransport, ModelTier
 } from './consts.js'
+import type { InquiryAnswerPayload, InquiryPayload } from './ops.js'
 
 /**
  * What a parent agent can do, as it reports itself.
@@ -95,6 +101,16 @@ export interface ConnectJob {
   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. */
@@ -204,6 +220,22 @@ export interface ConnectProfileSettings {
 export interface ConnectProfileSettingsView extends ConnectProfileSettings {
   /** Whether the organization's plan allows the local-LLM mode at all. */
   canUseLocal: boolean
+  /**
+   * 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
+   * 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`
+   * optionally: the two converter fields are answered by a platform build that does not exist yet,
+   * and this package is consumed by the platform through a workspace link rather than a published
+   * range — a required field here is a compile error in every handler that already returns this
+   * view. Tightened to required once the platform's conversion handlers fill them.
+   */
+  converterLlmMode?: ConnectLlm
+  /** Whether this caller may run a conversion's model calls on the parent agent. */
+  canUseConverterLocal?: boolean
 }
 
 export interface ConnectLlmBody {
@@ -216,6 +248,16 @@ export interface ConnectProjectSettings {
   llmMode: ConnectLlm | null
   effective: ConnectLlm
   canUseLocal: boolean
+  /**
+   * The project's converter override; `null` inherits the profile's.
+   *
+   * Optional on the same forward-compatibility grounds as
+   * {@link ConnectProfileSettingsView.converterLlmMode} — absent from an answer written before the
+   * platform's conversion handlers land, and never to be read as a value.
+   */
+  converterLlmMode?: ConnectLlm | null
+  /** What the override, the profile and the platform's own floor actually resolve to. */
+  converterEffective?: ConnectLlm
 }
 
 export interface ConnectProjectLlmBody {
@@ -228,8 +270,13 @@ export interface ConnectCapabilitiesView {
   tiers: Record<ModelTier, string[]>
   /** Whether this caller may open a local-LLM session. */
   localLlm: boolean
-  /** The default mode for a new session, resolved from the caller's settings. */
-  defaults: { target: ConnectTarget, llm: ConnectLlm }
+  /**
+   * The default mode for a new session, resolved from the caller's settings.
+   *
+   * `converterLlm` is OPTIONAL: an older platform does not send it, and a client that treated its
+   * absence as a value would pin every conversion to whatever its own default happened to be.
+   */
+  defaults: { target: ConnectTarget, llm: ConnectLlm, converterLlm?: ConnectLlm }
   limits: {
     pullWaitMs: number
     modelTaskTimeoutMs: number
@@ -275,6 +322,87 @@ export interface ConnectPipelineParams {
 export interface ConnectPipelineResumeBody {
   from?: string
   force?: boolean
+  /**
+   * Answers to the questions a parked run is waiting on, keyed by inquiry id.
+   *
+   * A run stops at `Waiting` because a step asked something; resuming it without what it asked for
+   * makes it ask again. The runner MERGES these into whatever the run already carries rather than
+   * replacing them, so a resume that answers one of two outstanding questions keeps the other.
+   */
+  answers?: Record<string, InquiryAnswerPayload>
+}
+
+/** Start a conversion of an existing project's code. */
+export interface ConnectConvertCreateBody {
+  name?: string
+  about?: string
+  /** Where the converted target's tree will live. */
+  target?: ConnectTarget
+  /**
+   * Where the code comes from.
+   *
+   * Absent for a LOCAL target the connector is already attached to: the tree is the directory the
+   * session opened on, and there is nothing to fetch.
+   */
+  origin?: { kind: OriginKind, repoUrl?: string, branch?: string }
+}
+
+/** Decide what happens at a stage boundary. */
+export interface ConnectConvertProceedBody {
+  decision: ConversionDecision
+  /** Free text the user added to the decision; recorded, never parsed. */
+  note?: string
+}
+
+/** Answer one question a parked run is waiting on. */
+export type ConnectInquiryAnswerBody = InquiryAnswerPayload
+
+/**
+ * Whether this origin can be converted, and what it will cost.
+ *
+ * Answered BEFORE anything is provisioned or charged, from the census alone — which is why it
+ * carries the counts it was decided from rather than a bare verdict.
+ */
+export interface ConvertCheck {
+  projectId: string
+  verdict: ConvertibilityVerdict
+  reasons: ConvertibilityReason[]
+  stack?: ConversionStackRef
+  architecture?: ArchitectureCase
+  shape: OriginShape
+  monorepo: boolean
+  /** Workspace members and directories nothing declares. Named, because each one is a decision. */
+  unlinked: string[]
+  files: number
+  bytes: number
+  /** Bulk data files found — sampled and described, never carried. */
+  bulk: number
+  estimate?: ConversionEstimate
+}
+
+/** Everything a caller needs to draw the conversion's current state in one call. */
+export interface ConversionStatusView {
+  projectId: string
+  stage: ConversionStage
+  status: ConversionStatus
+  /** The last decision the user made. */
+  decision?: ConversionDecision
+  verdict?: ConvertibilityVerdict
+  stack?: ConversionStackRef
+  /** What the conversion is rebuilding the project ONTO. Always the Viable stack today. */
+  targetStack?: ConversionStackRef
+  architecture?: ArchitectureCase
+  /** One per stage that has been estimated, newest last. */
+  estimates: ConversionEstimate[]
+  storyEstimate?: StoryEstimateBand
+  originState: OriginState
+  /** How many questions the conversion answered for itself. Each one is readable in the docs. */
+  assumptions: number
+  runId?: string
+  /** Set exactly when `status` is `Waiting`: the question the run stopped on. */
+  pendingInquiry?: InquiryPayload
+  lastError?: string
+  updatedAt: string
 }
 
 /** The acknowledgement returned when a connector submits an operation result. */