dsh-artcraft-plugin-gridcraft 0.2.1 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-artcraft-plugin-gridcraft",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "private": false,
   "type": "module",
   "description": "DSH plugin: drive GridCraft (spreadsheets) 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/journal.js

@@ -0,0 +1,55 @@
+/**
+ * A readable work journal for the craft tools.
+ *
+ * The harness shows each tool call, but a session that builds a report spans a
+ * dozen calls across four applications, and reconstructing what actually happened
+ * means scrolling a transcript. Every call also appends one line to a per-craft
+ * journal in the workspace (`.artcraft/journal/`), so the user can open one file
+ * and read the story: which craft, which operation, how long, what came out.
+ *
+ * A journal line is best-effort and never fails a tool call: a read-only
+ * workspace loses the record, not the work.
+ * @module @dsh-artcraft/craft-kit/journal
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+                                              
+
+/** One recorded event. */
+                               
+                                   
+                     
+                                            
+                       
+                                                                        
+                          
+                                          
+                                        
+ 
+
+/** Where the journals live, relative to the workspace the agent runs in. */
+export function journalDir(cwd         = process.cwd())         {
+  return join(cwd, '.artcraft', 'journal')
+}
+
+/**
+ * Append one entry to the craft's journal.
+ * @param profile - the craft that ran.
+ * @param entry - what happened.
+ * @param cwd - workspace root; defaults to the process cwd.
+ */
+export function appendJournal(profile              , entry              , cwd         = process.cwd())       {
+  try {
+    const dir = journalDir(cwd)
+    mkdirSync(dir, { recursive: true })
+    const time = new Date(entry.at).toTimeString().slice(0, 8)
+    const artifacts = entry.artifacts !== undefined && entry.artifacts.length > 0
+      ? `\n  → ${entry.artifacts.join(', ')}`
+      : ''
+    appendFileSync(join(dir, `${profile.id}.md`), `${time} · ${entry.kind} · ${entry.summary}${artifacts}\n`)
+    appendFileSync(join(dir, 'events.jsonl'), JSON.stringify({ craft: profile.id, ...entry }) + '\n')
+  } catch {
+    // A journal is a convenience; never let it fail the call that produced it.
+  }
+}

package/src/kit/present.js

@@ -0,0 +1,206 @@
+/**
+ * Render intents for the craft tools: what a call looks like *while running* and
+ * what its result looks like afterwards.
+ *
+ * A craft run is one call that performs a dozen steps, and a raw JSONL dump is a
+ * poor card: the reader cannot see how many steps there are, which one failed, or
+ * what files came out. These presenters turn the same result into a titled card
+ * (a UI that understands {@link ToolCallView}/{@link ToolResultView} shows it as a
+ * tool row with a header and a short body).
+ *
+ * The kernel stays DSH-free: these are plain objects shaped like the harness's
+ * view contracts, and the calling plugin passes them to `defineTool`.
+ * @module @dsh-artcraft/craft-kit/present
+ */
+
+                                              
+
+/** One text block, as the harness's content-block shape expects. */
+                                
+                       
+                       
+ 
+
+/** A file the call touches, for editor follow-along. */
+                               
+                       
+                        
+ 
+
+/** Pending-call card: `{card:'generic'}` with a title and an optional body. */
+                           
+                          
+                        
+                                                                                                
+                             
+                                             
+                                              
+ 
+
+/** Completed-call card: a replacement title and reformatted content. */
+                             
+                          
+                         
+                                            
+ 
+
+/** Arguments the model passed, as far as these presenters care. */
+                                   
+
+/** First `count` entries of a list, plus a count when longer. */
+function summarise   (items              , render                     , count = 8)                  {
+  const shown = items.slice(0, count).map(render)
+  if (items.length > shown.length) shown.push(`…and ${items.length - shown.length} more`)
+  return shown.length === 0 ? [{ type: 'text', text: '(no commands)' }] : shown.map(text => ({ type: 'text', text }))
+}
+
+/** The command list a run call carries, whether objects or raw strings. */
+function commandLabels(raw         )           {
+  if (!Array.isArray(raw)) return []
+  return raw.map((entry) => {
+    if (typeof entry === 'string') return entry
+    if (typeof entry === 'object' && entry !== null) {
+      const record = entry                                    
+      const id = typeof record.id === 'string' ? record.id : '(unnamed)'
+      const json = record.json === undefined ? '' : ` ${JSON.stringify(record.json)}`
+      return `${id}${json.length > 60 ? `${json.slice(0, 60)}…` : json}`
+    }
+    return String(entry)
+  })
+}
+
+/** A path from the arguments, when the call writes one. */
+function outputPath(args      )                     {
+  for (const key of ['save', 'export', 'output', 'out']         ) {
+    const value = args[key]
+    if (typeof value === 'string' && value.length > 0) return value
+  }
+  return undefined
+}
+
+/** A path from the arguments, when the call reads one. */
+function inputPath(args      )                     {
+  const value = args.input ?? args.file
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/**
+ * The pending-call card for one tool.
+ * @param profile - the craft, for the title.
+ * @param kind - which tool of the set is being called.
+ * @param args - the model's arguments.
+ * @returns a generic call view.
+ */
+export function craftCallView(profile              , kind        , args      )           {
+  const name = profile.product
+  switch (kind) {
+    case 'run': {
+      const labels = commandLabels(args.commands)
+      const target = outputPath(args)
+      return {
+        card: 'generic',
+        kind: 'execute',
+        title: `${name} · ${labels.length} command${labels.length === 1 ? '' : 's'}${target === undefined ? '' : ` → ${target}`}`,
+        content: summarise(labels, label => `• ${label}`),
+        ...target === undefined ? {} : { locations: [{ path: target }] },
+      }
+    }
+    case 'commands': {
+      const search = typeof args.search === 'string' && args.search.length > 0 ? ` "${args.search}"` : ''
+      return { card: 'generic', kind: 'search', title: `${name} · command catalogue${search}` }
+    }
+    case 'describe': {
+      const id = typeof args.id === 'string' ? args.id : ''
+      return { card: 'generic', kind: 'read', title: `${name} · describe ${id}` }
+    }
+    case 'inspect': {
+      const file = inputPath(args) ?? '(default)'
+      return { card: 'generic', kind: 'read', title: `${name} · inspect ${file}`, locations: [{ path: file }] }
+    }
+    case 'convert': {
+      const input = inputPath(args) ?? ''
+      const output = typeof args.output === 'string' ? args.output : ''
+      return {
+        card: 'generic',
+        kind: 'execute',
+        title: `${name} · convert ${input}${output.length === 0 ? '' : ` → ${output}`}`,
+        locations: output.length === 0 ? [] : [{ path: output }],
+      }
+    }
+    case 'mcpCall': {
+      const tool = typeof args.tool === 'string' ? args.tool : '(tool)'
+      const attach = typeof args.attach === 'number' ? ` · attached :${args.attach}` : ''
+      return { card: 'generic', kind: 'execute', title: `${name} · ${tool}${attach}`, rawInput: args.arguments }
+    }
+    case 'mcpTools': {
+      const search = typeof args.search === 'string' && args.search.length > 0 ? ` "${args.search}"` : ''
+      return { card: 'generic', kind: 'search', title: `${name} · MCP tools, resources and prompts${search}` }
+    }
+    case 'mcpStatus':
+      return { card: 'generic', kind: 'read', title: `${name} · MCP bridge status` }
+    case 'job': {
+      const action = typeof args.action === 'string' ? args.action : 'list'
+      const job = typeof args.job === 'string' ? ` ${args.job}` : ''
+      return { card: 'generic', kind: 'other', title: `${name} · job ${action}${job}` }
+    }
+    default:
+      return { card: 'generic', kind: 'other', title: `${name} · ${kind}` }
+  }
+}
+
+/** What a run result text says: exit status, duration, artifacts, per-step failures. */
+function summariseRun(profile              , text        )             {
+  const steps = text.split('\n').filter(line => line.startsWith('{"command"') || line.startsWith('{"step"'))
+  let ok = 0
+  let failed = 0
+  let firstFailure = ''
+  for (const line of steps) {
+    try {
+      const parsed = JSON.parse(line)                                                      
+      if (parsed.ok === false) {
+        failed += 1
+        if (firstFailure.length === 0) firstFailure = `${parsed.command ?? 'step'}: ${parsed.error ?? 'failed'}`
+      } else ok += 1
+    } catch {
+      // A craft that prints non-JSON progress lines still runs; the exit line below decides.
+    }
+  }
+  const exit = /exited (\d+) in (\d+)ms/.exec(text)
+  const artifacts = [...text.matchAll(/^(?:wrote|saved|exported) (.+)$/gm)].map(match => match[1])
+  const title = `${profile.product} · ${steps.length > 0 ? `${ok} ok${failed > 0 ? `, ${failed} failed` : ''}` : 'finished'}${exit === null ? '' : ` · exit ${exit[1]}`}`
+  const body           = []
+  if (failed > 0) body.push(`first failure — ${firstFailure}`)
+  if (artifacts.length > 0) body.push(`wrote ${artifacts.join(', ')}`)
+  if (exit !== null) body.push(`took ${exit[2]} ms`)
+  if (body.length === 0) body.push(text.trim().split('\n')[0] ?? '(no output)')
+  return { card: 'generic', title, content: body.map(line => ({ type: 'text', text: line })) }
+}
+
+/**
+ * The completed-call card for one tool.
+ * @param profile - the craft, for the title.
+ * @param kind - which tool ran.
+ * @param text - the model-facing result.
+ * @param isError - whether the call failed.
+ * @returns a generic result view.
+ */
+export function craftResultView(profile              , kind        , text        , isError         )             {
+  if (isError) {
+    return {
+      card: 'generic',
+      title: `${profile.product} · ${kind} failed`,
+      content: [{ type: 'text', text: text.split('\n').slice(0, 4).join('\n') }],
+    }
+  }
+  if (kind === 'run') return summariseRun(profile, text)
+  const all = text.trim().split('\n').filter(line => line.trim().length > 0)
+  // A few lines are usually the whole story (job status, an image path and its
+  // dimensions); keep them rather than collapsing to one line and a count.
+  const shown = all.slice(0, 4)
+  if (all.length > shown.length) shown.push(`…and ${all.length - shown.length} more lines`)
+  return {
+    card: 'generic',
+    title: `${profile.product} · ${kind}`,
+    content: (shown.length === 0 ? ['(no output)'] : shown).map(line => ({ type: 'text', text: line })),
+  }
+}

package/src/kit/tools.js

@@ -8,15 +8,17 @@
  * @module @dsh-artcraft/craft-kit/tools
  */
 
+import { craftCallView, craftResultView } from './present.js'
+import { appendJournal } from './journal.js'
 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'
+                                                                 
                                                                                          
 
 /**
@@ -159,7 +161,53 @@ export function createRuntime(profile              , packageRoot        , config
   let catalogCache                                                                                                          
   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
     },
@@ -264,15 +312,21 @@ export function renderCatalog(
                                           
                                         
                                             
+                                                                 
+                               
  
 
-/** One tool's definition: name/description/schema plus its executor. */
+/** One tool's definition: name/description/schema plus its executor and views. */
                                              
                   
                        
                               
                                               
                                                                       
+                                                          
+                                                                   
+                                                     
+                                                                                                     
  
 
 /**
@@ -322,6 +376,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()
@@ -335,13 +408,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 }
@@ -373,6 +447,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.',
@@ -466,8 +541,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`)
@@ -482,8 +556,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`)
@@ -495,12 +568,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
@@ -511,7 +579,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, {
@@ -529,8 +597,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)
     },
   }
 
@@ -644,8 +711,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)
     },
   }
 
@@ -670,6 +736,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
 
@@ -790,10 +919,12 @@ export function createToolSet(runtime              )               {
     ...mcpTools !== undefined ? { mcpTools } : {},
     ...mcpCall !== undefined ? { mcpCall } : {},
     ...mcpStatus !== undefined ? { mcpStatus } : {},
+    job,
   }
 }
 
 
+
 /** Prompt-section slot: after the built-in tool sections, app prose follows. */
 export const CRAFT_SECTION_ORDER = 120
 
@@ -810,8 +941,34 @@ export const CRAFT_SECTION_ORDER = 120
                                                                               
    
                                                           
+                                          
+                                                                                                                                
              
 
+/** One-line journal summary for a finished call. */
+function journalSummary(kind        , args                         , text        , elapsedMs        )         {
+  const output = ['save', 'export', 'output', 'out'].map(key => args[key]).find(value => typeof value === 'string' && value.length > 0)
+  switch (kind) {
+    case 'run': {
+      const count = Array.isArray(args.commands) ? args.commands.length : 0
+      const exit = /exited (\d+)/.exec(text)
+      return `${count} command(s)${output === undefined ? '' : ` → ${String(output)}`}`
+        + `${exit === null ? '' : ` · exit ${exit[1]}`} · ${elapsedMs}ms`
+    }
+    case 'mcpCall':
+      return `tool ${String(args.tool ?? '?')} · ${elapsedMs}ms`
+    case 'job':
+      return `job ${String(args.action ?? 'list')}${typeof args.job === 'string' ? ` ${args.job}` : ''}`
+    case 'inspect':
+    case 'convert':
+      return `${String(args.file ?? args.input ?? '')}${args.output === undefined ? '' : ` → ${String(args.output)}`}`
+    default: {
+      const first = text.trim().split('\n')[0] ?? ''
+      return first.length > 120 ? `${first.slice(0, 120)}…` : first
+    }
+  }
+}
+
 /** The `ctx` surface the kernel uses; kept structural for the same reason. */
                                      
                                                              
@@ -859,8 +1016,32 @@ export function applyCraftPlugin(
         render: (_args         , value        ) => [{ type: 'text'         , text: value }],
       },
       async execute(args       ) {
-        return await spec.execute(args                                      )
+        const typed = args                                      
+        const startedAt = Date.now()
+        try {
+          const text = await spec.execute(typed)
+          appendJournal(profile, { at: startedAt, kind: spec.kind, summary: journalSummary(spec.kind, typed, text, Date.now() - startedAt) })
+          return text
+        } catch (error) {
+          appendJournal(profile, {
+            at: startedAt,
+            kind: spec.kind,
+            summary: `failed: ${String((error         ).message ?? error).slice(0, 140)}`,
+          })
+          throw error
+        }
       },
+      // Cards: a run is one call with a dozen steps, so the raw JSONL is a poor
+      // row. These turn it into a titled card — what the call does, then what it
+      // produced — and the journal keeps the same story on disk.
+      presentCall: (args         ) => craftCallView(profile, spec.kind, (args ?? {})                           ),
+      presentResult: (args         , result                                                                            ) =>
+        craftResultView(
+          profile,
+          spec.kind,
+          (result.content ?? []).filter(block => block.type === 'text').map(block => block.text ?? '').join('\n'),
+          result.isError === true,
+        ),
     })))
   }
   ctx.systemPrompt.section({

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. */