dsh-draw 0.1.0

package/src/session-events.ts

@@ -0,0 +1,70 @@
+/**
+ * The dsh-draw session event: one durable record per completed generation
+ * (tool call or panel regenerate), appended to the owning session log. It is
+ * log-only (`ignorable`) and exists so quota accounting and the durable audit
+ * trail are reconstructable from the log alone. The model-visible input and
+ * output of the call ride the loop-owned `tool/call` and `tool/result`
+ * events; this event carries the accounting facts those events do not.
+ *
+ * @module dsh-draw/session-events
+ */
+
+import type { Session } from '@deepseek-ai/dsh-session'
+
+declare module '@deepseek-ai/dsh-session/types' {
+  interface SessionEventMap {
+    /**
+     * One completed image generation: engine, standardized request, produced
+     * bytes, and the durable attachment ids. Log-only UI/accounting state.
+     */
+    'draw/generated': DrawGeneratedEvent
+  }
+}
+
+/** Payload of the `draw/generated` session event. */
+export interface DrawGeneratedEvent {
+  /** Engine id that produced the images. */
+  engine: string
+  /** Engine model name. */
+  model: string
+  /** Who requested the generation: the tool body or a panel regenerate. */
+  source: 'tool' | 'regenerate'
+  /** The standardized prompt, verbatim from the model request. */
+  prompt: string
+  /** Standard size vocabulary value of the request. */
+  size: 'square' | 'landscape' | 'portrait' | 'auto'
+  /** Standard quality value of the request. */
+  quality: 'low' | 'medium' | 'high' | 'auto'
+  /** Number of images produced. */
+  count: number
+  /** Sum of the produced image byte lengths. */
+  bytes: number
+  /** Durable attachment ids in result order. */
+  attachmentIds: readonly string[]
+  /** Engine round-trip latency in milliseconds. */
+  elapsedMs: number
+}
+
+/**
+ * Append one `draw/generated` event to a session.
+ *
+ * @param session - owning session.
+ * @param event - accounting payload.
+ * @returns the logged event.
+ */
+export function appendDrawGenerated(session: Session, event: DrawGeneratedEvent) {
+  // Two-argument append: the pinned 0.1.0-rc.6 peers have no append-envelope
+  // option; the two-argument form typechecks against rc.6 and newer builds.
+  return session.append('draw/generated', event)
+}
+
+/**
+ * Collect the `draw/generated` events of a session in log order. Declaration
+ * merging narrows `event.type === 'draw/generated'` to the payload type.
+ *
+ * @param session - session whose log is scanned.
+ * @returns the accounting events.
+ */
+export function drawGeneratedEvents(session: Session): readonly import('@deepseek-ai/dsh-session').SessionEvent<'draw/generated'>[] {
+  return session.events.filter(event => event.type === 'draw/generated')
+}

package/src/tool.ts

@@ -0,0 +1,145 @@
+/**
+ * The `image_generate` tool: the model-facing unified image generation entry.
+ * Standard parameters (prompt/size/count/quality/style/engine) flow into the
+ * shared drawer path; the canonical value carries the durable attachment
+ * references plus quota and routing facts, and the render output embeds the
+ * images as attachment content blocks so both text-only surfaces and the web
+ * conversation show them.
+ *
+ * @module dsh-draw/tool
+ */
+
+import { AttachmentId, type ImageAttachmentRef } from '@deepseek-ai/dsh-attachment'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { JsonValue } from '@deepseek-ai/dsh-session'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ResolvedConfig } from './config.ts'
+import type { Drawer, DrawSuccess } from './drawer.ts'
+
+/** Tool argument surface (validated by the schema; the drawer re-normalizes). */
+export interface ImageGenerateArgs {
+  prompt: string
+  size?: 'square' | 'landscape' | 'portrait' | 'auto'
+  count?: number
+  quality?: 'low' | 'medium' | 'high' | 'auto'
+  style?: 'natural' | 'vivid'
+  engine?: string
+}
+
+/**
+ * Build the `image_generate` tool over one drawer.
+ *
+ * @param drawer - the shared generation path.
+ * @param config - resolved config (prompt cap for the description, timeout budget).
+ * @returns the tool definition.
+ */
+export function imageGenerateTool(drawer: Drawer, config: ResolvedConfig) {
+  return defineTool({
+    name: 'image_generate',
+    description: `Generate 1..${config.maxImagesPerCall} static images from a text prompt through the configured image engines (OpenAI Images, Zhipu CogView, or any OpenAI-compatible endpoint). Standard parameters are translated per engine; a failing engine falls back down the configured chain. Results are saved as durable attachments and count against the per-session quota. Prompt cap: ${config.maxPromptLength} characters.`,
+    parameters: {
+      prompt: { type: 'string' as const, description: 'Image prompt.', required: true as const },
+      size: { type: 'string' as const, enum: ['square', 'landscape', 'portrait', 'auto'] as const, description: 'Composition (default square).' },
+      count: { type: 'integer' as const, description: 'Number of images (default 1; capped by configuration).' },
+      quality: { type: 'string' as const, enum: ['low', 'medium', 'high', 'auto'] as const, description: 'Quality tier (default auto; dropped for engines without it).' },
+      style: { type: 'string' as const, enum: ['natural', 'vivid'] as const, description: 'Style preset (dropped for engines without it).' },
+      engine: { type: 'string' as const, description: 'Engine id override (must name a configured engine; omitted = chain order).' },
+    },
+    output: {
+      schema: {
+        type: 'object' as const,
+        properties: {
+          ok: { type: 'boolean' as const, const: true },
+          engine: { type: 'string' as const },
+          model: { type: 'string' as const },
+          size: { type: 'string' as const },
+          images: {
+            type: 'array' as const,
+            items: {
+              type: 'object' as const,
+              properties: {
+                attachmentId: { type: 'string' as const },
+                mediaType: { type: 'string' as const },
+                bytes: { type: 'integer' as const },
+                width: { type: 'integer' as const },
+                height: { type: 'integer' as const },
+                name: { type: 'string' as const },
+              },
+              additionalProperties: false,
+            },
+          },
+          quota: {
+            type: 'object' as const,
+            properties: {
+              generations: { type: 'integer' as const },
+              bytes: { type: 'integer' as const },
+            },
+            additionalProperties: false,
+          },
+          limits: {
+            type: 'object' as const,
+            properties: {
+              maxGenerations: { type: 'integer' as const },
+              maxBytes: { type: 'integer' as const },
+            },
+            additionalProperties: false,
+          },
+          fallbackUsed: { type: 'boolean' as const },
+          elapsedMs: { type: 'integer' as const },
+          attempts: {
+            type: 'array' as const,
+            items: {
+              type: 'object' as const,
+              properties: {
+                engine: { type: 'string' as const },
+                phase: { oneOf: [{ type: 'string' as const }, { type: 'null' as const }] as const },
+                code: { type: 'string' as const },
+                message: { oneOf: [{ type: 'string' as const }, { type: 'null' as const }] as const },
+                status: { oneOf: [{ type: 'integer' as const }, { type: 'null' as const }] as const },
+              },
+              additionalProperties: false,
+            },
+          },
+        },
+        additionalProperties: false,
+      },
+      render(_args, value): ContentBlock[] {
+        const result = value as unknown as DrawSuccess
+        const lines = [
+          `Generated ${result.images.length} image(s) via ${result.engine} (${result.model}, ${result.size})${result.fallbackUsed ? ' after fallback' : ''} in ${result.elapsedMs} ms.`,
+          `Quota: ${result.quota.generations}/${result.limits.maxGenerations} calls, ${result.quota.bytes}/${result.limits.maxBytes} bytes this session.`,
+        ]
+        for (const attempt of result.attempts) {
+          if (attempt.code === 'ok') continue
+          lines.push(`- ${attempt.engine}: ${attempt.code}${attempt.message === undefined ? '' : ` (${attempt.message})`}`)
+        }
+        const blocks: ContentBlock[] = [{ type: 'text', text: lines.join('\n') }]
+        for (const image of result.images) {
+          const attachment: ImageAttachmentRef = {
+            attachmentId: AttachmentId(image.attachmentId),
+            mediaType: image.mediaType as ImageAttachmentRef['mediaType'],
+            bytes: image.bytes,
+            width: image.width,
+            height: image.height,
+            ...(image.name !== undefined ? { name: image.name } : {}),
+          }
+          blocks.push({ type: 'image', attachment })
+        }
+        return blocks
+      },
+      // The result card reads the canonical value through this replayable
+      // presentation projection (the frozen client block exposes only `meta`).
+      presentationMeta(_args, value): JsonValue {
+        return value as unknown as JsonValue
+      },
+    },
+    timeoutMs: config.requestTimeoutMs,
+    async execute(args, exec) {
+      const outcome = await drawer.generate(args as unknown, { session: exec.agent?.session, source: 'tool', signal: exec.signal })
+      if (!outcome.ok) throw new Error(outcome.message)
+      // The schema-inferred canonical value owns mutable arrays; the drawer's
+      // frozen records are copied into owned mutable ones here.
+      return { ...outcome, images: [...outcome.images], attempts: [...outcome.attempts] }
+    },
+  })
+}

package/src/translate.ts

@@ -0,0 +1,101 @@
+/**
+ * Standard-parameter translation: the tool-level vocabulary
+ * (`prompt`/size/count/quality/style) mapped onto one concrete engine's
+ * request. Pure functions with no I/O — unit tests pin every mapping.
+ *
+ * @module dsh-draw/translate
+ */
+
+import type { ResolvedEngineConfig, StandardSize } from './config.ts'
+
+/** Standard quality vocabulary; `auto` means "leave the engine default". */
+export type StandardQuality = 'low' | 'medium' | 'high' | 'auto'
+
+/** Standard style vocabulary (engines that lack styles drop it). */
+export type StandardStyle = 'natural' | 'vivid'
+
+/** Standard tool-level image request. */
+export interface StandardImageRequest {
+  /** Image prompt, non-empty and within the configured length cap. */
+  prompt: string
+  /** Standard size vocabulary (default `square`). */
+  size?: StandardSize
+  /** Number of images (default 1; capped by the engine/config). */
+  count?: number
+  /** Standard quality vocabulary (default `auto`). */
+  quality?: StandardQuality
+  /** Standard style vocabulary; omitted = engine default. */
+  style?: StandardStyle
+  /** Engine id override; omitted = the router's chain order. */
+  engine?: string
+}
+
+/** Concrete per-engine request body fields. */
+export interface TranslatedImageRequest {
+  /** Engine model name. */
+  model: string
+  /** Prompt, verbatim. */
+  prompt: string
+  /** Concrete engine size string. */
+  size: string
+  /** Number of images. */
+  n: number
+  /** Included only when the engine declares quality support and it is not `auto`. */
+  quality?: StandardQuality
+  /** Included only when the engine declares style support and one was requested. */
+  style?: StandardStyle
+  /** How the response delivers bytes. */
+  responseFormat: 'b64_json' | 'url'
+}
+
+const SIZES: readonly StandardSize[] = ['square', 'landscape', 'portrait', 'auto']
+const QUALITIES: readonly StandardQuality[] = ['low', 'medium', 'high', 'auto']
+const STYLES: readonly StandardStyle[] = ['natural', 'vivid']
+
+/**
+ * Normalize unvalidated tool args to a {@link StandardImageRequest}; malformed
+ * values fall back to defaults. The prompt passes through verbatim — length
+ * validation is the drawer's job (an over-long prompt fails the call loudly
+ * instead of being silently truncated).
+ *
+ * @param args - unvalidated tool arguments.
+ * @param maxImagesPerCall - configured cap the requested count clamps to.
+ * @returns the normalized request.
+ */
+export function normalizeRequest(args: unknown, maxImagesPerCall: number): StandardImageRequest {
+  const record = typeof args === 'object' && args !== null ? args as Record<string, unknown> : {}
+  const prompt = typeof record['prompt'] === 'string' ? record['prompt'] : ''
+  const rawSize = record['size']
+  const size = typeof rawSize === 'string' && (SIZES as readonly string[]).includes(rawSize) ? rawSize as StandardSize : 'square'
+  const rawCount = record['count']
+  const parsedCount = typeof rawCount === 'number' ? Math.trunc(rawCount) : 1
+  const count = Math.min(Math.max(Number.isFinite(parsedCount) ? parsedCount : 1, 1), maxImagesPerCall)
+  const rawQuality = record['quality']
+  const quality = typeof rawQuality === 'string' && (QUALITIES as readonly string[]).includes(rawQuality) ? rawQuality as StandardQuality : 'auto'
+  const rawStyle = record['style']
+  const style = typeof rawStyle === 'string' && (STYLES as readonly string[]).includes(rawStyle) ? rawStyle as StandardStyle : undefined
+  const rawEngine = record['engine']
+  const engine = typeof rawEngine === 'string' && rawEngine.length > 0 ? rawEngine : undefined
+  return { prompt, size, count, quality, ...(style !== undefined ? { style } : {}), ...(engine !== undefined ? { engine } : {}) }
+}
+
+/**
+ * Translate one standardized request into a concrete engine request.
+ *
+ * @param engine - resolved engine configuration.
+ * @param request - normalized standard request.
+ * @returns the engine request fields.
+ */
+export function translateRequest(engine: ResolvedEngineConfig, request: StandardImageRequest): TranslatedImageRequest {
+  const size = engine.sizeMap[request.size ?? 'square']
+  const requestBody: TranslatedImageRequest = {
+    model: engine.model,
+    prompt: request.prompt,
+    size,
+    n: request.count ?? 1,
+    ...(engine.qualitySupported && request.quality !== 'auto' ? { quality: request.quality } : {}),
+    ...(engine.styleSupported && request.style !== undefined ? { style: request.style } : {}),
+    responseFormat: engine.responseFormat,
+  }
+  return requestBody
+}

package/src/typert.host.ts

@@ -0,0 +1,25 @@
+/**
+ * The hand-written Typert HOST manifest for `dsh-draw`, exported as `./typert`
+ * so the harness's typert-loader registers the `draw` status/probe/credential/
+ * regenerate invocations automatically when this plugin mounts. Same shape as
+ * a generator output (validated by the loader): package face, empty model and
+ * schemas, and the canonical invocation list shared with the client Remote
+ * contribution (`src/wire.ts`).
+ *
+ * @module dsh-draw/typert
+ */
+
+import { DRAW_INVOCATIONS } from './wire.ts'
+
+/** Host Typert manifest (validated by `@deepseek-ai/dsh-typert-loader`). */
+export const TYPERT = Object.freeze({
+  package: 'dsh-draw',
+  face: 'host',
+  schemas: Object.freeze([]),
+  invocations: DRAW_INVOCATIONS,
+  model: Object.freeze({
+    services: Object.freeze([]),
+    events: Object.freeze([]),
+    objects: Object.freeze([]),
+  }),
+})

package/src/version.ts

@@ -0,0 +1,10 @@
+/**
+ * The plugin version, hardcoded beside `package.json` so the release script
+ * bumps both and `tests/version.spec.ts` trips when they drift. Served in the
+ * `draw/status` snapshot so the settings panel shows which plugin build runs.
+ *
+ * @module dsh-draw/version
+ */
+
+/** Plugin version; must equal the `version` field in `package.json`. */
+export const PLUGIN_VERSION = '0.1.0'