@owlmeans/viable-common 0.0.44 → 0.0.46

package/src/connect/{ops.ts → ops/types.ts}

@@ -1,9 +1,9 @@
-import type { SlotCommandPayload } from '../slot/index.js'
+import type { SlotCommandPayload } from '../../slot/types.js'
 import type {
   ConnectInquiryKind, ConnectOpErrorKind, ConnectOpKind, ModelTaskMode, ModelTaskResultKind,
   ModelTaskRole, ModelTier
-} from './consts.js'
-import type { ConnectServices } from './types.js'
+} from '../consts.js'
+import type { ConnectServices } from '../session/types.js'
 
 /**
  * One thing the platform asks a connector to do.
@@ -48,6 +48,13 @@ export interface ConnectOpError {
   kind?: ConnectOpErrorKind
 }
 
+/** The acknowledgement returned when a connector submits an operation result. */
+export interface ConnectOpSubmission {
+  ok: boolean
+  /** The operation was already resolved; retrying a lost HTTP response is safe. */
+  ignored?: boolean
+}
+
 /**
  * The configuration a local target needs, as file CONTENT rather than as keys.
  *
@@ -203,3 +210,6 @@ export interface InquiryAnswerPayload {
   text?: string
   declined?: boolean
 }
+
+/** Answer one question a parked run is waiting on. */
+export interface ConnectInquiryAnswerBody extends InquiryAnswerPayload {}

package/src/connect/pipeline/types.ts

@@ -0,0 +1,41 @@
+import type { ConnectWaitReason } from '../consts.js'
+import type { InquiryAnswerPayload, InquiryPayload } from '../ops/types.js'
+
+export interface ConnectPipelineParams {
+  id: string
+  runId: string
+}
+
+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>
+}
+
+/** The persistent state of one pipeline run, read by a connector without platform internals. */
+export interface ConnectPipelineState {
+  runId: string
+  pipeline: string
+  version: number
+  status: string
+  step?: string
+  completed: string[]
+  pending: string[]
+  warnings: string[]
+  failedAt?: string
+  error?: string
+  note?: string
+  waitingFor?: ConnectWaitReason
+  pendingInquiry?: InquiryPayload
+  attempts: number
+  startedAt: string
+  heartbeatAt: string
+  updatedAt: string
+}

package/src/connect/project/types.ts

@@ -0,0 +1,127 @@
+import type { ConnectTarget, ConnectWaitReason } from '../consts.js'
+import type { InquiryPayload } from '../ops/types.js'
+import type { ConnectSessionView } from '../session/types.js'
+
+export interface ConnectRunStatus {
+  runId: string
+  pipeline: string
+  status: string
+  step?: string
+  completed: string[]
+  pending: string[]
+  warnings?: string[]
+  error?: string
+  startedAt?: string
+  updatedAt?: string
+}
+
+/** What a connector needs to know about a project in one call. */
+export interface ConnectProjectStatus {
+  /**
+   * The project card, flattened into the names a parent agent already reads.
+   *
+   * `name` is the card's `title` and `alias` its `code`; the three brief parts are the bodies of
+   * the project's `specification`, `vision` and `design-system` specifications. `status` and
+   * `intrinsic` are the card's own — a key of the project flow and the intrinsic state it maps to —
+   * typed as plain strings because this view crosses a version skew and a newer platform may
+   * answer with a status an older connector has never heard of.
+   */
+  project: {
+    id: string
+    name: string
+    alias: string
+    description?: string
+    status: string
+    intrinsic: string
+    specification?: string
+    vision?: string
+    designSystem?: string
+  }
+  slot?: {
+    id: string
+    kind: string
+    status: string
+    slug: string
+    host?: string
+    initialized?: boolean
+    lastError?: string
+    buildWarning?: string
+    backendWarning?: string
+  }
+  production?: { id: string, status: string, host?: string }
+  agent: { locked: boolean, task?: string, lockedAt?: 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. */
+export interface ConnectMarker {
+  version: 1
+  apiUrl: string
+  projectId: string
+  slug: string
+  entitySlug?: string
+  createdAt: string
+}
+
+/** The deliberate small projection returned by the connector project list. */
+export interface ConnectProjectSummary {
+  id: string
+  name: string
+  alias: string
+}
+
+/** Attach an existing project to a session. */
+export interface ConnectAttachBody {
+  projectId?: string
+  slug?: string
+  projectDir?: string
+}
+
+/** Create a project through the connector; `target` decides where its tree will live. */
+export interface ConnectCreateBody {
+  prompt: string
+  target?: ConnectTarget
+}
+
+/**
+ * Confirm a drafted project, optionally editing what the analysis produced.
+ *
+ * The keys are a parent agent's vocabulary and stay as they are: `name` becomes the card's
+ * `title`, and each brief part present is written into the project's specification of that
+ * category before the confirm transition runs.
+ */
+export interface ConnectConfirmBody {
+  name?: string
+  description?: string
+  specification?: string
+  vision?: string
+  designSystem?: string
+  target?: ConnectTarget
+}
+
+export interface ConnectModifyBody {
+  prompt: string
+}

package/src/connect/references/types.local.ts

@@ -0,0 +1,5 @@
+import type { EntrypointReference } from '@owlmeans/context'
+import type { RegisteredEntrypoint, RequestShape } from '@owlmeans/entrypoint'
+
+export interface ConnectReference<Request extends RequestShape, Response>
+  extends EntrypointReference<RegisteredEntrypoint<Request, Response>> {}

package/src/connect/references/types.ts

@@ -0,0 +1,73 @@
+import type { ConnectProjectBranding, ConnectProjectBrandingSave } from '../branding/types.js'
+import type {
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConversionStatusView, ConvertCheck
+} from '../conversion/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe } from '../kit/types.js'
+import type { ConnectInquiryAnswerBody, ConnectOp, ConnectOpResult, ConnectOpSubmission } from '../ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState } from '../pipeline/types.js'
+import type {
+  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody, ConnectProjectStatus,
+  ConnectProjectSummary, ConnectStoryStatus
+} from '../project/types.js'
+import type { ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView } from '../session/types.js'
+import type { ConnectReference } from './types.local.js'
+
+export interface ConnectReferences {
+  session: {
+    open: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
+    openDelegated: ConnectReference<{ body: ConnectSessionOpen }, ConnectSessionView>
+    close: ConnectReference<{ params: ConnectSessionParams }, ConnectSessionView>
+  }
+  op: {
+    pull: ConnectReference<{ params: ConnectSessionParams, query: ConnectPullQuery }, ConnectOp[]>
+    submit: ConnectReference<{
+      params: { sessionId: string, opId: string }, body: ConnectOpResult
+    }, ConnectOpSubmission>
+  }
+  project: {
+    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 } }, ConnectProjectStatus>
+    modify: ConnectReference<{ params: { id: string }, body: ConnectModifyBody }, ConnectProjectStatus>
+    kit: {
+      describe: ConnectReference<{ params: { id: string } }, ConnectKitDescribe>
+      apply: ConnectReference<{ params: { id: string }, body: ConnectKitApplyBody }, ConnectKitApplyResult>
+    }
+    branding: {
+      get: ConnectReference<{ params: { id: string } }, ConnectProjectBranding>
+      save: ConnectReference<{
+        params: { id: string }, body: ConnectProjectBrandingSave
+      }, ConnectProjectBranding>
+    }
+  }
+  story: {
+    status: ConnectReference<{ params: { id: string, storyId: string } }, ConnectStoryStatus>
+  }
+  files: {
+    list: ConnectReference<{ params: { id: string } }, string[]>
+  }
+  convert: {
+    create: ConnectReference<{ body: ConnectConvertCreateBody }, ConversionStatusView>
+    check: ConnectReference<{ params: { id: string } }, ConvertCheck>
+    start: ConnectReference<{ params: { id: string }, body: ConnectConvertStartBody }, ConversionStatusView>
+    proceed: ConnectReference<{
+      params: { id: string }, body: ConnectConvertProceedBody
+    }, ConversionStatusView>
+    status: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+    purge: ConnectReference<{ params: { id: string } }, ConversionStatusView>
+  }
+  inquiry: {
+    answer: ConnectReference<{
+      params: { id: string, inquiryId: string }, body: ConnectInquiryAnswerBody
+    }, unknown>
+  }
+  pipeline: {
+    state: ConnectReference<{ params: ConnectPipelineParams }, ConnectPipelineState>
+    resume: ConnectReference<{
+      params: ConnectPipelineParams, body: ConnectPipelineResumeBody
+    }, ConnectPipelineState>
+  }
+}

package/src/connect/references.ts

@@ -1,7 +1,18 @@
 import { entrypointRef } from '@owlmeans/entrypoint'
 import { connect } from './consts.js'
-import type { ConnectOp, ConnectOpResult } from './ops.js'
-import type { ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConnectInquiryAnswerBody, ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe, ConnectModifyBody, ConnectOpSubmission, ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState, ConnectProjectBranding, ConnectProjectBrandingSave, ConnectProjectStatus, ConnectProjectSummary, ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView, ConnectStoryStatus, ConversionStatusView, ConvertCheck, ConnectReferences } from './types.js'
+import type { ConnectProjectBranding, ConnectProjectBrandingSave } from './branding/types.js'
+import type {
+  ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody, ConversionStatusView, ConvertCheck
+} from './conversion/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe } from './kit/types.js'
+import type { ConnectInquiryAnswerBody, ConnectOp, ConnectOpResult, ConnectOpSubmission } from './ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody, ConnectPipelineState } from './pipeline/types.js'
+import type {
+  ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody, ConnectProjectStatus,
+  ConnectProjectSummary, ConnectStoryStatus
+} from './project/types.js'
+import type { ConnectReferences } from './references/types.js'
+import type { ConnectPullQuery, ConnectSessionOpen, ConnectSessionParams, ConnectSessionView } from './session/types.js'
 
 /**
  * Typed references for adapter packages that address the connector dynamically.  Applications

package/src/connect/schemas.ts

@@ -4,17 +4,16 @@ import {
   CONNECT_BRANDING_COPYRIGHT_MAX, CONNECT_BRANDING_GOOGLE_TAG_MAX,
   CONNECT_BRANDING_ORGANIZATION_MAX, CONNECT_BRANDING_URL_MAX, CONNECT_INQUIRY_MAX_TEXT,
   ConnectHarness, ConnectLlm, ConnectOpErrorKind, ConnectSessionStatus, ConnectTarget,
-  ConnectTransport, ModelTaskResultKind, ModelTier
+  ConnectTransport, ModelTaskResultKind
 } from './consts.js'
-import type { ConnectOpResult, InquiryAnswerPayload } from './ops.js'
-import type {
-  ConnectAttachBody, ConnectConfirmBody, ConnectConvertCreateBody, ConnectConvertProceedBody,
-  ConnectConvertStartBody,
-  ConnectCreateBody, ConnectLlmBody, ConnectModifyBody, ConnectPipelineParams,
-  ConnectPipelineResumeBody, ConnectProjectBrandingSave, ConnectProjectLlmBody, ConnectSession,
-  ConnectSessionOpen, ConnectPullQuery, ConnectSessionParams, ConnectKitApplyBody, ConnectKitApplyResult,
-  ConnectKitDescribe, PlanningKitView
-} from './types.js'
+import type { ConnectProjectBrandingSave } from './branding/types.js'
+import type { ConnectConvertCreateBody, ConnectConvertProceedBody, ConnectConvertStartBody } from './conversion/types.js'
+import type { ConnectKitApplyBody, ConnectKitApplyResult, ConnectKitDescribe, PlanningKitView } from './kit/types.js'
+import type { ConnectOpResult, InquiryAnswerPayload } from './ops/types.js'
+import type { ConnectPipelineParams, ConnectPipelineResumeBody } from './pipeline/types.js'
+import type { ConnectAttachBody, ConnectConfirmBody, ConnectCreateBody, ConnectModifyBody } from './project/types.js'
+import type { ConnectPullQuery, ConnectSession, ConnectSessionOpen, ConnectSessionParams } from './session/types.js'
+import type { ConnectLlmBody, ConnectProjectLlmBody } from './settings/types.js'
 
 /**
  * A nullable ENUM carries `null` as one of its values.
@@ -478,6 +477,3 @@ export const ModelTaskResultSchema = {
   required: ['taskId', 'kind'],
   additionalProperties: false,
 } as any
-
-/** Tier → the model the parent will run it on. Free-form; display only. */
-export const ModelTierValues = Object.values(ModelTier)

package/src/connect/session/types.ts

@@ -0,0 +1,81 @@
+import type {
+  ConnectExecutor, ConnectHarness, ConnectLlm, ConnectSessionStatus, ConnectTarget, ConnectTransport, ModelTier
+} from '../consts.js'
+
+/**
+ * What a parent agent can do, as it reports itself.
+ *
+ * `tiers` is what decides whether the local-LLM mode is usable at all: a parent that names no
+ * model for a tier still gets tasks, clamped to the nearest tier it does offer.
+ */
+export interface ConnectCapabilities {
+  harness: ConnectHarness
+  /** Tier → the parent's own name for the model it will run that tier on. Display only. */
+  tiers: Partial<Record<ModelTier, string>>
+  /** Whether the parent can run a task in an isolated subagent rather than its own conversation. */
+  subagents: boolean
+  /** Whether the parent can ask for low reasoning effort explicitly. */
+  effortControl: boolean
+  /** Which operation kinds this connector will execute. */
+  executors: ConnectExecutor[]
+  /** What the local machine has, learned from the configure op. Absent until one has run. */
+  services?: ConnectServices
+}
+
+/** What a local machine actually provides. Reported by the connector, never assumed. */
+export interface ConnectServices {
+  db: boolean
+  valkey: boolean
+}
+
+export interface ConnectSession {
+  id?: string
+  profileId: string
+  entityId: string
+  projectId?: string
+  /** The absolute directory the target lives in, for a local target. Identity for supersede. */
+  projectDir?: string
+  target: ConnectTarget
+  llm: ConnectLlm
+  harness: ConnectHarness
+  clientVersion: string
+  capabilities: ConnectCapabilities
+  status: ConnectSessionStatus
+  /** How the connector is receiving operations right now. */
+  transport?: ConnectTransport
+  openedAt: Date
+  lastSeenAt: Date
+  closedAt?: Date
+  createdAt: Date
+  updatedAt?: Date
+}
+
+/** What a connector asks for when it attaches. */
+export interface ConnectSessionOpen {
+  projectId?: string
+  projectDir?: string
+  target: ConnectTarget
+  harness: ConnectHarness
+  clientVersion: string
+  capabilities: ConnectCapabilities
+}
+
+export interface ConnectSessionParams {
+  sessionId: string
+}
+
+export interface ConnectSessionView {
+  id: string
+  target: ConnectTarget
+  llm: ConnectLlm
+  projectId?: string
+  status: ConnectSessionStatus
+  /** Operations waiting for this session right now. */
+  pending: number
+  expiresAt: string
+}
+
+export interface ConnectPullQuery {
+  /** Seconds to wait before answering; clamped to the pull ceiling. */
+  wait?: number
+}

package/src/connect/settings/types.ts

@@ -0,0 +1,52 @@
+import type { ConnectLlm } from '../consts.js'
+
+/** The per-profile connector preference. */
+export interface ConnectProfileSettings {
+  llmMode: ConnectLlm
+}
+
+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 case where handing
+   * the inference to the parent agent is the cheap default rather than the experimental option.
+   *
+   * OPTIONAL: 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 {
+  llmMode: ConnectLlm
+}
+
+/** The per-project override, and what it resolves to. */
+export interface ConnectProjectSettings {
+  /** `null` means "inherit the profile setting". */
+  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 {
+  llmMode: ConnectLlm | null
+}

package/src/convert/analysis/types.ts

@@ -0,0 +1,89 @@
+import type { ProjectArea } from '../../areas/consts.js'
+import type { StoryKind } from '../../ba/consts.js'
+import type { PurposeEvidenceSource, TaxonomyKind } from '../consts.js'
+import type { OriginProof } from '../types.js'
+
+export interface PurposeInference {
+  purpose: string
+  audience: string
+  source: PurposeEvidenceSource
+  confidence: number
+  evidence: OriginProof[]
+}
+
+/** A flow the ORIGIN implements, before it is turned into stories. */
+export interface OriginFlow {
+  id: string
+  name: string
+  actor: string
+  area: ProjectArea
+  steps: string[]
+  /** Whether the extracted story list covers it. An uncovered flow is a gap the user is shown. */
+  covered: boolean
+  kind: 'ui' | 'job' | 'cli'
+  proofs: OriginProof[]
+}
+
+/** One entry of the restored story list, in the order the records are created in. */
+export interface ConversionStoryRef {
+  code: string
+  story: string
+  area: ProjectArea
+  kind: ConversionStoryKind
+  ordinal: number
+}
+
+/**
+ * A restored story with the origin code that proves it.
+ *
+ * `complexity` is what the per-story price band is scaled by — derived from the proofs and the
+ * algorithms, never asked of a model, so two runs over the same extraction price identically.
+ */
+export interface StoryProof {
+  code: string
+  narrative: string
+  specification: string
+  ux: string
+  ui: string
+  proofs: OriginProof[]
+  algorithms: { name: string, steps: string[], proof: OriginProof }[]
+  complexity: number
+}
+
+export interface AreaAlignment {
+  areas: {
+    area: ProjectArea
+    roles: string[]
+    permissions: string[]
+    stories: string[]
+  }[]
+  /** Roles or permissions no area claimed. Recorded; never silently dropped. */
+  unmapped: string[]
+}
+
+/** The machine-readable graph the manager's conversion diagram is drawn from. */
+export interface StructureSummary {
+  nodes: { id: string, label: string, kind: TaxonomyKind | 'package' | 'area' }[]
+  edges: { from: string, to: string, label?: string }[]
+}
+
+export interface OriginFlowList {
+  flows: OriginFlow[]
+}
+
+/** What the origin's styles say about its design, in the terms the target's theme is written in. */
+export interface DesignInference {
+  concept: string
+  palette: string[]
+  radius?: string
+  font?: string
+}
+
+/**
+ * What KIND of story a conversion produced.
+ *
+ * The analysis half of a conversion produces exactly the two kinds an ordinary initialization
+ * does; a conversion adds one more — a `coverage` story, written so an area the origin serves but
+ * the flow never reaches still has something in it.
+ */
+export type ConversionStoryKind = StoryKind | 'coverage'

package/src/convert/{consts.local.ts → census/consts.local.ts}

@@ -1,4 +1,4 @@
-import { FileClass } from './consts.js'
+import { FileClass } from '../consts.js'
 
 /**
  * Extension → class, for the extensions that decide a file on their own.