@qvac/harness 0.8.6 → 0.8.8

package/dist-lib/lib/models/model-pool.d.ts

@@ -25,6 +25,7 @@ export interface Admission {
     release(): void;
 }
 export type BeforeLoad = (load: PendingLoad) => Promise<Admission | undefined>;
+export type ChooseContext = (load: PendingLoad, tier: number) => Promise<number>;
 export interface LlmDeviceConfig {
     device?: 'cpu' | 'gpu';
     gpuLayers?: number;
@@ -157,9 +158,10 @@ export interface ModelPoolOptions {
     deviceConfig?: LlmDeviceConfig;
     loads?: LoadTracker;
     beforeLoad?: BeforeLoad;
+    chooseContext?: ChooseContext;
     hold?: HoldFn;
 }
-export declare function createModelPool(loadSdk: LoadSdk, notify: NotifyFn, { deviceConfig, loads, beforeLoad, hold }?: ModelPoolOptions): ModelPuddle;
+export declare function createModelPool(loadSdk: LoadSdk, notify: NotifyFn, { deviceConfig, loads, beforeLoad, chooseContext, hold }?: ModelPoolOptions): ModelPuddle;
 export interface EmbedPoolOptions {
     faults: GpuFaultState;
     batchSize?: number;

package/dist-lib/lib/models/model-pool.js

@@ -357,12 +357,12 @@ export function loadClockGuard(model, sdk, { now = () => Date.now(), monoMs = mo
     };
     return { race };
 }
-export function createModelPool(loadSdk, notify, { deviceConfig = {}, loads = createLoadTracker(), beforeLoad, hold } = {}) {
+export function createModelPool(loadSdk, notify, { deviceConfig = {}, loads = createLoadTracker(), beforeLoad, chooseContext, hold } = {}) {
     const load = async (key, model, opts) => {
         const sdk = await loadSdk();
         const modelSrc = await resolveModelSrc(sdk, model);
         const resolved = resolveLoadOptions(opts, deviceConfig);
-        const ctxSize = resolved.ctxSize || defaultContextSize(modelSrc, customContextLength(model));
+        const tier = defaultContextSize(modelSrc, customContextLength(model));
         const projectionModelSrc = resolved.projectionModel
             ? await resolveModelSrc(sdk, resolved.projectionModel)
             : undefined;
@@ -376,11 +376,10 @@ export function createModelPool(loadSdk, notify, { deviceConfig = {}, loads = cr
         const openclCache = deviceConfig.device !== 'cpu' && deviceConfig.openclCacheDir
             ? deviceConfig.openclCacheDir()
             : undefined;
-        const modelConfig = definedFields({
+        const config = definedFields({
             verbosity: llmVerbosity(),
             tools: true,
             stop_sequences: RUNAWAY_STOP_SEQUENCES,
-            ctx_size: ctxSize,
             'cache-type-k': kvCache.k,
             'cache-type-v': kvCache.v,
             projectionModelSrc,
@@ -389,15 +388,13 @@ export function createModelPool(loadSdk, notify, { deviceConfig = {}, loads = cr
             'main-gpu': mainGpu,
             openclCacheDir: openclCache || undefined
         });
+        const pending = { key, model, modelSrc, modelType: 'llamacpp-completion' };
+        const ctxSize = resolved.ctxSize ||
+            (chooseContext ? await chooseContext({ ...pending, modelConfig: config }, tier) : tier);
+        const modelConfig = { ...config, ctx_size: ctxSize };
         const { projectionModelSrc: projection, ...loggedConfig } = modelConfig;
         hlog('llm load config', { model, projection: Boolean(projection), ...loggedConfig });
-        const admission = await beforeLoad?.({
-            key,
-            model,
-            modelSrc,
-            modelType: 'llamacpp-completion',
-            modelConfig
-        });
+        const admission = await beforeLoad?.({ ...pending, modelConfig });
         const loadStarted = Date.now();
         const modelId = await loadClockGuard(model, sdk)
             .race(loads.track(sdk.loadModel({

package/dist-lib/lib/models/sdk-faults.d.ts

@@ -1,6 +1,7 @@
 import type { EmbedDevice } from './embed-config.ts';
 export declare function isSdkGpuDeviceLostError(err: unknown): boolean;
 export declare function isSdkModelWedgedError(err: unknown): boolean;
+export declare function isGrammarOverrunError(err: unknown): boolean;
 export declare function isContextOverflowError(err: unknown): boolean;
 export type GpuFaultDecision = 'reload' | 'fallback';
 interface GpuFaultEscalation {

package/dist-lib/lib/models/sdk-faults.js

@@ -16,6 +16,12 @@ export function isSdkModelWedgedError(err) {
     }
     return /failed to (decode next token|eval chunk)/i.test(message);
 }
+export function isGrammarOverrunError(err) {
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const message = 'message' in err ? err.message : undefined;
+    return typeof message === 'string' && /empty grammar stack/i.test(message);
+}
 export function isContextOverflowError(err) {
     if (typeof err !== 'object' || err === null)
         return false;

package/dist-lib/lib/office/engine/pptx/picture-area.d.ts

@@ -0,0 +1,23 @@
+import type { Box } from './inherit.ts';
+import type { SlideSize } from './template.ts';
+export type Role = 'slot' | 'blank' | 'body' | 'picture' | 'other';
+export interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+export interface Placed {
+    readonly box: Box;
+    readonly role: Role;
+}
+export interface Beside<T> {
+    readonly shape: T;
+    readonly box: Box;
+}
+export interface Area<T> {
+    readonly box: Box;
+    readonly cleared: readonly T[];
+    readonly beside: Beside<T> | null;
+}
+export declare function framed(slide: SlideSize): Box;
+export declare function fitted(size: Size, area: Box): Box;
+export declare function pictureArea<T extends Placed>(slide: SlideSize, shapes: readonly T[]): Area<T>;

package/dist-lib/lib/office/engine/pptx/picture-area.js

@@ -0,0 +1,84 @@
+const FRAME = 0.8;
+const MARGIN = 0.03;
+const MIN_BAND = 0.15;
+const MIN_SPLIT = 0.5;
+export function framed(slide) {
+    return {
+        x: Math.round((slide.width * (1 - FRAME)) / 2),
+        y: Math.round((slide.height * (1 - FRAME)) / 2),
+        width: Math.round(slide.width * FRAME),
+        height: Math.round(slide.height * FRAME)
+    };
+}
+export function fitted(size, area) {
+    const scale = Math.min(area.width / size.width, area.height / size.height);
+    const width = Math.round(size.width * scale);
+    const height = Math.round(size.height * scale);
+    return {
+        x: area.x + Math.round((area.width - width) / 2),
+        y: area.y + Math.round((area.height - height) / 2),
+        width,
+        height
+    };
+}
+function bandBelow(slide, shapes, margin) {
+    const top = Math.max(...shapes.map(({ box }) => box.y + box.height)) + margin;
+    const band = {
+        x: margin,
+        y: top,
+        width: slide.width - 2 * margin,
+        height: slide.height - top - margin
+    };
+    return band.height >= slide.height * MIN_BAND ? band : null;
+}
+function halves(box, gap) {
+    if (box.width >= box.height) {
+        const half = Math.round((box.width - gap) / 2);
+        const rest = box.width - half - gap;
+        return [
+            { ...box, width: half },
+            { ...box, x: box.x + half + gap, width: rest }
+        ];
+    }
+    const half = Math.round((box.height - gap) / 2);
+    const rest = box.height - half - gap;
+    return [
+        { ...box, height: half },
+        { ...box, y: box.y + half + gap, height: rest }
+    ];
+}
+function split(shape, gap) {
+    const [kept, freed] = halves(shape.box, gap);
+    const box = shape.role === 'picture' ? fitted(shape.box, kept) : kept;
+    return { box: freed, cleared: [], beside: { shape, box } };
+}
+function largest(shapes) {
+    return shapes.reduce((best, shape) => !best || shape.box.width * shape.box.height > best.box.width * best.box.height ? shape : best, undefined);
+}
+function overlaps(a, b) {
+    return a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
+}
+function place(slide, shapes) {
+    const slot = shapes.find((shape) => shape.role === 'slot');
+    if (slot) {
+        return { box: slot.box, cleared: [slot], beside: null };
+    }
+    const whole = { box: framed(slide), cleared: [], beside: null };
+    if (!shapes.length) {
+        return whole;
+    }
+    const margin = Math.round(slide.height * MARGIN);
+    const band = bandBelow(slide, shapes, margin);
+    if (band) {
+        return { box: band, cleared: [], beside: null };
+    }
+    const bodies = shapes.filter((shape) => shape.role === 'body');
+    const wide = bodies.filter((shape) => shape.box.width >= slide.width * MIN_SPLIT);
+    const shared = largest(wide) ?? largest(shapes.filter((shape) => shape.role === 'picture')) ?? largest(bodies);
+    return shared ? split(shared, margin) : whole;
+}
+export function pictureArea(slide, shapes) {
+    const area = place(slide, shapes.filter((shape) => shape.role !== 'blank'));
+    const covered = shapes.filter((shape) => shape.role === 'blank' && overlaps(shape.box, area.box));
+    return { ...area, cleared: [...area.cleared, ...covered] };
+}

package/dist-lib/lib/office/engine/pptx/presentation.d.ts

@@ -50,5 +50,7 @@ export declare class Presentation {
     private chartOf;
     private chartPart;
     private box;
+    private narrow;
+    private pictureArea;
     private pictureBox;
 }

package/dist-lib/lib/office/engine/pptx/presentation.js

@@ -12,6 +12,7 @@ import * as fit from './fit.js';
 import * as template from './template.js';
 import * as slides from './slides.js';
 import * as notes from './notes.js';
+import { fitted, framed, pictureArea } from './picture-area.js';
 import { pick, describe, layoutName, layoutType, BODY_TYPES } from './read.js';
 import { SHAPE_ORDER, shapesOf, placeholderFrom, pictureElement, textBoxElement, tableElement, chartFrameElement, setBackground, nextShapeId } from './shapes.js';
 const { a: A, p: P, r: R, p14: P14 } = xml.ns;
@@ -154,16 +155,19 @@ function checkSlideText(doc, at, opts) {
         }
     }
 }
-function fitted(info, current) {
-    const scale = Math.min(current.width / info.width, current.height / info.height);
-    const width = Math.round(info.width * scale);
-    const height = Math.round(info.height * scale);
-    return {
-        x: current.x + Math.round((current.width - width) / 2),
-        y: current.y + Math.round((current.height - height) / 2),
-        width,
-        height
-    };
+function roleOf(shape) {
+    const { el, kind, placeholder } = shape;
+    if (kind === 'picture') {
+        return 'picture';
+    }
+    if (el.localName !== 'sp' || !placeholder || !BODY_TYPES.has(placeholder)) {
+        return 'other';
+    }
+    const txBody = xml.child(el, P, 'txBody');
+    if (txBody && text.readParagraphs(txBody).some((p) => p.text.trim())) {
+        return placeholder === 'subTitle' ? 'other' : 'body';
+    }
+    return placeholder === 'obj' ? 'slot' : 'blank';
 }
 function tableBody(tc) {
     const existing = xml.child(tc, A, 'txBody');
@@ -366,6 +370,9 @@ export class Presentation {
         const layoutDoc = this.package.xml(layout);
         const doc = slideFromLayout(layoutDoc);
         checkSlideText(doc, at, opts);
+        if (opts.image !== undefined) {
+            probe(opts.image);
+        }
         this.insertSlide({ doc, layout, at, ids: all.map((e) => e.id), before: all[at]?.el ?? null });
         if (opts.title !== undefined) {
             this.setText({ slide: at, shape: 'title' }, opts.title);
@@ -373,14 +380,25 @@ export class Presentation {
         if (opts.body !== undefined) {
             this.setText({ slide: at, shape: 'body' }, opts.body);
         }
-        return { index: at, layout: layoutName(layoutDoc), shapes: shapesOf(doc).map(describe) };
+        if (opts.image !== undefined) {
+            this.addPicture(at, opts.image);
+        }
+        const shapes = shapesOf(this.package.xml(slides.slideAt(this.deck, at).part));
+        return { index: at, layout: layoutName(layoutDoc), shapes: shapes.map(describe) };
     }
     addPicture(slide, bytes, opts = {}) {
         const entry = slides.slideAt(this.deck, slide);
-        const box = this.pictureBox(probe(bytes), opts);
+        const area = this.pictureArea(entry.part, opts);
+        const box = this.pictureBox(probe(bytes), opts, area.box);
         const { rId } = media.addImage(this.package, bytes, { source: entry.part, dir: '../media' });
         const doc = this.package.xml(entry.part);
         const id = nextShapeId(doc);
+        for (const shape of area.cleared) {
+            xml.remove(shape.el);
+        }
+        if (area.beside) {
+            this.narrow(entry.part, area.beside);
+        }
         this.spTree(entry.part).appendChild(pictureElement(doc, { id, rId, box, name: opts.name, description: opts.description }));
         this.package.touch(entry.part);
         return { id, ...box };
@@ -722,14 +740,34 @@ export class Presentation {
         }
         return box;
     }
-    pictureBox(info, opts) {
+    narrow(part, { shape, box }) {
+        writeXfrm(shape.el, box);
+        const txBody = xml.child(shape.el, P, 'txBody');
+        const estimate = txBody ? this.estimate(part, shape.el, txBody) : null;
+        if (txBody && estimate?.overflow) {
+            applyAutofit(txBody, estimate);
+        }
+    }
+    pictureArea(part, opts) {
+        if (opts.x !== undefined || opts.y !== undefined) {
+            return { box: framed(this.slideSize), cleared: [], beside: null };
+        }
+        const shapes = shapesOf(this.package.xml(part)).flatMap((shape) => {
+            if (shape.group !== null || SKIPPED_PLACEHOLDERS.has(shape.placeholder ?? '')) {
+                return [];
+            }
+            const box = inherit.box({ pkg: this.package, slide: part, el: shape.el });
+            return box ? [{ el: shape.el, box, role: roleOf(shape) }] : [];
+        });
+        return pictureArea(this.slideSize, shapes);
+    }
+    pictureBox(info, opts, area) {
         checkPlacement(opts);
-        const slide = this.slideSize;
         const ratio = info.height / info.width;
         let { width, height } = opts;
         if (width === undefined && height === undefined) {
             const natural = { width: info.width * EMU_PER_PIXEL, height: info.height * EMU_PER_PIXEL };
-            const scale = Math.min(1, (slide.width * 0.8) / natural.width, (slide.height * 0.8) / natural.height);
+            const scale = Math.min(1, area.width / natural.width, area.height / natural.height);
             width = Math.round(natural.width * scale);
             height = Math.round(natural.height * scale);
         }
@@ -742,8 +780,8 @@ export class Presentation {
         if (!width || !height) {
             throw new DocsError('INVALID_BOX', 'the picture would have no visible size');
         }
-        const x = opts.x ?? Math.max(0, Math.round((slide.width - width) / 2));
-        const y = opts.y ?? Math.max(0, Math.round((slide.height - height) / 2));
+        const x = opts.x ?? Math.max(0, area.x + Math.round((area.width - width) / 2));
+        const y = opts.y ?? Math.max(0, area.y + Math.round((area.height - height) / 2));
         return { x, y, width, height };
     }
 }

package/dist-lib/lib/office/engine/pptx/types.d.ts

@@ -61,6 +61,7 @@ export interface AddSlideOptions {
     at?: number;
     title?: TextInput;
     body?: TextInput;
+    image?: Uint8Array;
 }
 export interface AddedSlide {
     index: number;

package/dist-lib/lib/office/engine/xlsx/workbook.d.ts

@@ -156,6 +156,7 @@ export declare class Workbook {
     private ownCharts;
     private rangeValues;
     private besideData;
+    private rowsBelowDrawings;
     private drawingOf;
     private ensureDrawing;
 }

package/dist-lib/lib/office/engine/xlsx/workbook.js

@@ -2,6 +2,7 @@ import { Package } from '../opc/package.js';
 import * as xml from '../xml.js';
 import * as media from '../opc/media.js';
 import { probe } from '../image.js';
+import { points } from '../units.js';
 import * as refs from './refs.js';
 import * as formula from './formula.js';
 import { Sheet, SHEET_ORDER } from './sheet.js';
@@ -170,6 +171,12 @@ function pictureAnchor(doc, anchor, spec) {
     root.appendChild(d('clientData'));
     return root;
 }
+function markerCell(marker) {
+    return {
+        row: Number(xml.text(xml.child(marker, XDR, 'row'))),
+        col: Number(xml.text(xml.child(marker, XDR, 'col')))
+    };
+}
 function nextDrawingId(doc) {
     return (Math.max(0, ...xml.descendants(doc, XDR, 'cNvPr').map((el) => Number(el.getAttribute('id')) || 0)) + 1);
 }
@@ -421,7 +428,7 @@ export class Workbook {
         const target = this.sheet(sheet);
         const info = probe(bytes);
         const o = isRecord(opts) ? opts : {};
-        const at = refs.parse(o.cell === undefined ? 'A1' : o.cell);
+        const at = o.cell === undefined ? this.besideData(target) : refs.parse(o.cell);
         const size = imageSize(o, info);
         const drawing = this.ensureDrawing(target);
         const { rId } = media.addImage(this.package, bytes, { source: drawing, dir: '../media' });
@@ -791,7 +798,8 @@ export class Workbook {
             const from = xml.child(anchor, XDR, 'from');
             const info = chart.readChart(this.package.xml(rel.part));
             if (from) {
-                info.cell = refs.cell(Number(xml.text(xml.child(from, XDR, 'row'))), Number(xml.text(xml.child(from, XDR, 'col'))));
+                const { row, col } = markerCell(from);
+                info.cell = refs.cell(row, col);
             }
             out.push(info);
         }
@@ -823,7 +831,30 @@ export class Workbook {
     }
     besideData(sheet) {
         const used = sheet.usedRange();
-        return used ? { row: used.top, col: used.right + 2 } : { row: 0, col: 0 };
+        const col = used ? used.right + 2 : 0;
+        return { row: Math.max(used ? used.top : 0, ...this.rowsBelowDrawings(sheet, col)), col };
+    }
+    rowsBelowDrawings(sheet, col) {
+        const drawing = this.drawingOf(sheet);
+        if (!drawing) {
+            return [];
+        }
+        const format = xml.child(sheet.root, X, 'sheetFormatPr');
+        const rowHeight = points(Number(format?.getAttribute('defaultRowHeight') ?? 15));
+        return xml.children(this.package.root(drawing), XDR).flatMap((anchor) => {
+            const from = xml.child(anchor, XDR, 'from');
+            if (!from || markerCell(from).col !== col) {
+                return [];
+            }
+            const to = xml.child(anchor, XDR, 'to');
+            if (to) {
+                return [markerCell(to).row + 2];
+            }
+            const ext = xml.child(anchor, XDR, 'ext');
+            return ext
+                ? [markerCell(from).row + Math.ceil(Number(ext.getAttribute('cy')) / rowHeight) + 1]
+                : [];
+        });
     }
     drawingOf(sheet) {
         const ref = xml.child(sheet.root, X, 'drawing');

package/dist-lib/lib/serve.js

@@ -8,7 +8,7 @@ import HRPC from '../spec/hrpc/index.js';
 import { isCapability } from './capabilities/invoke.js';
 import { CUSTOM_TASK_TYPES } from './models/model-catalog.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
-import { errorMessage } from './guards.js';
+import { errorMessage, isRecord } from './guards.js';
 import { hlog } from './log.js';
 import { pushQueue } from './queue.js';
 import { TextCoalescer } from './helpers/text-coalescer.js';
@@ -236,6 +236,7 @@ function toWireSkill(skill) {
     }));
     return {
         name: skill.name,
+        displayName: skill.displayName || undefined,
         description: skill.description,
         tools: skill.tools,
         credentials: skill.credentials,
@@ -525,10 +526,14 @@ function completion(harness) {
                 model: frame.model ?? '',
                 agent: frame.agent ?? {},
                 cacheKey: frame.cacheKey ?? undefined,
+                session: frame.session ?? undefined,
                 thinkingDefault: frame.thinkingDefault ?? undefined,
                 generationParams: frame.generationParams ?? undefined,
                 responseFormat: frame.responseFormat ?? undefined,
                 captureInferenceCalls: frame.captureInferenceCalls ?? undefined,
+                typedText: isRecord(frame.payload) && typeof frame.payload.typedText === 'string'
+                    ? frame.payload.typedText
+                    : undefined,
                 messages: (frame.messages ?? []).map(({ role, content, attachments }) => ({
                     role,
                     content,

package/dist-lib/lib/spawn.js

@@ -46,9 +46,8 @@ export function spawnHarness(opts) {
         batchSize: opts.embedBatchSize
     });
     return connectHarness(async () => {
-        const { default: Sidecar } = await import('bare-sidecar');
-        const { wrap } = await import('bare-stow/host');
-        const sidecar = new Sidecar(opts.entry, [
+        const { default: launch } = await import('bare-supervisor/runner/sidecar');
+        const { ipc, exit } = launch(opts.entry, [
             opts.skillsDir ?? '',
             JSON.stringify(opts.sdkStorage),
             JSON.stringify(embedConfig),
@@ -60,13 +59,8 @@ export function spawnHarness(opts) {
             opts.musicClamps ? JSON.stringify(opts.musicClamps) : '',
             opts.wheelsDir ?? '',
             opts.gpuStats === undefined ? '' : JSON.stringify(opts.gpuStats)
-        ]);
-        sidecar.stdout.on('data', (data) => logger?.info('harness', data.toString().trimEnd()));
-        sidecar.stderr.on('data', (data) => logger?.warn('harness', data.toString().trimEnd()));
-        const ipc = wrap(sidecar);
-        const died = new Promise((resolve) => {
-            sidecar.once('exit', (code) => resolve(`harness exited (${code}) before ready`));
-        });
+        ], logger);
+        const died = exit.then((code) => `harness exited (${code}) before ready`);
         const failure = await Promise.race([ipc.ready.then(() => null), died]);
         if (failure) {
             throw new Error(failure);

package/dist-lib/lib/tools/exec.d.ts

@@ -14,6 +14,7 @@ export interface ExecToolOptions {
     readonly pythonNetwork?: boolean;
     readonly credentialStore?: CredentialStoreFn;
     readonly skillSettings?: SkillSettingsFn;
+    readonly skillEnv?: SkillEnvFn;
     readonly realpath?: Realpath;
     readonly deniedRoots?: readonly string[];
     readonly skillsDir?: string;
@@ -23,4 +24,6 @@ export interface ScriptRun {
     trusted: boolean;
 }
 export declare function resolveScriptRun(rawArgs: Record<string, unknown>, skillsDir: string | undefined): ScriptRun | ExecError | null;
-export declare function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide, pythonNetwork, credentialStore, skillSettings, realpath, deniedRoots, skillsDir }?: ExecToolOptions): ToolDefinition;
+export type SkillEnvFn = (skill: string) => Readonly<Record<string, string>> | undefined;
+export declare function declaredEnv(declared: Readonly<Record<string, string>> | undefined, session: string | undefined): Record<string, string>;
+export declare function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide, pythonNetwork, credentialStore, skillSettings, skillEnv, realpath, deniedRoots, skillsDir }?: ExecToolOptions): ToolDefinition;

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

@@ -6,7 +6,7 @@ import { namedHosts } from './exec/adapters/python/named-hosts.js';
 import { pythonReachesNetwork } from './exec/adapters/python/net-shim.js';
 import { createShellAdapter } from './exec/adapters/shell/shell-adapter.js';
 import { routeObsidianCommand } from './exec/obsidian/route.js';
-import { MAX_OUTPUT_CHARS_LIMIT } from './exec/runner.js';
+import { MAX_OUTPUT_CHARS, MAX_OUTPUT_CHARS_LIMIT, TRUNCATED_OUTPUT_SUFFIX } from './exec/runner.js';
 import { bareBin, firstCommandToken, sanitizeCommand } from './exec/scope.js';
 import { FILES_NEED_PYTHON_ERROR, isPythonSourceShaped, PACKAGES_NEED_PYTHON_ERROR, pythonRedirectError, startsLikePython, videoToolError } from './exec/shell-guidance.js';
 import { shellArgv } from './exec/shell-argv.js';
@@ -47,6 +47,30 @@ function shellEffect(command, toolOps) {
     }
     return matched.every((op) => op.annotation(argv) === 'read') ? 'read' : 'write';
 }
+function shellOutputCap(command, toolOps) {
+    const { ops, argv } = resolveShellOps(command, toolOps);
+    const caps = ops.map((op) => op.outputCap(argv)).filter((cap) => cap !== undefined);
+    return caps.length > 0 ? Math.min(...caps) : undefined;
+}
+function noteCeiling(result, ceiling) {
+    if (!result || typeof result !== 'object')
+        return result;
+    const out = { ...result };
+    for (const stream of ['stdout', 'stderr']) {
+        const text = out[stream];
+        if (typeof text === 'string' && text.endsWith(TRUNCATED_OUTPUT_SUFFIX)) {
+            out[stream] =
+                text.slice(0, -TRUNCATED_OUTPUT_SUFFIX.length) +
+                    `… [truncated at this skill's ${ceiling}-character limit for this command; a larger maxOutputChars does not apply]`;
+        }
+    }
+    return out;
+}
+function cappedOutput(requested, ceiling) {
+    if (ceiling === undefined)
+        return requested;
+    return Math.min(requested ?? MAX_OUTPUT_CHARS, ceiling);
+}
 function resolveExecution({ adapters, fallback }, args, ctx) {
     for (const adapter of adapters) {
         const plan = adapter.resolve(args, ctx);
@@ -289,18 +313,33 @@ function checkExecutionScope(args, { toolOps, disablePyodide, sandbox, network }
     }
     return checkShellScope(command, toolOps);
 }
-async function skillsEnv(skillSettings, ctx) {
+async function skillsEnv(skillSettings, skillEnv, ctx) {
     const skills = ctx?.skills ?? [];
     if (skills.length === 0) {
         return undefined;
     }
     const env = {};
     for (const skill of skills) {
-        Object.assign(env, settingsEnv(skill, await skillSettings(skill, ctx?.agentId)));
+        if (skillSettings) {
+            Object.assign(env, settingsEnv(skill, await skillSettings(skill, ctx?.agentId)));
+        }
+        Object.assign(env, declaredEnv(skillEnv?.(skill), ctx?.session));
     }
     return Object.keys(env).length > 0 ? env : undefined;
 }
-export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide = false, pythonNetwork = !disablePyodide && pythonReachesNetwork(), credentialStore, skillSettings, realpath = defaultRealpath, deniedRoots, skillsDir } = {}) {
+export function declaredEnv(declared, session) {
+    const env = {};
+    for (const [name, value] of Object.entries(declared ?? {})) {
+        if (!value.includes('${session}')) {
+            env[name] = value;
+        }
+        else if (session) {
+            env[name] = value.replaceAll('${session}', session);
+        }
+    }
+    return env;
+}
+export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide = false, pythonNetwork = !disablePyodide && pythonReachesNetwork(), credentialStore, skillSettings, skillEnv, realpath = defaultRealpath, deniedRoots, skillsDir } = {}) {
     const adapters = [createPythonAdapter(disablePyodide, loadPyodide, pythonNetwork)];
     const fallback = createShellAdapter({ spawn, killProcess, loadRuntime: bareRuntime });
     return {
@@ -349,7 +388,7 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
                 },
                 maxOutputChars: {
                     type: 'number',
-                    description: 'Optional stdout/stderr cap in characters (default 8192, max 65536). Raise when reading long content, e.g. a full note.'
+                    description: 'Optional stdout/stderr cap in characters (default 8192, max 65536). Raise when reading long content, e.g. a full note. A skill may cap one of its commands lower; the truncation note says so, and raising this does not lift that cap.'
                 },
                 script: {
                     type: 'string',
@@ -564,10 +603,12 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
                     timeout = Math.min(timeout, remaining);
                 }
             }
-            const maxOutputChars = parsePositiveInt(rawArgs.maxOutputChars, 'maxOutputChars', MAX_OUTPUT_CHARS_LIMIT);
-            if (maxOutputChars && typeof maxOutputChars === 'object') {
-                return maxOutputChars;
+            const requestedCap = parsePositiveInt(rawArgs.maxOutputChars, 'maxOutputChars', MAX_OUTPUT_CHARS_LIMIT);
+            if (requestedCap && typeof requestedCap === 'object') {
+                return requestedCap;
             }
+            const ceiling = shellOutputCap(command, ctx?.toolOps);
+            const maxOutputChars = cappedOutput(requestedCap, ceiling);
             if (!isPythonLanguage(rawArgs.language)) {
                 const obsidian = await routeObsidianCommand(command, ctx, {
                     credentialStore,
@@ -581,7 +622,7 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
                     return obsidian;
                 }
             }
-            const skillEnv = skillSettings ? await skillsEnv(skillSettings, ctx) : undefined;
+            const childEnv = await skillsEnv(skillSettings, skillEnv, ctx);
             try {
                 const execution = resolveExecution({ adapters, fallback }, rawArgs, {
                     attach: ctx?.attach,
@@ -593,13 +634,16 @@ export function createExecTool({ spawn, killProcess, loadPyodide, disablePyodide
                     approval: ctx?.approval,
                     confirmConnect: ctx?.askUser ? connectAsker(ctx.askUser) : undefined
                 });
-                return await execution.run({
+                const result = await execution.run({
                     cwd,
                     timeoutMs: timeout,
                     maxOutputChars,
                     signal: ctx?.signal,
-                    env: skillEnv
+                    env: childEnv
                 });
+                return ceiling !== undefined && maxOutputChars === ceiling
+                    ? noteCeiling(result, ceiling)
+                    : result;
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));

package/dist-lib/lib/tools/file-glob.js

@@ -57,6 +57,7 @@ export function createFileGlobTool({ realpath = defaultRealpath, deniedRoots } =
             required: ['pattern']
         },
         effect: () => 'read',
+        stableRead: true,
         autoApprove: true,
         rootsRequired: true,
         validate(rawArgs) {

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

@@ -99,6 +99,7 @@ export function createGrepTool({ realpath = defaultRealpath, deniedRoots } = {})
             required: ['queries']
         },
         effect: () => 'read',
+        stableRead: true,
         autoApprove: true,
         rootsRequired: true,
         validate(rawArgs) {