@qvac/harness 0.1.2 → 0.2.0

package/dist-lib/lib/tools/exec.js

@@ -59,16 +59,19 @@ function resolveExecution(adapters, fallback, args, ctx) {
     }
     return fallback.resolve(args, ctx);
 }
+function isPresent(value) {
+    return value !== undefined && value !== null;
+}
 function checkFileArgs(args, python) {
+    if (!python && (isPresent(args.inputs) || isPresent(args.outputs))) {
+        return 'inputs and outputs require language "python" with Pyodide enabled';
+    }
     const inputs = parseInputs(args.inputs);
     if (inputs && 'error' in inputs)
         return inputs.error;
     const outputs = parseOutputs(args.outputs);
     if (outputs && 'error' in outputs)
         return outputs.error;
-    if ((inputs || outputs) && !python) {
-        return 'inputs and outputs require language "python" with Pyodide enabled';
-    }
     if (!python)
         return null;
     const workdir = parseWorkdir(args.workdir);
@@ -150,6 +153,12 @@ export function resolveScriptRun(rawArgs, skillsDir) {
             trusted: false
         };
     }
+    if (!script.startsWith('scripts/') || !script.endsWith('.py')) {
+        return {
+            error: 'script takes a scripts/*.py path bundled with a skill, not a command line — ' +
+                `run a shell command by passing it in \`command\` instead. Got: ${String(rawArgs.script)}`
+        };
+    }
     const skill = typeof rawArgs.skill === 'string' ? unquoteArg(rawArgs.skill) : '';
     if (!skill)
         return { error: 'script runs need the owning skill name in `skill`' };
@@ -158,11 +167,6 @@ export function resolveScriptRun(rawArgs, skillsDir) {
     if (String(rawArgs.command ?? '').trim()) {
         return { error: 'pass either command or script, never both' };
     }
-    if (!script.startsWith('scripts/') || !script.endsWith('.py')) {
-        return {
-            error: `script must be a scripts/*.py path from the skill instructions, got: ${script}`
-        };
-    }
     const segments = [...skill.split('/'), ...script.split('/')];
     if (segments.some((segment) => segment === '' || segment === '..' || segment.includes('\\'))) {
         return { error: `script not found in skill ${skill}: ${script}` };
@@ -294,6 +298,54 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
             },
             required: []
         },
+        prompt: {
+            description: "Run one program on the user's device: a shell command, or Python source in `command` with " +
+                'language="python". Chaining, pipes, redirection and shell expansion are rejected. ' +
+                'Returns stdout, stderr, exit code. Run a script ' +
+                'bundled with a loaded skill via `skill`+`script`+`scriptArgs`, never as retyped source.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'Shell command, or bare Python source when language="python".'
+                    },
+                    language: {
+                        type: 'string',
+                        enum: ['shell', 'python'],
+                        description: '"python" runs `command` as Python; default shell.'
+                    },
+                    packages: { type: 'array', description: 'python only: PyPI packages to install.' },
+                    inputs: {
+                        type: 'array',
+                        description: 'python only: attachments to stage as {attachmentId, path}, path a bare file name; ' +
+                            'omit attachmentId for the latest attached image.'
+                    },
+                    outputs: {
+                        type: 'array',
+                        description: 'Only with language "python": bare file names the code writes; attached on success.'
+                    },
+                    workdir: { type: 'string' },
+                    timeoutMs: { type: 'number', description: 'default 120000, max 600000.' },
+                    maxOutputChars: {
+                        type: 'number',
+                        description: 'stdout/stderr cap (default 8192, max 65536); raise for long content.'
+                    },
+                    script: {
+                        type: 'string',
+                        description: 'Run a python script bundled with a loaded skill instead of passing source: a scripts/*.py ' +
+                            'path exactly as the skill instructions name it (e.g. "scripts/extract_text.py"). Requires ' +
+                            '`skill`; leave `command` unset. Never a command line — shell commands go in `command`.'
+                    },
+                    skill: {
+                        type: 'string',
+                        description: 'With script: the name of the skill that bundles it (e.g. "pdf").'
+                    },
+                    scriptArgs: { type: 'array', description: 'With script: string arguments in order.' }
+                },
+                required: []
+            }
+        },
         autoApprove: false,
         effect(args, ctx) {
             if (typeof args.script === 'string' && args.script.trim() && !args.script.includes('\n')) {

package/dist-lib/lib/tools/generate-image.d.ts

@@ -67,6 +67,7 @@ export declare const IMAGE_LOAD_STALL_MS: number;
 export interface DiffusionRuntimeOptions extends ImageModelSet {
     loadSdk: () => Promise<DiffusionSdk>;
     onProgress?: (model: string, progress: Record<string, unknown>) => void;
+    onLoaded?: (model: string) => void;
     onBeforeLoad?: (signal?: BareAbortSignal) => Promise<void>;
     loads?: LoadTracker;
     stallMs?: number;
@@ -86,7 +87,7 @@ export interface DiffusionRuntime {
 }
 export declare function generationPercentTick(onPercent: (percentage: number) => void, encodePhases?: number): (tick: DiffusionTick) => void;
 export declare const IMAGE_LOAD_STALL_ERROR = "image model download stalled";
-export declare function createDiffusionRuntime({ loadSdk, onProgress, onBeforeLoad, loads, stallMs, ...base }: DiffusionRuntimeOptions): DiffusionRuntime;
+export declare function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBeforeLoad, loads, stallMs, ...base }: DiffusionRuntimeOptions): DiffusionRuntime;
 export declare const BUSY_ERROR = "an image generation is already running; try again when it finishes";
 export declare function runDiffusion(sdk: DiffusionSdk, modelId: string, params: DiffusionParams, signal?: BareAbortSignal, onTick?: (tick: DiffusionTick) => void): Promise<Uint8Array | {
     error: string;

package/dist-lib/lib/tools/generate-image.js

@@ -60,7 +60,7 @@ function createLoadStall(ms) {
         promise
     };
 }
-export function createDiffusionRuntime({ loadSdk, onProgress, onBeforeLoad, loads = createLoadTracker(), stallMs = IMAGE_LOAD_STALL_MS, ...base }) {
+export function createDiffusionRuntime({ loadSdk, onProgress, onLoaded, onBeforeLoad, loads = createLoadTracker(), stallMs = IMAGE_LOAD_STALL_MS, ...base }) {
     let loading = null;
     let residentFingerprint = null;
     let busy = false;
@@ -128,6 +128,7 @@ export function createDiffusionRuntime({ loadSdk, onProgress, onBeforeLoad, load
                     });
                     try {
                         const modelId = await Promise.race([loads.track(pending), stall.promise]);
+                        onLoaded?.(diffusionProgressName(set));
                         return { modelId, prediction: set.prediction };
                     }
                     catch (err) {

package/dist-lib/lib/tools/skill.js

@@ -87,6 +87,22 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
             },
             required: ['name']
         },
+        prompt: {
+            description: "Load a named skill's instructions FIRST, before any other tool, when a listed skill covers " +
+                'what you are about to do — and again with `file` for any file they reference.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    file: {
+                        type: 'string',
+                        description: "A file inside the skill, exactly as named there (e.g. 'references/edit.md'). " +
+                            'Omit for the main instructions.'
+                    }
+                },
+                required: ['name']
+            }
+        },
         effect: () => 'read',
         autoApprove: true,
         async execute(args, ctx) {

package/dist-lib/lib/wire.d.ts

@@ -35,6 +35,7 @@ export interface WireEvent {
 }
 export interface WireDownloadEvent {
     type: string;
+    downloaded?: boolean | null;
     progress?: unknown;
     assetId?: string | null;
     message?: string | null;

package/dist-lib/lib/wire.js

@@ -88,7 +88,11 @@ export function toDownloadWire(event) {
             return { type, progress };
         }
         case 'complete':
-            return { type: 'complete', assetId: event.assetId };
+            return {
+                type: 'complete',
+                assetId: event.assetId,
+                downloaded: typeof event.downloaded === 'boolean' ? event.downloaded : undefined
+            };
         case 'error':
             return { type: 'error', message: event.message };
         case 'aborted':
@@ -102,7 +106,7 @@ export function fromDownloadWire(event) {
         case 'progress':
             return { type: 'progress', ...(event.progress ?? {}) };
         case 'complete':
-            return { type: 'complete', assetId: event.assetId ?? '' };
+            return { type: 'complete', assetId: event.assetId ?? '', downloaded: event.downloaded };
         case 'error':
             return { type: 'error', message: event.message ?? 'download error' };
         case 'aborted':

package/dist-lib/schema/harness.js

@@ -167,7 +167,7 @@ export function registerHarnessTypes(ns) {
     });
     ns.register({
         name: 'model-event-status',
-        enum: ['loading', 'downloading', 'ready', 'error', 'unloading', 'unloaded'],
+        enum: ['loading', 'downloading', 'ready', 'error', 'unloading', 'unloaded', 'downloaded'],
         strings: true
     });
     ns.register({
@@ -209,7 +209,8 @@ export function registerHarnessTypes(ns) {
             { name: 'type', type: '@harness/download-event-type', required: true },
             { name: 'progress', type: 'json' },
             { name: 'assetId', type: 'string' },
-            { name: 'message', type: 'string' }
+            { name: 'message', type: 'string' },
+            { name: 'downloaded', type: 'bool', useDefault: false }
         ]
     });
     ns.register({
@@ -605,6 +606,10 @@ export function registerHarnessTypes(ns) {
         name: 'delete-skill-response',
         fields: [{ name: 'removed', type: 'bool', required: true }]
     });
+    ns.register({
+        name: 'kv-cache-delete-request',
+        fields: [{ name: 'kvCacheKey', type: 'string', required: true }]
+    });
 }
 export function registerHarnessApi(api) {
     api.register({
@@ -742,4 +747,9 @@ export function registerHarnessApi(api) {
         request: { name: '@harness/skill-name-request', stream: false },
         response: { name: '@harness/delete-skill-response', stream: false }
     });
+    api.register({
+        name: 'delete-kv-cache',
+        request: { name: '@harness/kv-cache-delete-request', stream: false },
+        response: { name: '@harness/kv-cache-deletion-response', stream: false }
+    });
 }

package/dist-lib/spec/bind.js

@@ -121,4 +121,7 @@ export function bindApi(rpc, api) {
   if (api.deleteOverlaySkill) {
     rpc.onDeleteOverlaySkill((req) => api.deleteOverlaySkill(req));
   }
+  if (api.deleteKvCache) {
+    rpc.onDeleteKvCache((req) => api.deleteKvCache(req));
+  }
 }

package/dist-lib/spec/calls.js

@@ -37,5 +37,6 @@ export function harnessClient(rpc) {
     writeSkillFile: (input) => rpc.writeSkillFile(input),
     copySkillForEdit: (input) => rpc.copySkillForEdit(input),
     deleteOverlaySkill: (input) => rpc.deleteOverlaySkill(input),
+    deleteKvCache: (input) => rpc.deleteKvCache(input),
   };
 }

package/dist-lib/spec/hrpc/hrpc.json

@@ -351,6 +351,19 @@
         "stream": false
       },
       "version": 1
+    },
+    {
+      "id": 27,
+      "name": "@harness/delete-kv-cache",
+      "request": {
+        "name": "@harness/kv-cache-delete-request",
+        "stream": false
+      },
+      "response": {
+        "name": "@harness/kv-cache-deletion-response",
+        "stream": false
+      },
+      "version": 1
     }
   ]
 }

package/dist-lib/spec/hrpc/index.js

@@ -59,7 +59,9 @@ const methods = new Map([
   ['@harness/copy-skill-for-edit', 25],
   [25, '@harness/copy-skill-for-edit'],
   ['@harness/delete-overlay-skill', 26],
-  [26, '@harness/delete-overlay-skill']
+  [26, '@harness/delete-overlay-skill'],
+  ['@harness/delete-kv-cache', 27],
+  [27, '@harness/delete-kv-cache']
 ])
 
 class HRPC {
@@ -93,7 +95,8 @@ class HRPC {
       ['@harness/read-skill-file', getEncoding('@harness/skill-name-request')],
       ['@harness/write-skill-file', getEncoding('@harness/write-skill-request')],
       ['@harness/copy-skill-for-edit', getEncoding('@harness/skill-name-request')],
-      ['@harness/delete-overlay-skill', getEncoding('@harness/skill-name-request')]
+      ['@harness/delete-overlay-skill', getEncoding('@harness/skill-name-request')],
+      ['@harness/delete-kv-cache', getEncoding('@harness/kv-cache-delete-request')]
     ])
     this._responseEncodings = new Map([
       ['@harness/completion', getEncoding('@harness/completion-event')],
@@ -122,7 +125,8 @@ class HRPC {
       ['@harness/read-skill-file', getEncoding('@harness/skill-file-response')],
       ['@harness/write-skill-file', getEncoding('@harness/ok-response')],
       ['@harness/copy-skill-for-edit', getEncoding('@harness/copy-skill-response')],
-      ['@harness/delete-overlay-skill', getEncoding('@harness/delete-skill-response')]
+      ['@harness/delete-overlay-skill', getEncoding('@harness/delete-skill-response')],
+      ['@harness/delete-kv-cache', getEncoding('@harness/kv-cache-deletion-response')]
     ])
     this._rpc = new RPC(stream, async (req) => {
       const command = methods.get(req.command)
@@ -328,6 +332,10 @@ class HRPC {
     return this._call('@harness/delete-overlay-skill', args)
   }
 
+  async deleteKvCache(args) {
+    return this._call('@harness/delete-kv-cache', args)
+  }
+
   onCompletion(responseFn) {
     this._handlers['@harness/completion'] = responseFn
   }
@@ -436,6 +444,10 @@ class HRPC {
     this._handlers['@harness/delete-overlay-skill'] = responseFn
   }
 
+  onDeleteKvCache(responseFn) {
+    this._handlers['@harness/delete-kv-cache'] = responseFn
+  }
+
   _requestIsStream(command) {
     return [
       '@harness/completion',

package/dist-lib/spec/hrpc/messages.js

@@ -878,13 +878,14 @@ const encoding14_enum = {
   ready: 'ready',
   error: 'error',
   unloading: 'unloading',
-  unloaded: 'unloaded'
+  unloaded: 'unloaded',
+  downloaded: 'downloaded'
 }
 
 // @harness/model-event-status enum
 const encoding14 = {
   preencode (state, m) {
-    state.end++ // max enum is 6 so always one byte
+    state.end++ // max enum is 7 so always one byte
   },
   encode (state, m) {
     switch (m) {
@@ -906,6 +907,9 @@ const encoding14 = {
       case 'unloaded':
         c.uint.encode(state, 6)
         break
+      case 'downloaded':
+        c.uint.encode(state, 7)
+        break
       default:
         throw new Error('Unknown enum')
     }
@@ -924,6 +928,8 @@ const encoding14 = {
         return 'unloading'
       case 6:
         return 'unloaded'
+      case 7:
+        return 'downloaded'
       default: return null
     }
   }
@@ -1080,14 +1086,18 @@ const encoding18 = {
 const encoding19 = {
   preencode(state, m) {
     encoding18.preencode(state, m.type)
-    state.end++ // max flag is 4 so always one byte
+    state.end++ // max flag is 8 so always one byte
 
     if (m.progress) c.json.preencode(state, m.progress)
     if (m.assetId) c.string.preencode(state, m.assetId)
     if (m.message) c.string.preencode(state, m.message)
   },
   encode(state, m) {
-    const flags = (m.progress ? 1 : 0) | (m.assetId ? 2 : 0) | (m.message ? 4 : 0)
+    const flags =
+      (m.progress ? 1 : 0) |
+      (m.assetId ? 2 : 0) |
+      (m.message ? 4 : 0) |
+      ((version >= 7 && m.downloaded) ? 8 : 0)
 
     encoding18.encode(state, m.type)
     c.uint.encode(state, flags)
@@ -1104,7 +1114,8 @@ const encoding19 = {
       type: r0,
       progress: (flags & 1) !== 0 ? c.json.decode(state) : null,
       assetId: (flags & 2) !== 0 ? c.string.decode(state) : null,
-      message: (flags & 4) !== 0 ? c.string.decode(state) : null
+      message: (flags & 4) !== 0 ? c.string.decode(state) : null,
+      downloaded: (version >= 7 && (flags & 8) !== 0)
     }
   }
 }
@@ -2862,6 +2873,23 @@ const encoding76 = {
   }
 }
 
+// @harness/kv-cache-delete-request
+const encoding77 = {
+  preencode(state, m) {
+    c.string.preencode(state, m.kvCacheKey)
+  },
+  encode(state, m) {
+    c.string.encode(state, m.kvCacheKey)
+  },
+  decode(state) {
+    const r0 = c.string.decode(state)
+
+    return {
+      kvCacheKey: r0
+    }
+  }
+}
+
 // @harness/completion-frame.grantedDrives, deferred due to recusive use
 const encoding11_23 = c.array(c.frame(encoding60))
 // @harness/skill.setupV2, deferred due to recusive use
@@ -3074,6 +3102,8 @@ function getEncoding(name) {
       return encoding75
     case '@harness/delete-skill-response':
       return encoding76
+    case '@harness/kv-cache-delete-request':
+      return encoding77
     default:
       throw new Error('Encoder not found ' + name)
   }

package/dist-lib/spec/hyperschema/index.js

@@ -878,13 +878,14 @@ const encoding14_enum = {
   ready: 'ready',
   error: 'error',
   unloading: 'unloading',
-  unloaded: 'unloaded'
+  unloaded: 'unloaded',
+  downloaded: 'downloaded'
 }
 
 // @harness/model-event-status enum
 const encoding14 = {
   preencode (state, m) {
-    state.end++ // max enum is 6 so always one byte
+    state.end++ // max enum is 7 so always one byte
   },
   encode (state, m) {
     switch (m) {
@@ -906,6 +907,9 @@ const encoding14 = {
       case 'unloaded':
         c.uint.encode(state, 6)
         break
+      case 'downloaded':
+        c.uint.encode(state, 7)
+        break
       default:
         throw new Error('Unknown enum')
     }
@@ -924,6 +928,8 @@ const encoding14 = {
         return 'unloading'
       case 6:
         return 'unloaded'
+      case 7:
+        return 'downloaded'
       default: return null
     }
   }
@@ -1080,14 +1086,18 @@ const encoding18 = {
 const encoding19 = {
   preencode(state, m) {
     encoding18.preencode(state, m.type)
-    state.end++ // max flag is 4 so always one byte
+    state.end++ // max flag is 8 so always one byte
 
     if (m.progress) c.json.preencode(state, m.progress)
     if (m.assetId) c.string.preencode(state, m.assetId)
     if (m.message) c.string.preencode(state, m.message)
   },
   encode(state, m) {
-    const flags = (m.progress ? 1 : 0) | (m.assetId ? 2 : 0) | (m.message ? 4 : 0)
+    const flags =
+      (m.progress ? 1 : 0) |
+      (m.assetId ? 2 : 0) |
+      (m.message ? 4 : 0) |
+      ((version >= 7 && m.downloaded) ? 8 : 0)
 
     encoding18.encode(state, m.type)
     c.uint.encode(state, flags)
@@ -1104,7 +1114,8 @@ const encoding19 = {
       type: r0,
       progress: (flags & 1) !== 0 ? c.json.decode(state) : null,
       assetId: (flags & 2) !== 0 ? c.string.decode(state) : null,
-      message: (flags & 4) !== 0 ? c.string.decode(state) : null
+      message: (flags & 4) !== 0 ? c.string.decode(state) : null,
+      downloaded: (version >= 7 && (flags & 8) !== 0)
     }
   }
 }
@@ -2862,6 +2873,23 @@ const encoding76 = {
   }
 }
 
+// @harness/kv-cache-delete-request
+const encoding77 = {
+  preencode(state, m) {
+    c.string.preencode(state, m.kvCacheKey)
+  },
+  encode(state, m) {
+    c.string.encode(state, m.kvCacheKey)
+  },
+  decode(state) {
+    const r0 = c.string.decode(state)
+
+    return {
+      kvCacheKey: r0
+    }
+  }
+}
+
 // @harness/completion-frame.grantedDrives, deferred due to recusive use
 const encoding11_23 = c.array(c.frame(encoding60))
 // @harness/skill.setupV2, deferred due to recusive use
@@ -3074,6 +3102,8 @@ function getEncoding(name) {
       return encoding75
     case '@harness/delete-skill-response':
       return encoding76
+    case '@harness/kv-cache-delete-request':
+      return encoding77
     default:
       throw new Error('Encoder not found ' + name)
   }

package/dist-lib/spec/hyperschema/schema.json

@@ -698,6 +698,10 @@
         {
           "key": "unloaded",
           "version": 1
+        },
+        {
+          "key": "downloaded",
+          "version": 7
         }
       ],
       "strings": true
@@ -846,6 +850,11 @@
           "name": "message",
           "type": "string",
           "version": 1
+        },
+        {
+          "name": "downloaded",
+          "type": "bool",
+          "version": 7
         }
       ]
     },
@@ -2285,6 +2294,20 @@
           "version": 6
         }
       ]
+    },
+    {
+      "name": "kv-cache-delete-request",
+      "namespace": "harness",
+      "compact": false,
+      "flagsPosition": -1,
+      "fields": [
+        {
+          "name": "kvCacheKey",
+          "required": true,
+          "type": "string",
+          "version": 7
+        }
+      ]
     }
   ]
 }

package/dist-lib/spec/hyperschema/types.d.ts

@@ -121,7 +121,7 @@ export interface HarnessCompletionEvent {
   rawCall?: string | null
 }
 
-export type HarnessModelEventStatus = "loading" | "downloading" | "ready" | "error" | "unloading" | "unloaded"
+export type HarnessModelEventStatus = "loading" | "downloading" | "ready" | "error" | "unloading" | "unloaded" | "downloaded"
 
 export interface HarnessLoadedModel {
   model: string
@@ -152,6 +152,7 @@ export interface HarnessDownloadEvent {
   progress?: unknown | null
   assetId?: string | null
   message?: string | null
+  downloaded?: boolean
 }
 
 export interface HarnessEmbedRequest {
@@ -473,6 +474,10 @@ export interface HarnessDeleteSkillResponse {
   removed?: boolean
 }
 
+export interface HarnessKvCacheDeleteRequest {
+  kvCacheKey: string
+}
+
 export interface SchemaTypes {
   "@harness/empty": HarnessEmpty
   "@harness/ok-response": HarnessOkResponse
@@ -551,4 +556,5 @@ export interface SchemaTypes {
   "@harness/write-skill-request": HarnessWriteSkillRequest
   "@harness/copy-skill-response": HarnessCopySkillResponse
   "@harness/delete-skill-response": HarnessDeleteSkillResponse
+  "@harness/kv-cache-delete-request": HarnessKvCacheDeleteRequest
 }