dsh-artcraft-plugin-soundcraft 0.1.3 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-artcraft-plugin-soundcraft",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive SoundCraft (audio production) headlessly through its own CLI and MCP server.",
@@ -43,4 +43,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/kit/catalog.js

@@ -92,9 +92,44 @@ export function parseCatalog(stdout        , json         )                 {
       // Fall through to the table parser: a CLI may ignore an unknown --json.
     }
   }
+  const emDash = parseEmDash(text)
+  if (emDash.length > 0) return emDash
   return parseTable(text)
 }
 
+/**
+ * Parse an `id — Label: {params}` catalogue (DeckCraft 0.14+).
+ *
+ * One command per line, single-spaced, with an em dash between the id and its
+ * label. `: {…}` introduces the parameter grammar and ` → …` describes what the
+ * command answers, which is not part of the grammar.
+ * @param text - raw `commands` output.
+ * @returns every command whose line has the `id — label` shape.
+ */
+export function parseEmDash(text        )                 {
+  const out                 = []
+  for (const raw of text.split('\n')) {
+    const line = raw.trimEnd()
+    if (line.length === 0 || line.startsWith('#')) continue
+    const match = /^([\w.-]+)\s+—\s+(.*)$/.exec(line)
+    if (match === null) continue
+    const id = match[1]
+    const rest = match[2]
+    const returnIndex = rest.indexOf(' → ')
+    const beforeReturn = returnIndex === -1 ? rest : rest.slice(0, returnIndex)
+    const brace = beforeReturn.indexOf(': {')
+    const label = brace === -1 ? beforeReturn.trim() : beforeReturn.slice(0, brace).trim()
+    const params = brace === -1 ? undefined : beforeReturn.slice(brace + 2).trim()
+    out.push({
+      id,
+      ...label.length > 0 ? { label } : {},
+      ...params !== undefined && params.length > 0 ? { params } : {},
+      group: groupOf(id),
+    })
+  }
+  return out
+}
+
 /**
  * Parse a craft's fixed-column `commands` table.
  *
@@ -111,7 +146,14 @@ export function parseTable(text        )                 {
   const flush = ()       => {
     if (current === undefined) return
     const { id, columns } = current
-    const rest = columns.join(' ').trim()
+    let rest = columns.join(' ').trim()
+    // Some tables end with the grammar as its own column (`{name?, color?}`),
+    // with no `params:` label; take the last column when it is only an object.
+    let columnParams
+    if (columns.length > 1 && /^\{.*\}$/.test(columns[columns.length - 1].trim())) {
+      columnParams = columns[columns.length - 1].trim()
+      rest = columns.slice(0, -1).join(' ').trim()
+    }
     const paramsMatch = /\bparams:\s*(\{.*)$/.exec(rest)
     const labelPart = paramsMatch === null ? rest : rest.slice(0, paramsMatch.index).trim()
     // Trailing `label  [Shortcut]` and an interleaved menu column.
@@ -120,7 +162,9 @@ export function parseTable(text        )                 {
     out.push({
       id,
       ...label.length > 0 ? { label } : {},
-      ...paramsMatch !== null ? { params: paramsMatch[1].replace(/\s+/g, ' ').trim() } : {},
+      ...columnParams !== undefined
+        ? { params: columnParams.replace(/\s+/g, ' ') }
+        : paramsMatch !== null ? { params: paramsMatch[1].replace(/\s+/g, ' ').trim() } : {},
       ...shortcutMatch !== null ? { shortcut: shortcutMatch[1] } : {},
       group: groupOf(id),
     })
@@ -136,7 +180,8 @@ export function parseTable(text        )                 {
     }
     flush()
     const columns = raw.trimEnd().split(/\s{2,}/).map(part => part.trim()).filter(part => part.length > 0)
-    const id = columns[0] ?? ''
+    // Rust CLIs mark undoable commands with a trailing `*`; it is not the id.
+    const id = (columns[0] ?? '').replace(/\*$/, '')
     if (id.length === 0 || /\s/.test(id) || !/^[\w.-]+$/.test(id)) continue
     current = { id, columns: columns.slice(1) }
   }

package/src/kit/mcp.js

@@ -14,6 +14,8 @@
 
 import { spawn } from 'node:child_process'
                                                                         
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
 import { killTree } from './exec.js'
                                                            
 
@@ -31,6 +33,33 @@ import { killTree } from './exec.js'
                        
  
 
+/** Extensions for the image types an MCP tool can return. */
+const IMAGE_EXTENSIONS                         = {
+  'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif', 'image/svg+xml': 'svg',
+}
+
+/**
+ * Write one base64 image from a tool result to disk.
+ * @param data - base64 payload.
+ * @param mimeType - media type the server declared.
+ * @param dir - directory to write into.
+ * @param craft - craft id, used in the file name.
+ * @param tool - tool name, used in the file name.
+ * @returns the absolute path, or `undefined` when the payload cannot be written.
+ */
+function saveImage(data        , mimeType                    , dir        , craft        , tool        )                     {
+  try {
+    const extension = IMAGE_EXTENSIONS[mimeType ?? ''] ?? 'png'
+    const safeTool = tool.replace(/[^\w.-]+/g, '-')
+    mkdirSync(dir, { recursive: true })
+    const file = join(dir, `${craft}-${safeTool}-${Date.now()}.${extension}`)
+    writeFileSync(file, Buffer.from(data, 'base64'))
+    return file
+  } catch {
+    return undefined
+  }
+}
+
 /** Default MCP protocol revision; servers negotiate down if they need to. */
 const PROTOCOL_VERSION = '2024-11-05'
 
@@ -52,6 +81,8 @@ export class CraftMcpClient {
   #idleTimer                            
   #handshake                                                          
   #tools                       
+  /** Last stderr lines, so a failed attach can say why the app refused. */
+  #stderrTail           = []
   #closed = false
 
   constructor(profile              , binary             , args                    = []) {
@@ -91,17 +122,26 @@ export class CraftMcpClient {
     child.stdout.on('data', (chunk        ) => { this.#onData(chunk) })
     child.stderr.setEncoding('utf8')
     // Craft servers announce themselves on stderr; it is not an error stream.
+    // The tail is kept so a refused attach can repeat the app's own reason
+    // ("no control token", "cannot connect to 127.0.0.1:7979") instead of a
+    // bare "server exited".
     child.stderr.on('data', (chunk        ) => {
       const text = chunk.trim()
-      if (text.length > 0 && process.env.DSH_ARTCRAFT_TRACE !== undefined) {
+      if (text.length === 0) return
+      for (const line of text.split('\n')) {
+        this.#stderrTail.push(line.trim())
+        if (this.#stderrTail.length > 8) this.#stderrTail.shift()
+      }
+      if (process.env.DSH_ARTCRAFT_TRACE !== undefined) {
         process.stderr.write(`[${this.#profile.id} mcp] ${text}\n`)
       }
     })
     child.on('exit', () => {
       this.#child = undefined
+      const reason = this.#stderrTail.filter(line => line.length > 0).slice(-2).join(' ')
       for (const [, pending] of this.#pending) {
         clearTimeout(pending.timer)
-        pending.reject(new Error(`${this.#profile.product}: MCP server exited`))
+        pending.reject(new Error(`${this.#profile.product}: MCP server exited${reason.length > 0 ? ` (${reason})` : ''}`))
       }
       this.#pending.clear()
     })
@@ -134,22 +174,60 @@ export class CraftMcpClient {
 
   /**
    * Call one tool.
+   *
+   * Image results — a render, a screenshot, a page thumbnail — are written to
+   * `artifactsDir` and referenced by path instead of being dropped: the caller
+   * can then look at them with `read_image`, which is the only way an agent
+   * verifies what it drew.
    * @param name - tool name as declared by the server.
    * @param args - the tool's JSON arguments.
-   * @returns the concatenated text content of the result.
+   * @param artifactsDir - directory for returned images, when one is configured.
+   * @returns the text content, with any images saved and named by path.
    */
-  async callTool(name        , args                         )                  {
+  async callTool(name        , args                         , artifactsDir         )                  {
     const result = await this.#request('tools/call', { name, arguments: args })     
-                                                  
+                                                                                    
                        
      
-    const text = (result.content ?? [])
-      .map(block => (block.type === 'text' ? block.text ?? '' : `[${block.type ?? 'unknown'} content]`))
-      .join('\n')
-      .trim()
+    const parts           = []
+    for (const block of result.content ?? []) {
+      if (block.type === 'text') {
+        parts.push(block.text ?? '')
+        continue
+      }
+      if (block.type === 'image' && typeof block.data === 'string' && artifactsDir !== undefined) {
+        const saved = saveImage(block.data, block.mimeType, artifactsDir, this.#profile.id, name)
+        parts.push(saved === undefined
+          ? '[image content]'
+          : `[image] ${saved}\nUse read_image on that path to look at it.`)
+        continue
+      }
+      parts.push(`[${block.type ?? 'unknown'} content]`)
+    }
+    const text = parts.join('\n').trim()
     return `${text.length > 0 ? text : '(no content)'}${result.isError === true ? '\n[mcp: tool reported an error]' : ''}`
   }
 
+  /** List the resources the server advertises (documents, command catalogues). */
+  async listResources()                                                                   {
+    try {
+      const result = await this.#request('resources/list', {})                                                                           
+      return Array.isArray(result.resources) ? result.resources : []
+    } catch {
+      return []
+    }
+  }
+
+  /** List the prompts the server advertises (curated multi-step workflows). */
+  async listPrompts()                                                     {
+    try {
+      const result = await this.#request('prompts/list', {})                                                           
+      return Array.isArray(result.prompts) ? result.prompts : []
+    } catch {
+      return []
+    }
+  }
+
   /** Terminate the server process now. */
   close()       {
     this.#closed = true

package/src/kit/profiles.mjs

@@ -54,6 +54,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'hostPort' },
   },
   {
     id: 'gridcraft',
@@ -80,6 +81,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'soundcraft',
@@ -107,6 +109,7 @@ export const CRAFT_PROFILES = [
     describeArgs: ['describe'],
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'deckcraft',
@@ -133,6 +136,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'wordcraft',
@@ -158,6 +162,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'hostPort' },
   },
   {
     id: 'photocraft',
@@ -186,6 +191,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'hostPort' },
   },
   {
     id: 'lightcraft',
@@ -272,6 +278,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'hostPort' },
   },
   {
     id: 'effectcraft',
@@ -297,6 +304,7 @@ export const CRAFT_PROFILES = [
     catalogJson: false,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'port' },
   },
   {
     id: 'filmcraft',
@@ -334,6 +342,7 @@ export const CRAFT_PROFILES = [
     describeArgs: ['describe'],
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'hostPort' },
   },
   {
     id: 'designcraft',
@@ -358,6 +367,66 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
+  },
+  {
+    id: 'figcraft',
+    product: 'FigCraft',
+    bin: 'figcraft-cli',
+    envVar: 'FIGCRAFT_CLI',
+    searchDirs: [CRAFTS_BIN_DIR],
+    extensions: ['.figcraft', '.penpot', '.fig', '.sketch', '.svg'],
+    blurb: 'Interface design and prototyping (Figma-style): frames, components, auto layout, variables, prototyping and code export.',
+    run: {
+      verb: 'run',
+      inputMode: 'flag',
+      inFlag: '--in',
+      sampleFlag: '',
+      cmdFlag: '',
+      cmdSeparator: ' ',
+      // `run script.json` takes a generated script, one step per command.
+      scriptFile: { encoding: 'json-array', commandKey: 'command', paramsKey: 'params', inputFlag: '--in', saveFlag: '--out' },
+      saveFlag: '--out',
+    },
+    reads: [
+      { name: 'inspect', verb: 'info', summary: 'Summarize a design file: pages, node counts, top-level frames, style and variable counts.' },
+      { name: 'convert', verb: 'convert', summary: 'Convert a design file between .figcraft, .json, .svg, .png, .pdf and more.' },
+    ],
+    catalogJson: true,
+    catalogArgs: ['commands', '--json'],
+    mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--attach', format: 'port' },
+  },
+  {
+    id: 'texturecraft',
+    product: 'TextureCraft',
+    bin: 'texturecraft-cli',
+    envVar: 'TEXTURECRAFT_CLI',
+    searchDirs: [CRAFTS_BIN_DIR],
+    extensions: ['.tcraft'],
+    blurb: '3D texture painting: texture sets and layers over a mesh, baking, material channels and PBR export.',
+    run: {
+      verb: 'batch',
+      inputMode: 'flag',
+      inFlag: '',
+      sampleFlag: '',
+      cmdFlag: '',
+      cmdSeparator: ' ',
+      // `batch script.json` carries `{ open, steps, save }` in one file.
+      scriptFile: { encoding: 'json-array', commandKey: 'id', paramsKey: 'params', batch: { openKey: 'open', stepsKey: 'steps', saveKey: 'save' } },
+      saveMode: 'script',
+      saveFlag: '',
+      // A project is required before any command, so a bare run makes one.
+      sampleCreate: { verb: 'new', args: ['builtin:crate'], extension: '.tcraft' },
+    },
+    reads: [
+      { name: 'inspect', verb: 'info', summary: 'Summarize a texture project: texture sets, layers, triangles, materials and the UV report.' },
+      { name: 'convert', verb: 'export', summary: 'Export textures from a project: presets, formats, padding and size.' },
+    ],
+    catalogJson: false,
+    catalogArgs: ['commands'],
+    mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'port' },
   },
 ]
 

package/src/kit/tools.js

@@ -39,6 +39,9 @@ function resolveSample(profile              , args                         )
   const requested = args.sample
   if (typeof requested === 'string' && requested.length > 0) return requested
   if (requested === true) {
+    // A craft that starts a new document by default, or creates one itself,
+    // has nothing to select; asking for the sample is a harmless no-op.
+    if (profile.run.sampleFlag.length === 0 && (profile.run.sampleCreate !== undefined || profile.run.scriptFile !== undefined)) return undefined
     if (profile.run.sampleFlag.length === 0) {
       throw new Error(
         `${profile.product} has no "new document" flag: pass \`input\` to open an existing document, `
@@ -154,23 +157,37 @@ function craftWorkDir(profile              )         {
  */
 export function createRuntime(profile              , packageRoot        , config                    = {})               {
   let catalogCache                                                                                                          
-  let mcpClient                            
+  const mcpClients = new Map                        ()
+  const artifacts = config.artifactsDir ?? join(tmpdir(), 'dsh-artcraft', profile.id)
   return {
+    artifactsDir()         {
+      return artifacts
+    },
     profile,
     config,
-    mcp()                             {
+    mcp(attach         )                             {
       if (config.enableMcp === false) return undefined
       if (profile.mcpArgs === undefined) return undefined
+      if (attach !== undefined && profile.mcpAttach === undefined) {
+        throw new Error(`${profile.product} cannot attach to a running app: its MCP server is headless only`)
+      }
       const binary = this.binary()
       if (binary === undefined) return undefined
+      const args = [...profile.mcpSessionArgs ?? []]
+      if (attach !== undefined && profile.mcpAttach !== undefined) {
+        args.push(profile.mcpAttach.flag, profile.mcpAttach.format === 'hostPort' ? `127.0.0.1:${attach}` : String(attach))
+      }
+      const key = String(attach ?? '')
+      const existing = mcpClients.get(key)
       // A CLI upgrade mid-session invalidates the running server.
-      if (mcpClient !== undefined && !mcpClient.running && mcpClient.cachedTools !== undefined) mcpClient = undefined
-      mcpClient ??= new CraftMcpClient(profile, binary, profile.mcpSessionArgs ?? [])
-      return mcpClient
+      if (existing !== undefined && !existing.running && existing.cachedTools !== undefined) mcpClients.delete(key)
+      const fresh = mcpClients.get(key) ?? new CraftMcpClient(profile, binary, args)
+      mcpClients.set(key, fresh)
+      return fresh
     },
     dispose()       {
-      mcpClient?.close()
-      mcpClient = undefined
+      for (const client of mcpClients.values()) client.close()
+      mcpClients.clear()
     },
     binary()                          {
       const found = discoverCraft(profile, config.path, packageRoot)
@@ -361,7 +378,7 @@ export function createToolSet(runtime              )               {
         description: 'Ordered commands to apply. Each is { "id": "cell.set", "json": { "cell": "A1", "input": "x" } }. An entry may also be a raw CLI string.',
         items: { type: 'json' },
       },
-      ...(profile.run.saveMode ?? 'flag') === 'flag'
+      ...(profile.run.saveMode ?? 'flag') !== 'none'
         ? { save: { type: 'string', description: `Path to write the edited document to (${profile.extensions.join('/')}).` } }
         : {},
       // `export` is always advertised when the craft can render one. Where the
@@ -410,6 +427,48 @@ export function createToolSet(runtime              )               {
       // Crafts whose headless entry point only accepts a script file get one
       // written for this call; the file names the same commands the inline
       // style would have carried.
+      // Crafts whose headless verb takes a generated script file instead of
+      // inline command flags: FigCraft's `run script.json` and TextureCraft's
+      // `batch script.json`. The kernel writes it, so the model still supplies
+      // an ordered list and never has to know the file format.
+      if (profile.run.scriptFile !== undefined) {
+        const spec = profile.run.scriptFile
+        const savePath = typeof args.save === 'string' ? args.save : undefined
+        let effectiveInput = input
+        if (effectiveInput === undefined && profile.run.sampleCreate !== undefined) {
+          const created = join(craftWorkDir(profile), `sample-${Date.now()}${profile.run.sampleCreate.extension}`)
+          mkdirSync(dirname(created), { recursive: true })
+          const createdResult = await runCraft({
+            profile, binary,
+            argv: [profile.run.sampleCreate.verb, ...profile.run.sampleCreate.args, created],
+            cwd: process.cwd(), timeoutMs,
+          })
+          if (!createdResult.ok) return renderRun(createdResult, profile)
+          effectiveInput = created
+        }
+        const steps = commands.map(command => ({ [spec.commandKey]: command.id, [spec.paramsKey]: command.json ?? {} }))
+        const scriptPath = join(craftWorkDir(profile), `run-${Date.now()}.${spec.encoding === 'jsonl' ? 'jsonl' : 'json'}`)
+        mkdirSync(dirname(scriptPath), { recursive: true })
+        const argv = [profile.run.verb]
+        let body
+        if (spec.batch !== undefined) {
+          body = {
+            ...effectiveInput !== undefined ? { [spec.batch.openKey]: effectiveInput } : {},
+            [spec.batch.stepsKey]: steps,
+            ...savePath !== undefined ? { [spec.batch.saveKey]: savePath } : {},
+          }
+          argv.push(scriptPath)
+        } else {
+          body = spec.encoding === 'jsonl' ? steps.map(step => JSON.stringify(step)).join('\n') + '\n' : steps
+          argv.push(scriptPath)
+          if (effectiveInput !== undefined && spec.inputFlag !== undefined) argv.push(spec.inputFlag, effectiveInput)
+          if (savePath !== undefined && spec.saveFlag !== undefined) argv.push(spec.saveFlag, savePath)
+        }
+        writeFileSync(scriptPath, typeof body === 'string' ? body : JSON.stringify(body, null, 2) + '\n')
+        const extra = Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : []
+        const scriptResult = await runCraft({ profile, binary, argv: [...argv, ...extra], cwd: process.cwd(), timeoutMs })
+        return renderRun(scriptResult, profile)
+      }
       if (profile.run.scriptFlag !== undefined) {
         const scriptPath = join(craftWorkDir(profile), `steps-${Date.now()}.json`)
         mkdirSync(dirname(scriptPath), { recursive: true })
@@ -621,13 +680,19 @@ export function createToolSet(runtime              )               {
       `${profile.product}'s own MCP server tools, each with a real JSON Schema. `
       + `These are the modelled operations (think \`write_range\`, \`render\`), whereas \`${profile.id}_run\` takes generic `
       + `command strings. Use this to discover them, then call one with \`${profile.id}_mcp_call\`. `
-      + `Search by name or description; omit \`search\` to list everything.`,
+      + `Search by name or description, page with \`offset\`/\`limit\` (large servers declare hundreds). `
+      + `Also lists the server's MCP resources and prompts when it has them.`,
     parameters: {
       search: { type: 'string', description: 'Case-insensitive filter over tool names and descriptions.' },
-      limit: { type: 'number', description: 'Maximum tools to describe (default 30).' },
+      limit: { type: 'number', description: 'Maximum tools to describe (default 30, at most 200).' },
+      offset: { type: 'number', description: 'Skip this many matches, to page through a long list.' },
+      ...profile.mcpAttach !== undefined
+        ? { attach: { type: 'number', description: `Control-channel port of a running ${profile.product} app, to drive the user's open document instead of a headless one.` } }
+        : {},
     },
     async execute(args) {
-      const client = runtime.mcp()
+      const attach = typeof args.attach === 'number' ? Math.floor(args.attach) : undefined
+      const client = runtime.mcp(attach)
       if (client === undefined) throw new Error(`${profile.product} has no MCP server configured`)
       await client.start(idleMs)
       const all = await client.listTools()
@@ -636,10 +701,11 @@ export function createToolSet(runtime              )               {
         ? all
         : all.filter(tool => tool.name.toLowerCase().includes(needle) || (tool.description ?? '').toLowerCase().includes(needle))
       const limit = typeof args.limit === 'number' && args.limit > 0 ? Math.min(Math.floor(args.limit), 200) : 30
-      const shown = matched.slice(0, limit)
+      const offset = typeof args.offset === 'number' && args.offset > 0 ? Math.floor(args.offset) : 0
+      const shown = matched.slice(offset, offset + limit)
       const lines = [
         `${profile.product} MCP server — ${matched.length} tool(s)${needle.length > 0 ? ` matching ${JSON.stringify(args.search)}` : ''}`
-        + (matched.length > shown.length ? `, showing ${shown.length}` : ''),
+        + (matched.length > offset + shown.length ? `, showing ${offset}–${offset + shown.length}` : ''),
         `server: ${client.describe()}`,
         '',
       ]
@@ -648,6 +714,17 @@ export function createToolSet(runtime              )               {
         lines.push(renderSchema(tool.inputSchema))
       }
       if (shown.length === 0) lines.push('(no matching tools)')
+      // Resources and prompts are the parts a tool-only bridge would miss: the
+      // document, the command catalogue, and curated multi-step workflows.
+      const [resources, prompts] = await Promise.all([client.listResources(), client.listPrompts()])
+      if (resources.length > 0) {
+        lines.push('', 'resources:')
+        for (const resource of resources) lines.push(`  ${resource.uri}${resource.name !== undefined ? ` — ${resource.name}` : ''}`)
+      }
+      if (prompts.length > 0) {
+        lines.push('', 'prompts:')
+        for (const prompt of prompts) lines.push(`  ${prompt.name}${prompt.description !== undefined ? ` — ${prompt.description}` : ''}`)
+      }
       return lines.join('\n')
     },
   }
@@ -658,13 +735,18 @@ export function createToolSet(runtime              )               {
     description:
       `Call one tool on ${profile.product}'s MCP server with JSON arguments. `
       + `Discover names and schemas with \`${profile.id}_mcp_tools\` first. `
-      + `Use this for modelled operations; use \`${profile.id}_run\` for arbitrary command ids.`,
+      + `Use this for modelled operations; use \`${profile.id}_run\` for arbitrary command ids. `
+      + `Images a tool returns (render, screenshot) are saved to disk and named by path — look at them with \`read_image\`.`,
     parameters: {
       tool: { type: 'string', required: true, description: 'MCP tool name, exactly as listed.' },
       arguments: { type: 'object', additionalProperties: true, description: "The tool's arguments object; see its schema in the listing." },
+      ...profile.mcpAttach !== undefined
+        ? { attach: { type: 'number', description: `Control-channel port of a running ${profile.product} app, to drive the user's open document instead of a headless one.` } }
+        : {},
     },
     async execute(args) {
-      const client = runtime.mcp()
+      const attach = typeof args.attach === 'number' ? Math.floor(args.attach) : undefined
+      const client = runtime.mcp(attach)
       if (client === undefined) throw new Error(`${profile.product} has no MCP server configured`)
       const name = String(args.tool ?? '').trim()
       if (name.length === 0) throw new Error('tool is required')
@@ -677,7 +759,7 @@ export function createToolSet(runtime              )               {
       }
       const raw = args.arguments
       const params = typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw                            : {}
-      return await client.callTool(name, params)
+      return await client.callTool(name, params, runtime.artifactsDir())
     },
   }
 
@@ -694,6 +776,9 @@ export function createToolSet(runtime              )               {
         `command: ${client.describe()}`,
         `running: ${client.running}`,
         `tools cached: ${client.cachedTools === undefined ? 'no' : client.cachedTools.length}`,
+        profile.mcpAttach === undefined
+          ? 'attach: not supported (headless MCP server only)'
+          : `attach: pass \`attach: <port>\` to drive a running app (it must be started with its control channel, e.g. \`${profile.bin.replace(/-cli$/, '')} --control <port>\`)`,
       ].join('\n')
     },
   }
@@ -780,11 +865,17 @@ export function applyCraftPlugin(
   }
   ctx.systemPrompt.section({
     name: `artcraft:${profile.id}`,
-    text: `${profile.product} is available through the ${profile.id}_* tools. `
-      + `Documents are ${profile.extensions.join('/')}. `
-      + `Discover operations with \`${profile.id}_commands\` (generic command ids) or `
-      + `\`${profile.id}_mcp_tools\` (modelled operations with JSON schemas), read them back with `
-      + `\`${profile.id}_inspect\`, and apply them with \`${profile.id}_run\` or \`${profile.id}_mcp_call\`.`,
+    text:
+      `${profile.product} is available through the ${profile.id}_* tools; documents are ${profile.extensions.join('/')}. `
+      + `Two surfaces reach the same engine. Use \`${profile.id}_commands\` for the full command registry `
+      + `(every menu action; fetch exact parameter grammar with \`${profile.id}_describe\`) and \`${profile.id}_run\` to apply `
+      + `an ordered list. Use \`${profile.id}_mcp_tools\` for the app's modelled operations with JSON Schemas when you want `
+      + `a safer first call, then \`${profile.id}_mcp_call\`. `
+      + `Read a document back with \`${profile.id}_inspect\` before editing it. `
+      + (profile.mcpAttach === undefined
+        ? ''
+        : `When the user has ${profile.product} open, pass \`attach: <control port>\` to an mcp call to work in their window instead of a headless copy. `)
+      + `Images returned by a render or screenshot are saved and named by path; look at them with \`read_image\`.`,
     order: CRAFT_SECTION_ORDER,
   })
   return () => {

package/src/kit/types.js

@@ -69,7 +69,7 @@
                                                                                  
                                                                            
      
-                                     
+