dsh-artcraft-plugin-soundcraft 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-artcraft-plugin-soundcraft",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive SoundCraft (audio production) headlessly through its own CLI and MCP server.",

package/src/kit/exec.js

@@ -155,6 +155,71 @@ export async function runCraft(options                 )
   })
 }
 
+/**
+ * Run one craft process in the background and stream its output to a log file.
+ *
+ * Long operations — a 4K render, a texture bake, an audio bounce — outlast any
+ * reasonable tool timeout, and killing them at the timer loses the work. A job
+ * keeps the process alive after the tool returns, so the caller can poll or wait
+ * and still read the output afterwards.
+ */
+                                 
+                                        
+                     
+                                     
+                                  
+                                                                   
+                          
+                                  
+                            
+                                            
+                                  
+ 
+
+/** A started job, including the process handle the runtime uses to observe it. */
+                                                         
+                                                               
+                              
+ 
+
+/** Live job state kept by the runtime. */
+                                                       
+                                              
+                           
+                                
+                                   
+                                                          
+                                         
+                                          
+                              
+ 
+
+/**
+ * Start a craft CLI in the background.
+ * @param options - profile, binary, argv, cwd and the log file to write.
+ * @returns a handle the caller can poll through its runtime.
+ */
+export function startCraftJob(options                                                                     )                  {
+  const { profile, binary, argv, cwd, logPath, id } = options
+  const child = spawn(binary.path, [...argv], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, NO_COLOR: '1', TERM: 'dumb' },
+    windowsHide: true,
+  })
+  const write = (chunk        )       => {
+    try {
+      appendFileSync(logPath, chunk)
+    } catch {
+      // A full disk must not take the tool down; the process keeps running.
+    }
+  }
+  child.stdout?.on('data', write)
+  child.stderr?.on('data', write)
+  void profile
+  return { id, pid: child.pid, logPath, startedAt: Date.now(), argv, child }
+}
+
 /**
  * Compose the argv for one headless `run` invocation.
  *

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,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--connect', format: 'port' },
   },
   {
     id: 'figcraft',
@@ -385,6 +395,7 @@ export const CRAFT_PROFILES = [
     catalogJson: true,
     catalogArgs: ['commands', '--json'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--attach', format: 'port' },
   },
   {
     id: 'texturecraft',
@@ -415,6 +426,7 @@ export const CRAFT_PROFILES = [
     catalogJson: false,
     catalogArgs: ['commands'],
     mcpArgs: ['mcp'],
+    mcpAttach: { flag: '--bridge', format: 'port' },
   },
 ]
 

package/src/kit/tools.js

@@ -12,11 +12,11 @@ import { CraftMcpClient, renderSchema } from './mcp.js'
                                        
 import { groupsOf, loadCatalog, score } from './catalog.js'
 import { craftVersion, discoverCraft, missingBinaryMessage } from './discover.js'
-import { mkdirSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
-import { DEFAULT_TIMEOUT_MS, buildRunArgv, runCraft } from './exec.js'
-                                                  
+import { DEFAULT_TIMEOUT_MS, buildRunArgv, killTree, runCraft, startCraftJob } from './exec.js'
+                                                                 
                                                                                          
 
 /**
@@ -157,23 +157,83 @@ 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)
+  const jobs = new Map                       ()
+  const jobChildren = new Map                                                   ()
+  let jobCounter = 0
   return {
+    startJob(binary, argv) {
+      jobCounter += 1
+      const id = `j${jobCounter}`
+      const jobDir = join(artifacts, 'jobs')
+      mkdirSync(jobDir, { recursive: true })
+      const logPath = join(jobDir, `${profile.id}-${id}.log`)
+      const started = startCraftJob({ profile, binary, argv, cwd: process.cwd(), logPath, id })
+      const state                = { ...started, running: true, argv: started.argv, logPath, id, pid: started.pid, startedAt: started.startedAt }
+      jobs.set(id, state)
+      jobChildren.set(id, started.child)
+      started.child.on('close', (code, signal) => {
+        const settled                = {
+          ...state, running: false, exitCode: code, signal,
+          durationMs: Date.now() - state.startedAt,
+        }
+        jobs.set(id, settled)
+        jobChildren.delete(id)
+      })
+      started.child.unref()
+      return started
+    },
+    jobState(id) {
+      return jobs.get(id)
+    },
+    jobs() {
+      return [...jobs.values()].sort((a, b) => a.startedAt - b.startedAt)
+    },
+    async waitForJob(id, timeoutMs) {
+      const state = jobs.get(id)
+      if (state === undefined) return undefined
+      const deadline = Date.now() + Math.max(0, timeoutMs)
+      for (;;) {
+        const current = jobs.get(id)
+        if (current === undefined || !current.running) return current
+        if (Date.now() >= deadline) return current
+        await new Promise(resolve => setTimeout(resolve, 200))
+      }
+    },
+    killJob(id) {
+      const child = jobChildren.get(id)
+      if (child !== undefined) killTree(child)
+      return child !== undefined
+    },
+    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)
@@ -250,6 +310,8 @@ export function renderCatalog(
                                           
                                         
                                             
+                                                                 
+                               
  
 
 /** One tool's definition: name/description/schema plus its executor. */
@@ -308,6 +370,25 @@ export function createToolSet(runtime              )               {
   const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS
   const catalogLimit = config.catalogLimit ?? 60
 
+  /**
+   * Run now, or start a background job when `background` is set.
+   *
+   * Renders, bakes and bounces outlast the tool timeout; a job keeps the process
+   * alive after the call returns and leaves its output in a log file.
+   */
+  const runOrStart = async (binary             , argv                   , background         )                  => {
+    if (background === true) {
+      const job = runtime.startJob(binary, argv)
+      return [
+        `started ${profile.id} job ${job.id}${job.pid === undefined ? '' : ` (pid ${job.pid})`}`,
+        `log: ${job.logPath}`,
+        `poll with \`${profile.id}_job\` {"action":"status","job":"${job.id}"}`,
+        `or wait with {"action":"wait","job":"${job.id}","timeoutMs":300000}`,
+      ].join('\n')
+    }
+    return renderRun(await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs }), profile)
+  }
+
   /** Guard every tool: a missing binary is an answer, never a crash. */
   const requireBinary = ()              => {
     const binary = runtime.binary()
@@ -321,13 +402,14 @@ export function createToolSet(runtime              )               {
     input                    ,
     sample                              ,
     commands                              ,
+    background         ,
   )                  => {
     const argv = buildRunArgv(profile, {
       ...input !== undefined ? { input } : {},
       ...sample !== undefined ? { sample } : {},
       commands,
     })
-    return renderRun(await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs }), profile)
+    return await runOrStart(binary, argv, background)
   }
 
   const session               = { commands: [], stale: false }
@@ -359,6 +441,7 @@ export function createToolSet(runtime              )               {
       + `${profile.blurb} Files: ${profile.extensions.join(', ')}.`,
     parameters: {
       input: { type: 'string', description: `Absolute or workspace-relative path to an existing ${profile.extensions[0]} document. Mutually exclusive with \`sample\`.` },
+      background: { type: 'boolean', description: 'Start the work as a background job and return immediately; poll it with the job tool. Use for long renders, bakes and bounces.' },
       commands: {
         type: 'array',
         description: 'Ordered commands to apply. Each is { "id": "cell.set", "json": { "cell": "A1", "input": "x" } }. An entry may also be a raw CLI string.',
@@ -452,8 +535,7 @@ export function createToolSet(runtime              )               {
         }
         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)
+        return await runOrStart(binary, [...argv, ...extra], args.background)
       }
       if (profile.run.scriptFlag !== undefined) {
         const scriptPath = join(craftWorkDir(profile), `steps-${Date.now()}.json`)
@@ -468,8 +550,7 @@ export function createToolSet(runtime              )               {
           profile.run.scriptFlag, scriptPath,
           ...Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : [],
         ]
-        const result = await runCraft({ profile, binary, argv: [profile.run.verb, ...extra], cwd: process.cwd(), timeoutMs })
-        return renderRun(result, profile)
+        return await runOrStart(binary, [profile.run.verb, ...extra], args.background)
       }
       if (profile.run.scriptMode === true) {
         const scriptPath = join(craftWorkDir(profile), `run-${Date.now()}.jsonl`)
@@ -481,12 +562,7 @@ export function createToolSet(runtime              )               {
           scriptPath,
           ...Array.isArray(args.extraArgs) ? args.extraArgs.filter((a)              => typeof a === 'string') : [],
         ]
-        const result = await runCraft({
-          profile, binary,
-          argv: [...globalFlagsFor(profile, args), profile.run.verb, ...extra],
-          cwd: process.cwd(), timeoutMs,
-        })
-        return renderRun(result, profile)
+        return await runOrStart(binary, [...globalFlagsFor(profile, args), profile.run.verb, ...extra], args.background)
       }
       // PdfCraft's `run` accepts exactly one tool per invocation; sending a
       // list would produce "expected key=value" from the CLI, so the extra
@@ -497,7 +573,7 @@ export function createToolSet(runtime              )               {
       // whole list in a single process; the history recorded above is replayed
       // through that path, so a second call continues the same document.
       if (profile.oneToolPerRun === true && profile.run.scriptFlag === undefined && rest.length > 0) {
-        const only = await runSingle(binary, input, sample, single)
+        const only = await runSingle(binary, input, sample, single, args.background)
         return `${only}\n\n[${profile.product} runs one tool per call: ${rest.length} further command(s) were not sent — ${rest.map(c => c.id).join(', ')}. Call this tool again for each.]`
       }
       const argv = buildRunArgv(profile, {
@@ -515,8 +591,7 @@ export function createToolSet(runtime              )               {
         ...args.print === true ? { print: true } : {},
         ...Array.isArray(args.extraArgs) ? { extra: args.extraArgs.filter((a)              => typeof a === 'string') } : {},
       })
-      const result = await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs })
-      return renderRun(result, profile)
+      return await runOrStart(binary, argv, args.background)
     },
   }
 
@@ -630,8 +705,7 @@ export function createToolSet(runtime              )               {
       else if (argMode === 'section') argv.push(typeof args.section === 'string' && args.section.length > 0 ? args.section : inspectSpec.section ?? 'project')
       if (inspectSpec.projectFlag !== undefined && typeof args.project === 'string') argv.push(inspectSpec.projectFlag, args.project)
       argv.push(...inspectSpec.extraArgs ?? [], ...extra)
-      const result = await runCraft({ profile, binary, argv, cwd: process.cwd(), timeoutMs })
-      return renderRun(result, profile)
+      return await runOrStart(binary, argv, args.background)
     },
   }
 
@@ -656,6 +730,69 @@ export function createToolSet(runtime              )               {
     },
   } : undefined
 
+  const job                  = {
+    kind: 'job',
+    name: `${profile.id}_job`,
+    description:
+      `Track background work started by \`${profile.id}_run\` with \`background: true\`. `
+      + `Long renders, bakes and bounces outlive a tool timeout; the job keeps running and logs to a file. `
+      + `Actions: \`list\` every job, \`status\` one (with the log tail), \`wait\` for it to finish, \`kill\` it.`,
+    parameters: {
+      action: { type: 'string', enum: ['list', 'status', 'wait', 'kill'], description: 'What to do. Defaults to list.' },
+      job: { type: 'string', description: 'Job id returned by the run call, e.g. "j1".' },
+      timeoutMs: { type: 'number', description: 'For action "wait": milliseconds to block (default 60000, at most 600000).' },
+      tailLines: { type: 'number', description: 'For "status"/"wait": how many log lines to show (default 20).' },
+    },
+    async execute(args) {
+      const action = typeof args.action === 'string' ? args.action : 'list'
+      const tailLines = typeof args.tailLines === 'number' && args.tailLines > 0 ? Math.min(Math.floor(args.tailLines), 200) : 20
+      /** Last lines of a job's log, with a byte cap so a huge log cannot flood the model. */
+      const tail = (path        )         => {
+        try {
+          const text = readFileSync(path, 'utf8')
+          const lines = text.split('\n')
+          const shown = lines.slice(Math.max(0, lines.length - tailLines)).join('\n').trim()
+          return shown.length > 8000 ? `…${shown.slice(-8000)}` : shown
+        } catch {
+          return '(no log yet)'
+        }
+      }
+      /** A job's argv, shortened: a 200-command render would otherwise print pages. */
+      const commandLine = (argv                   )         => {
+        const text = argv.join(' ')
+        return text.length > 240 ? `${text.slice(0, 240)}… (${argv.length} arguments)` : text
+      }
+      const describe = (state               )         => [
+        `${state.id}${state.running ? ' (running)' : ` (exit ${state.exitCode ?? state.signal ?? '?'})`}`
+        + ` — ${state.durationMs === undefined ? `${Math.round((Date.now() - state.startedAt) / 1000)}s so far` : `${Math.round(state.durationMs / 1000)}s`}`,
+        `  command: ${commandLine(state.argv)}`,
+        `  log: ${state.logPath}`,
+      ].join('\n')
+
+      if (action === 'list') {
+        const all = runtime.jobs()
+        if (all.length === 0) return `${profile.product}: no background jobs in this session.`
+        return [`${profile.product} background jobs: ${all.length}`, ...all.map(describe)].join('\n')
+      }
+      const id = typeof args.job === 'string' ? args.job.trim() : ''
+      if (id.length === 0) throw new Error('job is required for action ' + JSON.stringify(action))
+      if (action === 'kill') {
+        const killed = runtime.killJob(id)
+        const state = runtime.jobState(id)
+        return killed ? `killed ${id}` : `${id} is not running${state === undefined ? ' (unknown job)' : ''}`
+      }
+      if (action === 'wait') {
+        const timeout = typeof args.timeoutMs === 'number' && args.timeoutMs > 0 ? Math.min(Math.floor(args.timeoutMs), 600_000) : 60_000
+        const state = await runtime.waitForJob(id, timeout)
+        if (state === undefined) return `No job named ${JSON.stringify(id)}.`
+        return [describe(state), '', tail(state.logPath)].join('\n')
+      }
+      const state = runtime.jobState(id)
+      if (state === undefined) return `No job named ${JSON.stringify(id)}.`
+      return [describe(state), '', tail(state.logPath)].join('\n')
+    },
+  }
+
   const mcp = runtime.mcp()
   const idleMs = config.mcpIdleMs ?? 300_000
 
@@ -666,13 +803,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()
@@ -681,10 +824,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()}`,
         '',
       ]
@@ -693,6 +837,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')
     },
   }
@@ -703,13 +858,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')
@@ -722,7 +882,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())
     },
   }
 
@@ -739,6 +899,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')
     },
   }
@@ -750,6 +913,7 @@ export function createToolSet(runtime              )               {
     ...mcpTools !== undefined ? { mcpTools } : {},
     ...mcpCall !== undefined ? { mcpCall } : {},
     ...mcpStatus !== undefined ? { mcpStatus } : {},
+    job,
   }
 }
 
@@ -825,11 +989,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

@@ -6,6 +6,10 @@
  * @module @dsh-artcraft/craft-kit/types
  */
 
+                                                              
+
+                                             
+
 /** How one craft CLI spells its one-shot, headless "run some commands" verb. */