zcode-workbuddy-connect 0.0.0-stage → 1.0.0

package/docs/adr/0004-workbuddy-56-at-rest-credentials.md

@@ -0,0 +1,111 @@
+# ADR 0004 — Read a 5.6 sign-in by opening its at-rest envelopes
+
+Status: accepted (2026-09-25)
+
+## Context
+
+Since WorkBuddy 5.6 the desktop app no longer writes its sign-in as plain JSON.
+`auth.accessToken` and `auth.refreshToken` arrive as `{$wbEncrypted:1, envelope}`
+wrappers (`buildPolicy: "fields"`, on by default), each sealed with AES-256-GCM
+under a per-machine at-rest key. The plugin's credential path had been "read the
+file, parse the JSON, take the token", so on a current install it read two
+objects where it expected two strings — and the desktop file is the identity
+authority for the region, so a file the plugin cannot read is a signed-out state
+it cannot even explain.
+
+Nothing in the plugin's own process can open those envelopes. The at-rest key is
+delivered by the app's Electron-modified runtime through a private binding,
+`process._linkedBinding("electron_browser_workbuddy_storage").loggerGet()`, which
+returns `{version:1, atRestSecretKey}` — and that binding does not exist in
+ZCode's stock Node, where this plugin runs. The format and its failure modes were
+established from the app bundle and from upstream's issue reports (#39/#40 in
+`corrinehu/dsh-workbuddy-connect`); the authenticated-context AAD is a
+transcription of the app's own `buildAuthenticatedContextAad`.
+
+## Decision
+
+**Classify the document before parsing it.** `classifyDesktopAuthDocument`
+returns `absent`, `plaintext`, `encrypted` or `unrecognized`. A plaintext
+document keeps going through the parser it always did, so the ordinary path is
+unchanged. An encrypted document is *opened*, never skipped. An unrecognized one
+fails loudly and names the path, because the desktop file outranks the
+plugin-owned copy wherever it exists: quietly preferring the copy would let a
+stale account sign the user in. An empty file is the one case that falls through
+to the next candidate — an empty file cannot be authoritative about anything.
+
+**Open envelopes by running the app's own binary once as Node.** The helper is
+spawned as `<Electron> -e` with the one-line binding read and
+`ELECTRON_RUN_AS_NODE=1`, and only the payload reaches stdout. The plugin never
+copies the app's runtime, never patches it, and never starts it as a GUI.
+
+**Derive the protector key with `sha256(atRestSecretKey, utf8)`**, cache it in
+memory only, single-flight, and key that cache by the derived key's own id
+(`sha256` of the key, first 16 hex characters). An envelope naming a different id
+re-resolves the payload once: an app update or a fresh sign-in reseals the file,
+and a stale key must never be used against a fresh envelope.
+
+**Transcribe the AAD instead of guessing at it.** The `WB-AAD\0` prefix, the
+`WBEV1` framing under `sym-v1`, the suite number, the length-prefixed key id and
+the trailing context bytes are all constants of the app's own builder. Credential
+fields are always suite 1 under the field framing; the neighbouring framings
+(`WBEF1`/`WBER1`/`WBES1`) belong to other document kinds and are deliberately
+left unimplemented — opening a credential is not a place to guess at a format.
+
+**Auto-discover one product, on the platforms where it was verified.** The CN
+app gets a platform default on Windows and macOS, and on macOS a Spotlight search
+by bundle id that *proves* identity — a candidate declaring a different bundle id
+is excluded, several Spotlight rows for one bundle collapse via realpath, a row
+that is provably gone is skipped, and anything that could not be checked is
+reported as incomplete rather than as "the app is missing". More than one
+survivor is an error, not a coin toss. Everything else — Linux, and the
+international app off Windows — gets `WORKBUDDY_ELECTRON_BIN` only, and a missing
+binary there is reported as "not configured", never as "searched and failed".
+
+This is a **deliberate deviation from upstream**, which refuses static
+candidates. The refusal fits macOS, where a real discovery mechanism exists; it
+does not transfer to Windows, which has none, and where the only alternative to a
+static default is asking the user for an env var to run their own installed app.
+The two Windows defaults are the app's own install directories and were verified
+live.
+
+**Never let a secret out, and never let one into a log.** The payload, the key
+and the tokens are used in memory and written nowhere new. Error text carries
+sizes, key ids and exit codes only — deliberately not helper stdout or stderr,
+which can hold paths or crash dumps.
+
+## Consequences
+
+**Gained.** A current WorkBuddy install works with no configuration on Windows
+and macOS (CN). When it cannot work, the diagnosis is specific: a signed-out
+state carries a `reasonCode` (`encrypted-credential-unreadable`,
+`electron-binary-not-found`, `electron-binary-ambiguous`,
+`electron-binary-unavailable`, `electron-discovery-incomplete`,
+`electron-path-invalid`), and `doctor` prints the file's format, the binary the
+unlock would use, and whether that binary exists — all without spawning or
+decrypting anything for the report itself.
+
+**Cost.** The plugin executes a foreign binary. It is the app's own, from a path
+that names exactly one product, and only ever with `ELECTRON_RUN_AS_NODE=1`, so
+no GUI or app code path runs; but the capability is real, and it is bounded by
+refusing every location that has not been verified rather than by adding
+fallbacks.
+
+**Cost.** The desktop file can now be a hard failure where it used to be
+invisible: a sealed file this plugin cannot open reports "fix or remove the
+file" instead of silently falling back. That is intended — the alternative is
+signing the user in as whoever the plugin-owned copy last belonged to.
+
+## Alternatives rejected
+
+- **Read the token fields as opaque objects** (what a naive port does) — the
+  install is healthy and the plugin says signed-out. Useless.
+- **Reimplement the binding in ZCode's Node** — the key material is produced by
+  the app's modified runtime; there is nothing to reimplement outside it.
+- **Read a DPAPI/Keychain secret directly** — the at-rest key is not held by the
+  OS credential store; it is delivered through the app's binding.
+- **Search the filesystem for any WorkBuddy install** — executing an
+  unidentified binary is not something a credential reader should do on a guess.
+  Upstream's refusal is kept everywhere the layout has not been verified live.
+- **Copy the decrypted tokens into the plugin-owned store and be done** — that
+  copy exists for refresh continuity, not as a second authority, and putting the
+  token in a second place on disk buys nothing the envelope open does not.

package/docs/validate-provider-config.mjs

@@ -0,0 +1,203 @@
+/**
+ * Strict validator for ZCode's `provider_config.json`.
+ *
+ * ZCode parses this document with zod schemas compiled into its Electron
+ * bundle, and those schemas are `.strict()`: a single unrecognised key fails
+ * the WHOLE document, and the app's failure mode is to discard the entire
+ * personal provider set and start from an empty one — silently breaking every
+ * other provider the user had configured, with no error surfaced anywhere.
+ *
+ * That failure mode is why `setup` writes into a temp file and this validator
+ * runs before the write lands. It mirrors the shapes read out of
+ * `ZCode\resources\app.asar` -> `out/host/index.js`:
+ *
+ *   manualProviderModelRules[].config  (the `extractManualModelConfig` shape)
+ *     enabled?
+ *     properties   pick: contextWindow, supportsJsonSchemaOutput,
+ *                        supportsNativeWebSearch, supportsMidConversationSystem
+ *                  + inputFormat pick: supportsImage, supportsVideo, supportsPdf
+ *     optionSpecs  pick: reasoningLevel
+ *                  + maxOutputTokens pick: max   (map is NOT accepted here)
+ *
+ *   providerModelRules[].config  (the full base shape, sparse)
+ *     properties: requiresMfjsToolSchema, contextWindow,
+ *                 inputFormat{5 flags}, outputFormat,
+ *                 supportsToolCall, supportsJsonSchemaOutput,
+ *                 supportsNativeWebSearch, supportsMidConversationSystem
+ *     optionSpecs: reasoningLevel{values,map}, maxOutputTokens{max,map}
+ *
+ * Usage:  node docs/validate-provider-config.mjs [path]
+ * Exit 0 = valid, 1 = invalid (with the offending path printed).
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const path = process.argv[2] ?? join(homedir(), '.zcode', 'v2', 'provider_config.json')
+
+/** Keys accepted inside `providerModelRules[].config.properties`. */
+const PROPERTY_KEYS = new Set([
+  'requiresMfjsToolSchema', 'contextWindow',
+  'inputFormat', 'outputFormat',
+  'supportsToolCall', 'supportsJsonSchemaOutput',
+  'supportsNativeWebSearch', 'supportsMidConversationSystem',
+])
+const INPUT_FORMAT_KEYS = new Set(['supportsText', 'supportsImage', 'supportsVideo', 'supportsAudio', 'supportsPdf'])
+const OUTPUT_FORMAT_KEYS = new Set(['supportsText'])
+const OPTION_SPEC_KEYS = new Set(['reasoningLevel', 'maxOutputTokens'])
+const MAX_OUTPUT_TOKEN_KEYS = new Set(['max', 'map'])
+const REASONING_LEVEL_KEYS = new Set(['values', 'map'])
+
+/** The manual variant accepts only a subset of each shape. */
+const CONFIG_KEYS = new Set(['enabled', 'properties', 'optionSpecs'])
+const MANUAL_PROPERTY_KEYS = new Set([
+  'contextWindow', 'supportsJsonSchemaOutput',
+  'supportsNativeWebSearch', 'supportsMidConversationSystem', 'inputFormat',
+])
+const MANUAL_INPUT_FORMAT_KEYS = new Set(['supportsImage', 'supportsVideo', 'supportsPdf'])
+const MANUAL_OPTION_SPEC_KEYS = new Set(['reasoningLevel', 'maxOutputTokens'])
+const MANUAL_MAX_OUTPUT_TOKEN_KEYS = new Set(['max'])
+
+const RULE_KEYS = new Set(['modelId', 'providerId', 'config'])
+const PROVIDER_RULE_KEYS = new Set(['providerId', 'templateId', 'providerName', 'enabled', 'config'])
+const PROVIDER_CONFIG_KEYS = new Set([
+  'group', 'logo', 'access', 'api', 'builtinModelIds', 'personalModelIds', 'modelOrder', 'visibility',
+])
+const API_TYPES = new Set(['anthropic-messages', 'openai-chat-completions', 'openai-responses'])
+const MODEL_RULE_SETS = new Set([
+  'providerModelRules', 'manualProviderModelRules', 'modelRules', 'modelApiRules',
+  'providerSiteRules', 'templateModelRules', 'builtinProviderModelRules',
+])
+
+const problems = []
+const isObj = value => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function unknownKeys(obj, allowed, where) {
+  if (!isObj(obj)) return
+  for (const key of Object.keys(obj)) {
+    if (!allowed.has(key)) problems.push(`${where}: unrecognised key "${key}" (strict schema rejects the whole document)`)
+  }
+}
+
+function checkPositiveInt(value, where) {
+  if (value === undefined) return
+  if (!Number.isInteger(value) || value <= 0) {
+    problems.push(`${where}: must be a positive integer, got ${JSON.stringify(value)}`)
+  }
+}
+
+function walkConfig(config, where, { manual }) {
+  if (!isObj(config)) {
+    problems.push(`${where}: must be an object`)
+    return
+  }
+  unknownKeys(config, CONFIG_KEYS, where)
+  if (config['enabled'] !== undefined && typeof config['enabled'] !== 'boolean') {
+    problems.push(`${where}.enabled: must be boolean`)
+  }
+
+  const properties = config['properties']
+  if (properties !== undefined) {
+    unknownKeys(properties, manual ? MANUAL_PROPERTY_KEYS : PROPERTY_KEYS, `${where}.properties`)
+    checkPositiveInt(properties['contextWindow'], `${where}.properties.contextWindow`)
+    if (properties['inputFormat'] !== undefined) {
+      unknownKeys(properties['inputFormat'], manual ? MANUAL_INPUT_FORMAT_KEYS : INPUT_FORMAT_KEYS, `${where}.properties.inputFormat`)
+    }
+    if (properties['outputFormat'] !== undefined) {
+      unknownKeys(properties['outputFormat'], OUTPUT_FORMAT_KEYS, `${where}.properties.outputFormat`)
+    }
+  }
+
+  const specs = config['optionSpecs']
+  if (specs === undefined) return
+  unknownKeys(specs, manual ? MANUAL_OPTION_SPEC_KEYS : OPTION_SPEC_KEYS, `${where}.optionSpecs`)
+  const maxOutput = specs['maxOutputTokens']
+  if (maxOutput !== undefined) {
+    unknownKeys(maxOutput, manual ? MANUAL_MAX_OUTPUT_TOKEN_KEYS : MAX_OUTPUT_TOKEN_KEYS, `${where}.optionSpecs.maxOutputTokens`)
+    checkPositiveInt(maxOutput['max'], `${where}.optionSpecs.maxOutputTokens.max`)
+  }
+  const reasoning = specs['reasoningLevel']
+  if (reasoning !== undefined) {
+    unknownKeys(reasoning, REASONING_LEVEL_KEYS, `${where}.optionSpecs.reasoningLevel`)
+  }
+}
+
+let document
+try {
+  document = JSON.parse(readFileSync(path, 'utf8'))
+} catch (error) {
+  console.error(`INVALID — ${path}`)
+  console.error(`  - not readable as JSON: ${String(error)}`)
+  process.exit(1)
+}
+
+if (document['schemaVersion'] !== 1) {
+  problems.push(`schemaVersion: must be 1, got ${JSON.stringify(document['schemaVersion'])}`)
+}
+const config = document['config']
+if (!isObj(config)) {
+  console.error(`INVALID — ${path}`)
+  console.error('  - missing config object')
+  process.exit(1)
+}
+unknownKeys(config, new Set(['providerOrder', 'providerConfigRules', 'modelConfigRules', 'defaultModelSelection']), 'config')
+
+const modelConfigRules = config['modelConfigRules']
+if (modelConfigRules !== undefined) {
+  unknownKeys(modelConfigRules, MODEL_RULE_SETS, 'config.modelConfigRules')
+  for (const setName of ['providerModelRules', 'manualProviderModelRules']) {
+    const rules = modelConfigRules[setName]
+    if (rules === undefined) continue
+    if (!Array.isArray(rules)) {
+      problems.push(`config.modelConfigRules.${setName}: must be an array`)
+      continue
+    }
+    rules.forEach((rule, index) => {
+      const where = `config.modelConfigRules.${setName}[${index}]`
+      unknownKeys(rule, RULE_KEYS, where)
+      if (typeof rule?.['providerId'] !== 'string') problems.push(`${where}.providerId: required string`)
+      if (typeof rule?.['modelId'] !== 'string') problems.push(`${where}.modelId: required string`)
+      if (rule?.['config'] !== undefined) {
+        walkConfig(rule['config'], `${where}.config`, { manual: setName === 'manualProviderModelRules' })
+      }
+    })
+  }
+}
+
+const providerRules = config['providerConfigRules']?.['providerRules']
+if (providerRules !== undefined) {
+  if (!Array.isArray(providerRules)) {
+    problems.push('config.providerConfigRules.providerRules: must be an array')
+  } else {
+    providerRules.forEach((rule, index) => {
+      const where = `config.providerConfigRules.providerRules[${index}]`
+      unknownKeys(rule, PROVIDER_RULE_KEYS, where)
+      const ruleConfig = rule?.['config']
+      if (ruleConfig === undefined) return
+      unknownKeys(ruleConfig, PROVIDER_CONFIG_KEYS, `${where}.config`)
+      const ids = ruleConfig['personalModelIds']
+      if (ids !== undefined && ids !== null && !Array.isArray(ids)) {
+        problems.push(`${where}.config.personalModelIds: must be an array or null`)
+      }
+      const modelOrder = ruleConfig['modelOrder']
+      if (modelOrder !== undefined && modelOrder !== null && !Array.isArray(modelOrder)) {
+        problems.push(`${where}.config.modelOrder: must be an array or null`)
+      }
+      const api = ruleConfig['api']
+      if (isObj(api) && typeof api['type'] === 'string' && !API_TYPES.has(api['type'])) {
+        problems.push(`${where}.config.api.type: unsupported "${api['type']}"`)
+      }
+    })
+  }
+}
+
+if (problems.length === 0) {
+  const ruleCount = (modelConfigRules?.['providerModelRules']?.length ?? 0)
+    + (modelConfigRules?.['manualProviderModelRules']?.length ?? 0)
+  console.log(`VALID — ${path}`)
+  console.log(`  providers: ${Array.isArray(providerRules) ? providerRules.length : 0}, model rules: ${ruleCount}`)
+  process.exit(0)
+}
+console.error(`INVALID — ${path}`)
+for (const problem of problems) console.error(`  - ${problem}`)
+process.exit(1)

package/docs/verify-endpoint.mjs

@@ -0,0 +1,162 @@
+/**
+ * End-to-end verification of the zcode-workbuddy-connect endpoint.
+ *
+ * Run against a live endpoint:   node docs/verify-endpoint.mjs
+ * Requires the service to be up on :39271 (node bin/cli.mjs serve).
+ *
+ * Covers the four failure modes that mattered during the port: stream
+ * termination (a missing [DONE] hangs the client), tool-call reassembly (the
+ * upstream sends id and name only on the first fragment), non-streaming
+ * fallback (the upstream rejects stream:false), and schema-valid JSON.
+ */
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const stateDir = process.env['ZCODE_WORKBUDDY_CONNECT_HOME'] ?? join(homedir(), '.zcode-workbuddy-connect')
+const token = JSON.parse(await readFile(join(stateDir, 'endpoint.json'), 'utf8')).token
+const BASE = process.env['ZCODE_WORKBUDDY_CONNECT_BASE'] ?? 'http://127.0.0.1:39271/v1'
+const H = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }
+
+let pass = 0, fail = 0
+const check = (name, ok, detail = '') => {
+  console.log(`[${ok ? 'PASS' : 'FAIL'}] ${name}${detail ? ' — ' + detail : ''}`)
+  ok ? pass++ : fail++
+}
+
+/** POST and consume the SSE stream, reporting the first-byte latency. */
+async function stream(body) {
+  const t0 = Date.now()
+  const r = await fetch(`${BASE}/chat/completions`, { method: 'POST', headers: H, body: JSON.stringify(body) })
+  if (r.status !== 200) {
+    const text = await r.text()
+    return { status: r.status, error: text.slice(0, 300) }
+  }
+  const reader = r.body.getReader()
+  const dec = new TextDecoder()
+  let firstByte = null, sawDone = false, sawHeartbeat = false
+  let text = '', reasoning = '', finish = null
+  const calls = []
+  let usage = null
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    if (firstByte === null) firstByte = Date.now() - t0
+    for (const line of dec.decode(value, { stream: true }).split('\n')) {
+      const t = line.trim()
+      if (t.startsWith(':') && t.toLowerCase().includes('heartbeat')) { sawHeartbeat = true; continue }
+      if (!t.startsWith('data:')) continue
+      const p = t.slice(5).trim()
+      if (p === '') continue
+      if (p === '[DONE]') { sawDone = true; continue }
+      let j; try { j = JSON.parse(p) } catch { continue }
+      if (j.usage) usage = j.usage
+      const ch = j.choices?.[0]
+      if (!ch) continue
+      if (ch.finish_reason) finish = ch.finish_reason
+      const d = ch.delta
+      if (!d) continue
+      if (typeof d.content === 'string') text += d.content
+      if (typeof d.reasoning_content === 'string') reasoning += d.reasoning_content
+      if (Array.isArray(d.tool_calls)) calls.push(...d.tool_calls)
+    }
+  }
+  // Merge tool-call fragments by index, exactly as a real OpenAI client does:
+  // id and name arrive on the first fragment, arguments accumulate after.
+  const byIndex = new Map()
+  for (const c of calls) {
+    const i = typeof c.index === 'number' ? c.index : 0
+    const acc = byIndex.get(i) ?? { id: '', name: '', arguments: '' }
+    if (typeof c.id === 'string' && c.id !== '') acc.id = c.id
+    const fn = c.function
+    if (fn) {
+      if (typeof fn.name === 'string' && fn.name !== '') acc.name = fn.name
+      if (typeof fn.arguments === 'string') acc.arguments += fn.arguments
+    }
+    byIndex.set(i, acc)
+  }
+  return {
+    status: 200, firstByte, total: Date.now() - t0, sawDone, sawHeartbeat, text, reasoning, finish, usage,
+    rawChunks: calls.length,
+    calls: [...byIndex.entries()].sort((a, b) => a[0] - b[0]).map(([, v]) => ({ id: v.id, function: { name: v.name, arguments: v.arguments } })),
+  }
+}
+
+const TOOLS = [{
+  type: 'function',
+  function: {
+    name: 'get_weather',
+    description: 'Get the current weather for a city',
+    parameters: { type: 'object', properties: { city: { type: 'string' }, unit: { type: 'string' } }, required: ['city'] },
+  },
+}]
+
+console.log('=== 1. streaming text ===')
+{
+  const r = await stream({ model: 'hy3', stream: true, messages: [{ role: 'user', content: 'Reply with exactly: PONG' }] })
+  check('HTTP 200', r.status === 200, r.status === 200 ? `firstByte ${r.firstByte}ms, total ${r.total}ms` : r.error)
+  check('terminated with [DONE]', r.sawDone === true)
+  check('content received', (r.text ?? '').trim().length > 0, JSON.stringify((r.text ?? '').trim().slice(0, 40)))
+  check('finish_reason stop', r.finish === 'stop', JSON.stringify(r.finish))
+  check('usage reported', r.usage != null, `${r.usage?.total_tokens} tokens`)
+}
+
+console.log('\n=== 2. streaming tool call (id + name must survive) ===')
+{
+  const r = await stream({
+    model: 'hy3', stream: true, tool_choice: 'get_weather', tools: TOOLS,
+    messages: [
+      { role: 'system', content: 'You must call the provided tool.' },
+      { role: 'user', content: 'What is the weather in Shanghai in celsius?' },
+    ],
+  })
+  check('HTTP 200', r.status === 200, r.status === 200 ? `firstByte ${r.firstByte}ms` : r.error)
+  check('finish_reason is tool_calls', r.finish === 'tool_calls', JSON.stringify(r.finish))
+  check('exactly one assembled call', r.calls.length === 1, `${r.calls.length} call(s) from ${r.rawChunks} chunk(s)`)
+  const c = r.calls[0]
+  check('call has an upstream id', typeof c?.id === 'string' && c.id.length > 0, JSON.stringify(c?.id))
+  check('call has the function name', c?.function?.name === 'get_weather', JSON.stringify(c?.function?.name))
+  let args = null
+  try { args = JSON.parse(c?.function?.arguments ?? '') } catch {}
+  check('arguments are complete JSON', args !== null, c?.function?.arguments)
+  check('arguments carry the city', args?.city === 'Shanghai', JSON.stringify(args))
+}
+
+console.log('\n=== 3. non-streaming ===')
+{
+  const r = await fetch(`${BASE}/chat/completions`, {
+    method: 'POST', headers: H,
+    body: JSON.stringify({ model: 'hy3', stream: false, messages: [{ role: 'user', content: 'Reply with exactly: JSONOK' }] }),
+  })
+  const j = await r.json()
+  check('HTTP 200', r.status === 200, r.status === 200 ? '' : JSON.stringify(j).slice(0, 200))
+  check('object is chat.completion', j.object === 'chat.completion', j.object)
+  check('message content present', typeof j.choices?.[0]?.message?.content === 'string' && j.choices[0].message.content.trim().length > 0,
+    JSON.stringify(j.choices?.[0]?.message?.content?.trim()?.slice(0, 30)))
+  check('usage reported', j.usage != null, `${j.usage?.total_tokens} tokens`)
+}
+
+console.log('\n=== 4. non-streaming tool call ===')
+{
+  const r = await fetch(`${BASE}/chat/completions`, {
+    method: 'POST', headers: H,
+    body: JSON.stringify({
+      model: 'hy3', stream: false, tool_choice: 'get_weather', tools: TOOLS,
+      messages: [
+        { role: 'system', content: 'You must call the provided tool.' },
+        { role: 'user', content: 'What is the weather in Beijing?' },
+      ],
+    }),
+  })
+  const j = await r.json()
+  const tc = j.choices?.[0]?.message?.tool_calls
+  check('tool_calls present', Array.isArray(tc) && tc.length === 1, `${tc?.length}`)
+  check('tool name correct', tc?.[0]?.function?.name === 'get_weather', JSON.stringify(tc?.[0]?.function?.name))
+  check('finish_reason tool_calls', j.choices?.[0]?.finish_reason === 'tool_calls', j.choices?.[0]?.finish_reason)
+  let args = null
+  try { args = JSON.parse(tc?.[0]?.function?.arguments ?? '') } catch {}
+  check('arguments parse', args !== null, JSON.stringify(args))
+}
+
+console.log(`\n${pass} passed, ${fail} failed`)
+process.exitCode = fail === 0 ? 0 : 1

package/hooks/service-ensure.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook: make sure the local WorkBuddy endpoint is running.
+ *
+ * Contract with the rest of the plugin: the provider entry in ZCode's
+ * provider_config.json points at a fixed loopback port, so something has to be
+ * listening there before the first message. This hook starts it if it is not
+ * already up.
+ *
+ * It is deliberately *self-verifying*: spawning a detached process is the part
+ * most likely to be refused (a locked-down or sandboxed host can deny it
+ * outright), so the hook never reports success on the strength of the spawn
+ * call alone. It probes the endpoint afterwards and says plainly what happened,
+ * because a hook that claims the service is up while it is not would turn a
+ * visible "start it yourself" into a confusing connection error later.
+ *
+ * Never fails the session: every path exits 0.
+ *
+ * @module zcode-workbuddy-connect/hooks/service-ensure
+ */
+
+import { spawn } from 'node:child_process'
+import { readFile, appendFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const cliPath = join(pluginRoot, 'bin', 'cli.mjs')
+const stateDir = process.env['ZCODE_WORKBUDDY_CONNECT_HOME'] ?? join(process.env['USERPROFILE'] ?? '.', '.zcode-workbuddy-connect')
+const endpointPath = join(stateDir, 'endpoint.json')
+const logPath = join(stateDir, 'service.log')
+const DEFAULT_PORT = 39271
+
+async function log(line) {
+  try {
+    await mkdir(stateDir, { recursive: true })
+    await appendFile(logPath, `${new Date().toISOString()} ${line}\n`)
+  } catch {
+    // Diagnostics are best-effort; never let logging break the hook.
+  }
+}
+
+async function readEndpoint() {
+  try {
+    const document = JSON.parse(await readFile(endpointPath, 'utf8'))
+    const token = typeof document['token'] === 'string' ? document['token'] : ''
+    const port = typeof document['port'] === 'number' && document['port'] > 0 ? document['port'] : DEFAULT_PORT
+    return { token, port }
+  } catch {
+    return { token: '', port: DEFAULT_PORT }
+  }
+}
+
+/** Probe the endpoint; true only when it answers healthily. */
+async function healthy(port, token, timeoutMs = 2500) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/healthz`, {
+      headers: token === '' ? {} : { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!response.ok) return false
+    const body = await response.json()
+    return body?.['ok'] === true
+  } catch {
+    return false
+  }
+}
+
+async function waitForHealth(port, token, attempts = 20) {
+  for (let i = 0; i < attempts; i += 1) {
+    if (await healthy(port, token)) return true
+    await new Promise(resolve => setTimeout(resolve, 500))
+  }
+  return false
+}
+
+/** Is a process already bound to the port (someone else's, or a stale child)? */
+function spawnDetached(port) {
+  // `windowsHide` plus `stdio: 'ignore'` is the whole point: the endpoint must
+  // not flash a console window on the user's desktop every session.
+  const child = spawn(process.execPath, [cliPath, 'serve', '--port', String(port)], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    cwd: pluginRoot,
+  })
+  child.unref()
+  return child.pid
+}
+
+async function main() {
+  if (!existsSync(cliPath)) {
+    await log(`cli not found at ${cliPath}; skipping`)
+    return
+  }
+  const { token, port } = await readEndpoint()
+
+  if (await healthy(port, token)) {
+    await log(`endpoint already healthy on :${port}`)
+    return
+  }
+
+  let pid
+  try {
+    pid = spawnDetached(port)
+    await log(`spawned detached pid ${pid} on :${port}`)
+  } catch (error) {
+    await log(`spawn refused: ${String(error)}`)
+  }
+
+  if (await waitForHealth(port, token)) {
+    await log(`endpoint healthy on :${port}${pid === undefined ? '' : ` (pid ${pid})`}`)
+    return
+  }
+
+  // The endpoint is not up and the hook could not bring it up. Say so, with the
+  // one command that fixes it, rather than leaving the failure to surface as an
+  // unexplained connection error on the first message.
+  await log(`endpoint NOT healthy on :${port} after spawn attempt`)
+  console.log(
+    `[zcode-workbuddy-connect] The local endpoint is not running on port ${port}.`
+    + ' Its models will fail until it is started. Start it in a terminal with:\n'
+    + `  node "${cliPath}" serve --port ${port}\n`
+    + `Diagnostics: node "${cliPath}" doctor`,
+  )
+}
+
+main().catch(async error => {
+  await log(`hook error: ${String(error)}`)
+}).finally(() => {
+  process.exit(0)
+})

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "zcode-workbuddy-connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Expose WorkBuddy desktop-app models (CN) through a loopback OpenAI-compatible endpoint, for use as a model provider in ZCode or any OpenAI-compatible client.",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "xiao-hans"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiao-hans/zcode-ai-connect.git",
+    "directory": "zcode-workbuddy-connect"
+  },
+  "homepage": "https://github.com/xiao-hans/zcode-ai-connect/tree/main/zcode-workbuddy-connect#readme",
+  "bugs": {
+    "url": "https://github.com/xiao-hans/zcode-ai-connect/issues"
+  },
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "bin": {
+    "zcode-workbuddy-connect": "bin/cli.mjs"
+  },
+  "files": [
+    ".zcode-plugin",
+    "bin",
+    "src",
+    "hooks",
+    "skills",
+    "docs",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md",
+    "!src/server.js.bak-order"
+  ],
+  "exports": {
+    ".": "./src/upstream.js",
+    "./server": "./src/server.js",
+    "./auth": "./src/auth.js",
+    "./catalog": "./src/catalog.js",
+    "./desktop-credential-protection": "./src/desktop-credential-protection.js"
+  },
+  "scripts": {
+    "serve": "node bin/cli.mjs serve",
+    "status": "node bin/cli.mjs status",
+    "doctor": "node bin/cli.mjs doctor",
+    "test": "node --test"
+  },
+  "dependencies": {},
+  "keywords": [
+    "workbuddy",
+    "codebuddy",
+    "openai-compatible",
+    "provider",
+    "zcode"
+  ]
+}