dsh-model-everything 0.0.0-stage → 0.2.0

package/src/index.ts

@@ -0,0 +1,289 @@
+/**
+ * dsh-model-everything — DeepSeek Harness native plugin for models and diagrams.
+ *
+ * It ships a skill set (one entry skill plus a skill per domain) and the tools that do
+ * the work: UML diagrams render, parse and review; state machines, protocols and composed
+ * machines are checked by running them; data models and migrations are checked by the same
+ * doctrine; concurrency claims are mined and routed; a verified model is exported to an
+ * external checker; a structure diagram is audited as a dependency graph; two reports are
+ * diffed against each other.
+ *
+ * Every tool carries its own description and every report says what it proves, so a model
+ * reaches for one the way it reaches for any other tool: by reading what it says it does.
+ * The plugin writes nothing into a session.
+ *
+ * The skills ship in this package's `skills/` directory and are registered at apply time
+ * into dsh's `ctx.skills` registry through the standard filesystem provider, so they appear
+ * in every session catalog without a manual copy step.
+ *
+ * Method, doctrine and per-domain detail live in the skills and their references, not here.
+ *
+ * @module dsh-model-everything
+ */
+
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import type { ContextFormed } from '@deepseek-ai/dsh-llm'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
+import type { HostCordisInspectProviderRegistration } from '@deepseek-ai/dsh-cordis-host-runner'
+import type { AssembleContext, PromptContext } from '@deepseek-ai/dsh-system-prompt'
+import { FileSystemSkillProvider } from '@deepseek-ai/dsh-skill-filesystem'
+import { modelVerifyTool } from './tool.js'
+import { modelDataModelVerifyTool, DATA_ENGINE_SCHEMA_VERSION } from './data-tool.js'
+import { modelConcurrencyScanTool } from './concurrency-tool.js'
+import { modelComposeTool } from './compose-tool.js'
+import { modelExportTool } from './export-tool.js'
+import { umlRenderTool, umlParseTool, umlReviewTool, umlExplainLabelsTool } from './uml-tool.js'
+import { umlStructureTool } from './structure-tool.js'
+import { designTool } from './design-tool.js'
+import { reportDiffTool } from './report-diff-tool.js'
+import { ENGINE_SCHEMA_VERSION } from './engine.js'
+
+// DSH 0.1.7-alpha.1 (session format v4) retires the shared
+// `{ kind: 'plugin', plugin }` wrapper: native admission rejects it in every
+// declared durable message slot, and the official v3-to-v4 migration rewrites
+// those historical rows to `plugin:<name>`. Declaring the producer-owned kind
+// here keeps the write path and the history guard on one identity, and still
+// compiles against the earlier releases that only declare `plugin`.
+
+export const name = 'dsh-model-everything'
+
+// Skills are contributed through the registry service, which dsh-base always
+// mounts before bundle rows such as this one apply.
+export const inject = ['skills']
+
+// Absolute path of the package's shipped skills directory. `lib/index.js`
+// lives one level below the package root, so `../skills` from the module URL
+// lands on `<package>/skills` regardless of where the package was installed.
+const SKILLS_DIR = fileURLToPath(new URL('../skills', import.meta.url))
+
+
+
+export type InteractionMode = 'ask' | 'auto' | 'follow-approval'
+
+
+export interface Config {
+  /**
+   * How an offer to run a tool resolves: `ask` and `auto` are fixed, while `follow-approval`
+   * reads the session's approval policy per call. `resolveInteraction` is its only reader.
+   *
+   * There is deliberately no on/off key here. A row is switched off by the loader row that
+   * mounts it (`disabled`, or the plugin manager), which removes the tools and the skills
+   * together; a key that turned the tools off while the skills stayed would leave every skill
+   * naming a tool that is not there, which is worse than having no skill at all.
+   */
+  interaction: InteractionMode
+}
+
+export const Config = z.object({
+  interaction: z.union(['ask', 'auto', 'follow-approval']).default('follow-approval'),
+})
+
+
+interface SessionEventLike {
+  type: string
+  data?: Record<string, unknown>
+}
+
+/**
+ * Minimum session-store surface this plugin reads. DSH 0.1.2-alpha.4 replaced
+ * the `Session.events` getter with on-demand reads (`seq`, `eventAt()`,
+ * `snapshotEvents()`); releases up to 0.1.2-alpha.3 expose `events` as the
+ * full log snapshot. Read through a structural union so one build serves every
+ * declared DSH release.
+ */
+interface SessionEventSource {
+  events?: readonly SessionEventLike[]
+  snapshotEvents?: () => readonly SessionEventLike[]
+}
+
+function readSessionEvents(session: Session): readonly SessionEventLike[] {
+  const source = session as unknown as SessionEventSource
+  if (typeof source.snapshotEvents === 'function') {
+    const snapshot = source.snapshotEvents()
+    if (Array.isArray(snapshot)) return snapshot
+  }
+  if (Array.isArray(source.events)) return source.events
+  return []
+}
+
+function lastApprovalPolicy(session: Session): 'ask' | 'never' | undefined {
+  const events = readSessionEvents(session)
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (event.type === 'approval/policy') {
+      return event.data?.policy === 'never' ? 'never' : 'ask'
+    }
+  }
+  return undefined
+}
+
+function planModeActive(session: Session): boolean {
+  const events = readSessionEvents(session)
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index]
+    if (event.type === 'plan/mode') return event.data?.active === true
+  }
+  return false
+}
+
+function resolveInteraction(config: Config, session: Session): 'ask' | 'auto' {
+  if (config.interaction === 'ask' || config.interaction === 'auto') return config.interaction
+  return lastApprovalPolicy(session) === 'never' ? 'auto' : 'ask'
+}
+
+
+interface ToolRegistryLike {
+  register(definition: unknown): () => void
+}
+
+interface SystemPromptLike {
+  context(contribution: PromptContext): () => void
+}
+
+/**
+ * Model-visible catalog entry (cordis_inspect_list / cordis_inspect_query):
+ * lets the model read this plugin's runtime status without guessing. Mirrors
+ * the registration pattern of the official dsh-tool-cordis host providers.
+ */
+function inspectProvider(config: Config, isToolRegistered: () => boolean, isDataToolRegistered: () => boolean, isConcurrencyToolRegistered: () => boolean, isComposeToolRegistered: () => boolean, isExportToolRegistered: () => boolean, isUmlToolRegistered: () => boolean, isStructureToolRegistered: () => boolean, isReportDiffToolRegistered: () => boolean): HostCordisInspectProviderRegistration {
+  return {
+    manifest: {
+      id: 'dsh-model-everything',
+      description: 'Model and diagram tooling for DeepSeek Harness: UML diagrams (render, read, review), executable verification of state machines, protocols and composed machines, data-model and migration checks, concurrency claim routing, external-checker export, dependency-graph review, and report diffing. The tools carry their own descriptions; the skills carry the doctrine and the per-domain detail.',
+      methods: [
+        {
+          name: 'status',
+          description: 'Read this plugin status: whether it registers its tools, which tools are on, and the model schema versions the bundled engines accept.',
+          inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+          },
+          outputSchema: {
+            type: 'object',
+            description: 'Plugin status: registration state and the schema versions the bundled engines accept.',
+            properties: {
+              interaction: { type: 'string', enum: ['ask', 'auto', 'follow-approval'], description: 'Configured interaction mode. follow-approval resolves per session from approval/policy.' },
+              toolRegistered: { type: 'boolean', description: 'Whether the model_verify tool is registered on ctx.tools.' },
+              dataToolRegistered: { type: 'boolean', description: 'Whether the model_datamodel_verify tool is registered on ctx.tools.' },
+              concurrencyToolRegistered: { type: 'boolean', description: 'Whether the model_interleaving_scan tool is registered on ctx.tools.' },
+              composeToolRegistered: { type: 'boolean', description: 'Whether the model_compose_verify tool is registered on ctx.tools.' },
+              exportToolRegistered: { type: 'boolean', description: 'Whether the model_export tool is registered on ctx.tools.' },
+              umlToolsRegistered: { type: 'boolean', description: 'Whether the four UML tools (uml_render, uml_parse, uml_review, uml_explain_labels) are registered on ctx.tools.' },
+              structureToolRegistered: { type: 'boolean', description: 'Whether the uml_structure_verify tool (structure-diagram / dependency review) is registered on ctx.tools.' },
+              reportDiffToolRegistered: { type: 'boolean', description: 'Whether the report_diff tool (baseline report comparison) is registered on ctx.tools.' },
+              engineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled state-machine verification engine accepts.' },
+              dataEngineSchemaVersion: { type: 'integer', description: 'Model schema version the bundled data-model verification engine accepts.' },
+            },
+            additionalProperties: false,
+          },
+        },
+      ],
+    },
+    query: async (method) => {
+      if (method === 'status') {
+        return {
+          interaction: config.interaction,
+          toolRegistered: isToolRegistered(),
+          dataToolRegistered: isDataToolRegistered(),
+          concurrencyToolRegistered: isConcurrencyToolRegistered(),
+          composeToolRegistered: isComposeToolRegistered(),
+          exportToolRegistered: isExportToolRegistered(),
+          umlToolsRegistered: isUmlToolRegistered(),
+          structureToolRegistered: isStructureToolRegistered(),
+          reportDiffToolRegistered: isReportDiffToolRegistered(),
+          engineSchemaVersion: ENGINE_SCHEMA_VERSION,
+          dataEngineSchemaVersion: DATA_ENGINE_SCHEMA_VERSION,
+        }
+      }
+      return null
+    },
+  }
+}
+
+export function apply(ctx: Context, config: Config): void {
+  // Optional services are registered opportunistically; base-bundle rows can
+  // mount after this row applies, so registration is retried on the first
+  // agent/pre-step — by then the app is fully booted.
+  let providerRegistered = false
+  let toolRegistered = false
+  let dataToolRegistered = false
+  let concurrencyToolRegistered = false
+  let composeToolRegistered = false
+  let exportToolRegistered = false
+  let umlToolsRegistered = false
+  let structureToolRegistered = false
+  let reportDiffToolRegistered = false
+  const registerProvider = (): void => {
+    if (providerRegistered) return
+    const inspect = ctx.get('cordisInspect')
+    if (inspect === undefined) return
+    try {
+      ctx.effect(() => inspect.register(inspectProvider(config, () => toolRegistered, () => dataToolRegistered, () => concurrencyToolRegistered, () => composeToolRegistered, () => exportToolRegistered, () => umlToolsRegistered, () => structureToolRegistered, () => reportDiffToolRegistered)), 'dsh-model-everything: inspect provider')
+      providerRegistered = true
+    } catch (err) {
+      console.warn('[dsh-model-everything] inspect provider registration failed', err)
+    }
+  }
+  const registerTool = (): void => {
+    if (toolRegistered) return
+    const tools = ctx.get('tools') as ToolRegistryLike | undefined
+    if (tools === undefined) return
+    try {
+      ctx.effect(() => tools.register(modelVerifyTool), 'dsh-model-everything: verify tool')
+      ctx.effect(() => tools.register(modelDataModelVerifyTool), 'dsh-model-everything: data verify tool')
+      ctx.effect(() => tools.register(modelConcurrencyScanTool), 'dsh-model-everything: concurrency scan tool')
+      ctx.effect(() => tools.register(modelComposeTool), 'dsh-model-everything: compose tool')
+      ctx.effect(() => tools.register(modelExportTool), 'dsh-model-everything: export tool')
+      ctx.effect(() => tools.register(umlRenderTool), 'dsh-model-everything: uml render tool')
+      ctx.effect(() => tools.register(umlParseTool), 'dsh-model-everything: uml parse tool')
+      ctx.effect(() => tools.register(umlReviewTool), 'dsh-model-everything: uml review tool')
+      ctx.effect(() => tools.register(umlExplainLabelsTool), 'dsh-model-everything: uml explain-labels tool')
+      ctx.effect(() => tools.register(umlStructureTool), 'dsh-model-everything: structure tool')
+      ctx.effect(() => tools.register(designTool), 'dsh-model-everything: design review tool')
+      ctx.effect(() => tools.register(reportDiffTool), 'dsh-model-everything: report diff tool')
+      toolRegistered = true
+      dataToolRegistered = true
+      concurrencyToolRegistered = true
+      composeToolRegistered = true
+      exportToolRegistered = true
+      umlToolsRegistered = true
+      structureToolRegistered = true
+      reportDiffToolRegistered = true
+    } catch (err) {
+      console.warn('[dsh-model-everything] model_verify/model_datamodel_verify tool registration failed', err)
+    }
+  }
+  const registerIntegrations = (): void => {
+    registerProvider()
+    registerTool()
+  }
+  registerIntegrations()
+  // Ship the bundled skill through the registry: reuse the standard
+  // filesystem provider over this package's own `skills/` directory, so
+  // catalog discovery, frontmatter parsing, and SKILL.md loading behave
+  // exactly like project/user skills while the plugin stays self-contained.
+  // Registration lands in the global registry layer (this row mounts at the
+  // profile root), so every agent preset sees the skill. `registerProvider`
+  // returns the effect disposer; its teardown unregisters and invalidates.
+  ctx.skills.registerProvider((control) => {
+    return new FileSystemSkillProvider(ctx, control, {
+      providerName: 'dsh-model-everything',
+      includeDefaultRoots: false,
+      customSkillDirs: [SKILLS_DIR],
+    })
+  })
+  // Optional services register opportunistically and a base-bundle row can mount after
+  // this one applies, so registration is retried on the first model step - the point by
+  // which the app is fully booted. Nothing is appended to the step: the tools and the
+  // skill text are the guide, not an injected reminder. Session-start routing, if a
+  // deployment wants it, is the separate gate component in `gate.ts`, not this row.
+  ctx.on('agent/pre-step', async (_payload, next) => {
+    const decision = await next()
+    registerIntegrations()
+    return decision
+  })
+}

package/src/json-value.ts

@@ -0,0 +1,20 @@
+/**
+ * Structural mirror of the JSON value union the dsh tool registry accepts.
+ *
+ * `@deepseek-ai/dsh-tools` exported this type through the 0.1.x line and stopped
+ * exporting it in 0.2.x, where the same type now lives in
+ * `@deepseek-ai/dsh-util-values`. This package declares peer support for both
+ * lines, so it cannot import the type from either one without breaking the other
+ * build. Declaring the one-line union here keeps `npm run typecheck` green against
+ * both, and it costs nothing at runtime: every use is a type-only cast on a value
+ * this package already produced.
+ *
+ * Keep it structurally identical to the official type. A cast through `unknown` to
+ * this alias is only a way to satisfy `defineTool`'s return-type constraint; if the
+ * official union ever widens, this alias must widen with it.
+ *
+ * @module this plugin-json-value
+ */
+
+/** JSON-serializable value: null, boolean, number, string, or an array/object of those. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue }

package/src/model-file.ts

@@ -0,0 +1,49 @@
+/**
+ * Read a JSON model from a file instead of requiring it inline.
+ *
+ * A model is the largest argument any of these tools takes, and it is the one that arrives as
+ * streamed tool-call JSON: the provider rejected one session with `tool input is invalid JSON`
+ * after the model spent sixteen steps hand-editing a nested model argument. Reading it from the
+ * workspace removes that failure mode and the tokens.
+ */
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { OptionShapeError } from './option-shape.js'
+
+/** Read and parse one JSON file. Formatting is irrelevant: whitespace, BOM and pretty printing all parse. */
+export function readJsonFile(path: unknown, option: string, code: string): unknown {
+  if (typeof path !== 'string' || path.trim() === '') {
+    throw new OptionShapeError(code, `${option} must be a non-empty path to a JSON file.`)
+  }
+  const full = resolve(path)
+  let text: string
+  try {
+    text = readFileSync(full, 'utf8')
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new OptionShapeError(code, `${option} could not be read: ${reason}. The path resolves against the process working directory; relative paths in a session resolve against the session's workspace.`)
+  }
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, ''))
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error)
+    throw new OptionShapeError(code, `${option} is not valid JSON: ${reason}.`)
+  }
+}
+
+/**
+ * Exactly one of the inline value and the file path. Both is ambiguous, neither is a missing
+ * argument, and each gets its own sentence so the caller knows which one to drop.
+ */
+export function oneOf(value: unknown, path: unknown, inlineName: string, pathName: string, code: string): unknown {
+  const hasValue = value !== undefined
+  const hasPath = path !== undefined
+  if (hasValue && hasPath) {
+    throw new OptionShapeError(code, `Pass either ${inlineName} or ${pathName}, not both: the file would be read and then ignored, or the other way round.`)
+  }
+  if (!hasValue && !hasPath) {
+    throw new OptionShapeError(code, `Pass ${inlineName} or ${pathName}: the model has to come from somewhere.`)
+  }
+  return hasPath ? readJsonFile(path, pathName, code) : value
+}

package/src/option-shape.ts

@@ -0,0 +1,64 @@
+/**
+ * Option shapes at the tool boundary.
+ *
+ * A tool declares `type: 'json'` for an option, which accepts any JSON value, and the engine then reads
+ * it as the type it needs. A string where an array was expected threw `machinesInput.forEach is not a
+ * function` and `(options.migrationMappings ?? []).map is not a function` - raw TypeErrors with no code,
+ * which a caller cannot route on and which say nothing about which option was wrong.
+ *
+ * The suite pinned those as known gaps. This closes them the way the rest of the plugin reports a
+ * refusal: a code naming the family, and a message naming the option.
+ */
+
+/** A refusal the caller can route on: the domain's code, and what arrived. */
+export class OptionShapeError extends Error {
+  constructor(
+    readonly errorCode: string,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'OptionShapeError'
+  }
+}
+
+function describe(value: unknown): string {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'an array'
+  return 'a ' + typeof value
+}
+
+/** An option the engine reads with `.map`: a string or a number is not one. */
+export function requireArrayOption(value: unknown, option: string, errorCode: string): void {
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    throw new OptionShapeError(errorCode, option + ' is ' + describe(value) + ', not an array. This option is read as a list; omit it, or pass the list the engine documents.')
+  }
+  // A null ENTRY fails later, deeper, with a message about a property of null. Naming the index here is the
+  // difference between "something is wrong" and "entry 2 is wrong".
+  const bad = value.findIndex((entry) => entry === null || typeof entry !== 'object' || Array.isArray(entry))
+  if (bad >= 0) {
+    throw new OptionShapeError(errorCode, option + '[' + String(bad) + '] is ' + describe(value[bad]) + ', not an object. Each entry is read as a mapping or a pair; a position cannot be omitted.')
+  }
+}
+
+/** An option the engine reads with `Object.entries`: a string has entries, and they are not the ones meant. */
+export function requireObjectOption(value: unknown, option: string, errorCode: string): void {
+  if (value === undefined) return
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new OptionShapeError(errorCode, option + ' is ' + describe(value) + ', not an object. This option is read as a map from one name to another.')
+  }
+}
+
+/** The refusal a tool returns for a shape it could not read. */
+export function optionRefusal(error: unknown, errorCode: string): Record<string, unknown> {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = error instanceof OptionShapeError ? error.errorCode : errorCode
+  return {
+    ok: false,
+    ran: false,
+    verdict: 'fail',
+    verdictReason: 'the tool did not run: ' + message,
+    errorCode: code,
+    error: message,
+  }
+}

package/src/report-diff-tool.ts

@@ -0,0 +1,67 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from './json-value.js'
+import { diffReports } from './baseline.js'
+import { refusalVerdict } from './engine.js'
+import { renderReportText } from './report-view.js'
+
+export const REPORT_DIFF_TOOL_NAME = 'report_diff'
+
+/**
+ * Turn a refusal into a report the model can route on.
+ *
+ * `diffReports` throws when a side is not a report, which is the right thing at the engine boundary -
+ * there is nothing to compare and no verdict to give. The tool boundary has a different obligation:
+ * malformed input has to come back as something with a code, never as a raw throw. This is the same
+ * shape the UML tools use, with a code of this tool's own.
+ */
+function refusal(error: unknown): JsonValue {
+  const message = error instanceof Error ? error.message : String(error)
+  return { ok: false, ran: false, ...refusalVerdict(message), errorCode: 'REPORT_INVALID', error: message } as unknown as JsonValue
+}
+
+/**
+ * Model-visible DSH tool that compares two reports of the same family — the accepted
+ * "violations must not increase" acceptance criterion, computed instead of eyeballed.
+ * A finding's identity is its check + code + machine-readable locator, so a reworded
+ * message reads as `changed`, and two runs over the same input add nothing.
+ */
+export const reportDiffTool = defineTool({
+  name: REPORT_DIFF_TOOL_NAME,
+  description:
+    'Compare two reports of the same family, to accept a change by what it added rather than by reading two reports: `baseline` (earlier) against `current` (newer). Use it to accept a slice by "no new findings". Findings match on a stable identity: check id, code, and a locator built from `evidence` and `path`. Reworded prose counts as `changed`, not as new. Returns added, removed and changed findings, plus `summary`. It does not look at a single artefact and it does not produce a report of its own: for the first look at one, call the domain tool directly (`model_verify`, `model_datamodel_verify`, `model_design_review`, `uml_review`, `uml_structure_verify`, `model_interleaving_scan`), then compare what those two calls returned. `verdict` is about the delta: a newly added error finding fails it. `currentVerdict` keeps the run\'s own verdict, so a clean delta over a failing report still shows as failing. Two runs over the same input add nothing. Both sides have to be reports this can compare: a refusal, a run that examined nothing, and a report from another family are refused with `REPORT_INVALID` instead of being compared, because a finding absent from an incomparable roster would otherwise read as resolved.',
+  parameters: {
+    baseline: {
+      type: 'json',
+      required: true,
+      description: 'The earlier report (any family: verify, compose, datamodel, uml review, structure, concurrency).',
+    },
+    current: {
+      type: 'json',
+      required: true,
+      description: 'The current report to compare against the baseline.',
+    },
+    reportView: {
+      type: 'string',
+      enum: ['digest', 'full'],
+      description: 'digest (default) prints the readable body; full prints the structured diff report.',
+    },
+  },
+  output: {
+    schema: {
+      type: 'json',
+      description: 'Baseline diff report: added/removed/changed findings, delta verdict, current verdict, summary and next steps.',
+    },
+    render(args, value) {
+      return [{ type: 'text' as const, text: renderReportText(value, { full: args.reportView === 'full' }) }]
+    },
+  },
+  timeoutMs: 10_000,
+  isConcurrencySafe: () => true,
+  async execute(args) {
+    try {
+      return diffReports(args.baseline, args.current) as unknown as JsonValue
+    } catch (error) {
+      return refusal(error)
+    }
+  },
+})