dsh-draw 0.1.0 → 0.1.2

package/src/drawer.ts

@@ -13,7 +13,8 @@ import type { ResolvedConfig } from './config.ts'
 import type { EngineDeps, ProducedImage } from './engine.ts'
 import { checkQuotaBytes, checkQuotaGenerations, type QuotaLimits, type QuotaState } from './quota.ts'
 import { EngineRouter, type AttemptView } from './router.ts'
-import { appendDrawGenerated } from './session-events.ts'
+import { commitDrawGenerated } from './session-events.ts'
+import type { EventGate } from './event-gate.ts'
 import { normalizeRequest } from './translate.ts'
 
 /** One durable result image as the canonical value and wire carry it. */
@@ -102,6 +103,14 @@ export interface DrawerDeps {
   sessions?: () => SessionStore | undefined
 }
 
+/** How the drawer commits the `draw/generated` accounting event. */
+export interface DrawerEventSink {
+  /** The adaptive session-event gate, probed at mount. */
+  gate: EventGate
+  /** Log warning sink for append failures. */
+  warn: (message: string) => void
+}
+
 /**
  * The shared generation path.
  */
@@ -110,11 +119,13 @@ export class Drawer {
    * @param config - resolved plugin configuration.
    * @param router - the engine router.
    * @param deps - per-call dependencies (public: the remote service reads them for probes).
+   * @param events - the gated session-event sink (log when safe, in-memory ledger otherwise).
    */
   constructor(
     private readonly config: ResolvedConfig,
     private readonly router: EngineRouter,
     readonly deps: DrawerDeps,
+    private readonly events: DrawerEventSink,
   ) {}
 
   /**
@@ -182,7 +193,7 @@ export class Drawer {
       ...(ref.name !== undefined ? { name: ref.name } : {}),
     }))
     const elapsedMs = Date.now() - startedAt
-    appendDrawGenerated(session, {
+    commitDrawGenerated(session, {
       engine: routed.engine,
       model: routed.model,
       source: options.source,
@@ -193,7 +204,7 @@ export class Drawer {
       bytes: totalBytes,
       attachmentIds: images.map(image => image.attachmentId),
       elapsedMs,
-    })
+    }, this.events.gate, this.events.warn)
     const after = checkQuotaGenerations(session, limits)
     return {
       ok: true,

package/src/event-gate.ts

@@ -0,0 +1,84 @@
+/**
+ * The session-event adaptive gate. `draw/generated` is declared only in this
+ * package's types, so it sits outside every host's `KNOWN_SESSION_EVENT_TYPES`:
+ * hosts whose session reader validates a static whitelist (rc.6/rc.7) refuse to
+ * reopen a session containing the event unless it carries the `ignorable`
+ * envelope — and those hosts' `Session.append` cannot stamp it. The gate
+ * therefore appends only when the type is host-known or a mount-time probe
+ * proves envelope support; otherwise the accounting payload goes to the
+ * in-memory fallback ledger (see session-events.ts) so quota keeps working for
+ * the live session without poisoning the log.
+ *
+ * @module dsh-draw/event-gate
+ */
+
+import { Context } from '@deepseek-ai/cordis'
+import SessionStore, { KNOWN_SESSION_EVENT_TYPES } from '@deepseek-ai/dsh-session'
+
+/** One gate decision: whether to append, and whether to mark ignorable. */
+export interface EventGateDecision {
+  /** Append the event to the session log. */
+  append: boolean
+  /** Stamp the `ignorable` envelope (only meaningful when append). */
+  ignorable: boolean
+}
+
+/** Decision function over session event types. */
+export type EventGate = (type: string) => EventGateDecision
+
+/**
+ * Build the gate: host-known types append plainly; unknown types append with
+ * the ignorable envelope only when the host append honors it; everything else
+ * is skipped — an unknown, unmarked event would make the session refuse to
+ * load on restart under the rc.6/rc.7 static whitelist.
+ *
+ * @param knownTypes - the host's KNOWN_SESSION_EVENT_TYPES.
+ * @param ignorableAppend - whether the host append stamps the envelope.
+ * @returns the decision function.
+ */
+export function makeEventGate(knownTypes: ReadonlySet<string>, ignorableAppend = false): EventGate {
+  return (type) => {
+    if (knownTypes.has(type)) return { append: true, ignorable: false }
+    if (ignorableAppend) return { append: true, ignorable: true }
+    return { append: false, ignorable: false }
+  }
+}
+
+/** The append face the probe needs; rc.6 types declare no envelope parameter. */
+type EnvelopeAppend = (type: string, data: unknown, opts: { ignorable: boolean }) => { ignorable?: boolean } | undefined
+
+/**
+ * Probe whether the host `Session.append` stamps the ignorable envelope. Runs
+ * on a fully detached SessionStore — never host persistence — appending one
+ * probe event with `{ ignorable: true }` and reading the marker back. rc.6's
+ * append silently drops the unknown options key (probe false); every failure
+ * is contained as "unsupported".
+ *
+ * @returns whether the envelope is honored.
+ */
+export function probeIgnorableAppend(): boolean {
+  try {
+    const store = new SessionStore(new Context())
+    const session = store.create()
+    const event = (session.append as unknown as EnvelopeAppend)('draw/generated', {
+      engine: 'probe',
+      model: 'probe',
+      source: 'tool',
+      prompt: 'probe',
+      size: 'auto',
+      quality: 'auto',
+      count: 0,
+      bytes: 0,
+      attachmentIds: [],
+      elapsedMs: 0,
+    }, { ignorable: true })
+    return event?.ignorable === true
+  } catch {
+    return false
+  }
+}
+
+/** The gate over the host's known types plus the probed envelope support. */
+export function makeHostEventGate(): EventGate {
+  return makeEventGate(KNOWN_SESSION_EVENT_TYPES, probeIgnorableAppend())
+}

package/src/index.ts

@@ -22,6 +22,7 @@ import type { SessionStore } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-tools'
 import { Config, resolveConfig } from './config.ts'
 import { Drawer } from './drawer.ts'
+import { makeHostEventGate } from './event-gate.ts'
 import { defaultHttpTransport, type HttpTransport } from './http.ts'
 import { EngineRouter } from './router.ts'
 import { DrawService } from './service.ts'
@@ -42,7 +43,8 @@ export { callEngine, EngineCallError, type EngineDeps, type ProducedImage } from
 export { translateRequest, normalizeRequest, type StandardImageRequest } from './translate.ts'
 export { quotaState, checkQuotaGenerations, checkQuotaBytes, type QuotaLimits, type QuotaState } from './quota.ts'
 export { sanitizeUrl, sanitizeText, sanitizeError, REDACTED } from './sanitize.ts'
-export { appendDrawGenerated, drawGeneratedEvents, type DrawGeneratedEvent } from './session-events.ts'
+export { appendDrawGenerated, commitDrawGenerated, drawGeneratedEvents, fallbackDrawGeneratedEvents, type DrawGeneratedEvent } from './session-events.ts'
+export { makeEventGate, makeHostEventGate, probeIgnorableAppend, type EventGate, type EventGateDecision } from './event-gate.ts'
 export { PLUGIN_VERSION } from './version.ts'
 export { DRAW_INVOCATIONS, imageToWire, statusToView, probeToWire, type DrawStatusSnapshot } from './wire.ts'
 
@@ -72,6 +74,9 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
 
   const credentials = () => ctx.get('credentials') as CredentialProvider | undefined
 
+  // The draw/generated event type is declared only by this package: append it
+  // only when the host knows the type or honors the ignorable envelope;
+  // otherwise the accounting payload rides the in-memory fallback ledger.
   const drawer = new Drawer(resolved, router, {
     engine: {
       transport,
@@ -84,7 +89,7 @@ export async function apply(ctx: Context, config: Config): Promise<void> {
     },
     attachments: () => ctx.get('attachments') as AttachmentStore | undefined,
     sessions: () => ctx.get('sessions') as SessionStore | undefined,
-  })
+  }, { gate: makeHostEventGate(), warn: (message) => logger.warn(message) })
 
   ctx.effect(() => ctx.tools.register(imageGenerateTool(drawer, resolved)), 'dsh-draw: image_generate tool')
 

package/src/quota.ts

@@ -1,14 +1,18 @@
 /**
  * Per-session quota accounting. The durable source of truth is the session
- * log: every completed generation appends one `draw/generated` event, and
- * quota is computed by folding those events, so usage survives restart and
- * fork and cannot drift from what the log records.
+ * log: every completed generation commits one `draw/generated` event, and
+ * quota folds those events, so usage survives restart and fork and cannot
+ * drift from what the log records. On hosts that cannot carry the event
+ * safely (rc.6/rc.7 static whitelist without the ignorable envelope), commits
+ * land in the in-memory fallback ledger instead and quota folds both sources —
+ * live-session accounting stays exact; cross-restart durability resumes when
+ * the host gains a plugin event surface.
  *
  * @module dsh-draw/quota
  */
 
 import type { Session } from '@deepseek-ai/dsh-session'
-import { drawGeneratedEvents } from './session-events.ts'
+import { drawGeneratedEvents, fallbackDrawGeneratedEvents } from './session-events.ts'
 
 /** The two quota axes. */
 export interface QuotaLimits {
@@ -48,9 +52,11 @@ export interface QuotaAllowance {
 export type QuotaCheck = QuotaAllowance | QuotaDenial
 
 /**
- * Fold one session's `draw/generated` events into current usage.
+ * Fold one session's `draw/generated` events into current usage: logged events
+ * first, then the in-memory fallback ledger (disjoint — a commit lands in
+ * exactly one of them).
  *
- * @param session - session whose log is folded.
+ * @param session - session whose log and ledger are folded.
  * @returns generation and byte totals.
  */
 export function quotaState(session: Session): QuotaState {
@@ -60,6 +66,10 @@ export function quotaState(session: Session): QuotaState {
     generations += 1
     bytes += event.data.bytes
   }
+  for (const event of fallbackDrawGeneratedEvents(session)) {
+    generations += 1
+    bytes += event.bytes
+  }
   return { generations, bytes }
 }
 

package/src/session-events.ts

@@ -6,10 +6,18 @@
  * output of the call ride the loop-owned `tool/call` and `tool/result`
  * events; this event carries the accounting facts those events do not.
  *
+ * The event type is declared only here, so plugin paths append it through
+ * {@link commitDrawGenerated}: the adaptive gate (event-gate.ts) appends only
+ * when the host knows the type or honors the `ignorable` envelope, and
+ * otherwise records the payload in the in-memory fallback ledger (live-session
+ * quota keeps working; the durable trail resumes once the host gains a plugin
+ * event surface).
+ *
  * @module dsh-draw/session-events
  */
 
 import type { Session } from '@deepseek-ai/dsh-session'
+import type { EventGate } from './event-gate.ts'
 
 declare module '@deepseek-ai/dsh-session/types' {
   interface SessionEventMap {
@@ -46,18 +54,70 @@ export interface DrawGeneratedEvent {
 }
 
 /**
- * Append one `draw/generated` event to a session.
+ * Append one `draw/generated` event to a session, ungated. Plugin paths use
+ * {@link commitDrawGenerated} instead; this raw form remains for tests and
+ * hosts that know the type.
  *
  * @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)
 }
 
+/** The append face with the envelope option; rc.6 types declare none. */
+type EnvelopeAppend = (type: string, data: unknown, opts: { ignorable: boolean }) => unknown
+
+/**
+ * In-memory accounting ledger for hosts whose session log cannot carry
+ * `draw/generated` safely (rc.6/rc.7 static whitelist, no ignorable envelope).
+ * Keyed by Session identity: the entries live exactly as long as the session.
+ */
+const fallbackLedger = new WeakMap<Session, DrawGeneratedEvent[]>()
+
+/**
+ * Commit one completed generation: append the `draw/generated` event when the
+ * gate allows (with the ignorable envelope when required), otherwise record
+ * the payload in the in-memory fallback ledger. A failed append degrades to
+ * the same ledger and never breaks the draw.
+ *
+ * @param session - owning session.
+ * @param event - accounting payload.
+ * @param gate - the adaptive gate (event-gate.ts).
+ * @param warn - log warning sink for append failures.
+ */
+export function commitDrawGenerated(session: Session, event: DrawGeneratedEvent, gate: EventGate, warn: (message: string) => void): void {
+  const decision = gate('draw/generated')
+  if (decision.append) {
+    try {
+      if (decision.ignorable) {
+        ;(session.append as unknown as EnvelopeAppend)('draw/generated', event, { ignorable: true })
+      } else {
+        session.append('draw/generated', event)
+      }
+      return
+    } catch (error) {
+      warn(`draw session event append failed: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  const list = fallbackLedger.get(session) ?? []
+  list.push(event)
+  fallbackLedger.set(session, list)
+}
+
+/**
+ * The in-memory fallback records of a session, in commit order. Populated
+ * only while the host cannot carry `draw/generated` in the log; quota folds
+ * these on top of the logged events.
+ *
+ * @param session - session whose ledger is read.
+ * @returns the fallback payloads.
+ */
+export function fallbackDrawGeneratedEvents(session: Session): readonly DrawGeneratedEvent[] {
+  return fallbackLedger.get(session) ?? []
+}
+
 /**
  * Collect the `draw/generated` events of a session in log order. Declaration
  * merging narrows `event.type === 'draw/generated'` to the payload type.

package/src/version.ts

@@ -7,4 +7,4 @@
  */
 
 /** Plugin version; must equal the `version` field in `package.json`. */
-export const PLUGIN_VERSION = '0.1.0'
+export const PLUGIN_VERSION = '0.1.2'