@kruntime/komputer 0.1.0 → 0.1.2

package/dist/agent/approvals.js

@@ -96,7 +96,12 @@ export function resultSummary(value) {
     return { type: typeof value };
 }
 function approvalActionKey(hook, current) {
-    return sha256(stableJson({ hook, current }));
+    return sha256(stableJson({ hook, current: approvalActionCurrent(current) }));
+}
+function approvalActionCurrent(current) {
+    const copy = { ...current };
+    delete copy.execToolUseId;
+    return copy;
 }
 function stableJson(value) {
     if (value === null || typeof value !== 'object')

package/dist/agent/approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../../../../packages/komputer/src/agent/approvals.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"approvals.js","sourceRoot":"","sources":["../../../../../packages/komputer/src/agent/approvals.ts"],"names":[],"mappings":"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"}

package/dist/agent-session.d.ts

@@ -37,6 +37,7 @@ export interface ExecOptions {
 }
 type ExecShellOptions = ExecOptions & {
     forceRemote?: boolean;
+    execToolUseId?: string;
 };
 interface TurnEndPayload {
     turnId: string;

package/dist/agent-session.js

@@ -594,10 +594,24 @@ export class AgentSession {
             return this.send(current.content, recordField(current, 'options') || {});
         }
         if (hook === 'shell.before' || hook === 'cmd.before') {
-            return this.execInternal(stringField(current, 'shellScript') || stringField(current, 'script'), {
+            const result = await this.execInternal(stringField(current, 'shellScript') || stringField(current, 'script'), {
                 by: stringField(current, 'by') || `approval:${approval.id}`,
                 foreground: typeof current.foreground === 'boolean' ? current.foreground : undefined,
             });
+            const execToolUseId = stringField(current, 'execToolUseId');
+            if (execToolUseId) {
+                const bounded = this.boundShellResult(result);
+                await this.appendExecToolExchange(execToolUseMessageFromApproval(current, execToolUseId), execToolUseId, bounded, stringField(current, 'by') || `approval:${approval.id}`);
+                await this.emit({
+                    type: 'tool',
+                    status: shellToolEventStatus(bounded),
+                    tool: 'shell',
+                    result: bounded,
+                    opId: execToolUseId,
+                    approvalId: approval.id,
+                });
+            }
+            return result;
         }
         if (hook === 'tool.before') {
             return this.command(stringField(current, 'command'), recordField(current, 'input') || {}, {
@@ -1060,10 +1074,20 @@ export class AgentSession {
         };
         try {
             await this.emit({ type: 'tool', status: 'requested', tool: 'shell', input: toolUseMessage.content[0]?.input, opId: toolUseId });
-            const result = await this.execShell(command, options);
+            const result = await this.execShell(command, { ...options, execToolUseId: toolUseId });
             const bounded = this.boundShellResult(result);
-            await this.appendExecToolExchange(toolUseMessage, toolUseId, bounded, by);
-            await this.emit({ type: 'tool', status: bounded.code === 0 ? 'completed' : 'failed', tool: 'shell', result: bounded, opId: toolUseId });
+            const toolStatus = shellToolEventStatus(bounded);
+            if (toolStatus !== 'waiting_approval') {
+                await this.appendExecToolExchange(toolUseMessage, toolUseId, bounded, by);
+            }
+            await this.emit({
+                type: 'tool',
+                status: toolStatus,
+                tool: 'shell',
+                result: bounded,
+                opId: toolUseId,
+                approvalId: stringField(recordField(bounded, 'approval') || {}, 'id'),
+            });
             return bounded;
         }
         catch (error) {
@@ -1134,7 +1158,7 @@ export class AgentSession {
         const shell = String(command);
         const foreground = options.foreground ?? !shell.trimEnd().endsWith('&');
         let script = foreground ? shell : shell.trimEnd().replace(/&\s*$/, '');
-        const beforeShell = await this.runHook('shell.before', { script, cwd: this.hookCwd(), by: normalizeBy(options.by) });
+        const beforeShell = await this.runHook('shell.before', { script, cwd: this.hookCwd(), by: normalizeBy(options.by), foreground, execToolUseId: options.execToolUseId });
         if (beforeShell.rejected) {
             await this.trace('process.rejected', { script, reason: beforeShell.reason });
             if (beforeShell.waitingApproval) {
@@ -1184,6 +1208,7 @@ export class AgentSession {
                 by: normalizeBy(options.by),
                 foreground: foreground && !concrete.background,
                 background: !foreground || concrete.background,
+                execToolUseId: options.execToolUseId,
             });
             if (beforeCmd.rejected) {
                 await this.trace('process.rejected', { cmd: concrete.cmd, args: concrete.args, reason: beforeCmd.reason });
@@ -2621,6 +2646,9 @@ export class AgentSession {
             throw new Error(`command not found: ${name}`);
         if (command.agent && command.agent !== this.agentName)
             throw new Error(`command ${name} belongs to agent ${command.agent}`);
+        if (isCommandHelpInput(input)) {
+            return { type: 'stdout', text: `${commandHelpText(name, command)}\n`, code: 0 };
+        }
         const by = normalizeBy(options.by || (typeof input.by === 'string' ? input.by : undefined));
         const toolName = `command:${name}`;
         const before = await this.runHook('tool.before', { tool: toolName, command: name, input, by });
@@ -2637,7 +2665,16 @@ export class AgentSession {
             throw new Error(authority.reason);
         }
         const toolUseId = id('tool');
-        const ctx = this.runtime.runtimeContext(this, { kind: 'command', name, input: currentInput, args: currentInput });
+        const parsed = parseCommandInput(name, command, currentInput);
+        const ctx = this.runtime.runtimeContext(this, {
+            kind: 'command',
+            name,
+            input: currentInput,
+            args: parsed.args,
+            argv: parsed.argv,
+            stdin: parsed.stdin,
+            env: parsed.env,
+        });
         await this.emit({ type: 'tool', status: 'requested', tool: toolName, input: currentInput, opId: toolUseId });
         await this.trace('tool.started', { name, input: currentInput, by, toolUseId });
         let result;
@@ -2652,20 +2689,30 @@ export class AgentSession {
             result = invocationMode ? await this.withTemporaryMode(invocationMode, runShell) : await runShell();
         }
         else if (command.kind === 'markdown') {
-            const args = Object.keys(currentInput).length ? `\n\nInput:\n${JSON.stringify(currentInput, null, 2)}` : '';
+            const prompt = String(command.prompt ?? '');
+            const rendered = renderMarkdownCommandPrompt(prompt, parsed.args, parsed.stdin);
+            const args = hasCommandTemplate(prompt) || Object.keys(currentInput).length === 0
+                ? ''
+                : `\n\nInput:\n${JSON.stringify(currentInput, null, 2)}`;
             const invocationMode = command.readonly === true
                 ? 'readonly'
                 : typeof command.mode === 'string'
                     ? command.mode
                     : undefined;
-            const runMarkdown = () => this.run(`${String(command.prompt ?? '')}${args}`, { by: options.by || `command:${name}`, model: typeof command.model === 'string' ? command.model : undefined });
+            const runMarkdown = () => this.run(`${rendered}${args}`, { by: options.by || `command:${name}`, model: typeof command.model === 'string' ? command.model : undefined });
             result = invocationMode ? await this.withTemporaryMode(invocationMode, runMarkdown) : await runMarkdown();
         }
         else {
-            if (!command.handler)
-                throw new Error(`command has no handler: ${name}`);
-            const handler = command.handler;
-            result = await this.withFsActor(options.by ? by : `command:${name}`, () => Promise.resolve(handler(ctx, currentInput)));
+            const main = command.main ?? command.handler;
+            if (!main)
+                throw new Error(`command has no main: ${name}`);
+            const runModule = () => this.withFsActor(options.by ? by : `command:${name}`, () => Promise.resolve(main(ctx, parsed.args)));
+            const invocationMode = command.readonly === true
+                ? 'readonly'
+                : typeof command.mode === 'string'
+                    ? command.mode
+                    : undefined;
+            result = invocationMode ? await this.withTemporaryMode(invocationMode, runModule) : await runModule();
         }
         const after = await this.runHook('tool.after', { tool: toolName, command: name, input: currentInput, result, by });
         if (after.rejected) {
@@ -2967,6 +3014,169 @@ function commandErrorText(command, error) {
 function isHelpArg(value) {
     return value === '--help' || value === '-h';
 }
+function isCommandHelpInput(input) {
+    const argv = stringArrayField(input, 'argv') || [];
+    return argv.length === 1 && isHelpArg(argv[0]);
+}
+function parseCommandInput(name, command, input) {
+    const argv = stringArrayField(input, 'argv') || [];
+    const stdin = typeof input.stdin === 'string' ? input.stdin : '';
+    const envRecord = recordField(input, 'env');
+    const env = envRecord ? stringRecord(envRecord) : undefined;
+    if (command.args === 'none') {
+        const extra = argv.filter((arg) => arg !== '--');
+        if (extra.length)
+            throw new Error(`${name}: unexpected argument: ${extra[0]}`);
+        return { argv, stdin, env, args: {} };
+    }
+    if (!command.args || command.args === 'argv')
+        return { argv, stdin, env, args: input };
+    return { argv, stdin, env, args: parseStructuredCommandArgs(name, command.args, input, argv) };
+}
+function parseStructuredCommandArgs(name, specs, input, argv) {
+    const parsed = {};
+    const options = commandOptionSpecs(specs);
+    for (const [key, spec] of Object.entries(specs)) {
+        if ('default' in spec)
+            parsed[key] = spec.default;
+        else if ('defaultValue' in spec)
+            parsed[key] = spec.defaultValue;
+    }
+    for (const [key, value] of Object.entries(input)) {
+        if (key !== 'argv' && key !== 'stdin' && key !== 'env' && specs[key])
+            parsed[key] = value;
+    }
+    const positional = Object.entries(specs)
+        .filter(([, spec]) => typeof spec.position === 'number')
+        .sort((a, b) => Number(a[1].position) - Number(b[1].position));
+    let positionalIndex = 0;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--') {
+            for (const rest of argv.slice(index + 1))
+                assignPositional(name, parsed, positional, positionalIndex++, rest);
+            break;
+        }
+        if (token.startsWith('--')) {
+            const body = token.slice(2);
+            const eq = body.indexOf('=');
+            const option = eq >= 0 ? body.slice(0, eq) : body;
+            const resolved = options.get(option);
+            if (!resolved)
+                throw new Error(`${name}: unsupported option: --${option}`);
+            const [key, spec] = resolved;
+            if (spec.type === 'boolean' && eq < 0) {
+                parsed[key] = true;
+                continue;
+            }
+            const value = eq >= 0 ? body.slice(eq + 1) : argv[++index];
+            if (value === undefined)
+                throw new Error(`${name}: option requires an argument: --${key}`);
+            assignCommandArg(name, parsed, key, spec, value);
+            continue;
+        }
+        const eq = token.indexOf('=');
+        if (eq > 0 && specs[token.slice(0, eq)]) {
+            const key = token.slice(0, eq);
+            assignCommandArg(name, parsed, key, specs[key], token.slice(eq + 1));
+            continue;
+        }
+        assignPositional(name, parsed, positional, positionalIndex++, token);
+    }
+    for (const [key, spec] of Object.entries(specs)) {
+        if (spec.required === true && (parsed[key] === undefined || parsed[key] === '')) {
+            throw new Error(`${name}: missing required argument: --${key}`);
+        }
+        if (parsed[key] !== undefined)
+            parsed[key] = coerceCommandArg(name, key, spec, parsed[key]);
+    }
+    return parsed;
+}
+function commandOptionSpecs(specs) {
+    const options = new Map();
+    for (const [key, spec] of Object.entries(specs)) {
+        options.set(key, [key, spec]);
+        const flag = typeof spec.flag === 'string' ? normalizeCommandFlag(spec.flag) : undefined;
+        if (flag)
+            options.set(flag, [key, spec]);
+    }
+    return options;
+}
+function normalizeCommandFlag(flag) {
+    return flag.trim().replace(/^-+/, '');
+}
+function assignPositional(name, parsed, positional, index, value) {
+    const entry = positional[index];
+    if (!entry)
+        throw new Error(`${name}: unexpected argument: ${String(value)}`);
+    assignCommandArg(name, parsed, entry[0], entry[1], value);
+}
+function assignCommandArg(name, parsed, key, spec, value) {
+    const coerced = coerceCommandArg(name, key, spec, value);
+    if (spec.repeat) {
+        const current = Array.isArray(parsed[key]) ? parsed[key] : parsed[key] === undefined ? [] : [parsed[key]];
+        current.push(coerced);
+        parsed[key] = current;
+        return;
+    }
+    parsed[key] = coerced;
+}
+function coerceCommandArg(name, key, spec, value) {
+    if (value === undefined)
+        return value;
+    if (spec.type === 'string' || spec.type === 'path')
+        return String(value);
+    if (spec.type === 'number') {
+        const number = typeof value === 'number' ? value : Number(String(value));
+        if (!Number.isFinite(number))
+            throw new Error(`${name}: invalid value for --${key}: expected number`);
+        return number;
+    }
+    if (spec.type === 'boolean') {
+        if (typeof value === 'boolean')
+            return value;
+        const text = String(value).toLowerCase();
+        if (text === 'true' || text === '1' || text === 'yes')
+            return true;
+        if (text === 'false' || text === '0' || text === 'no')
+            return false;
+        throw new Error(`${name}: invalid value for --${key}: expected boolean`);
+    }
+    if (spec.type === 'json') {
+        if (typeof value !== 'string')
+            return value;
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            throw new Error(`${name}: invalid value for --${key}: expected json`);
+        }
+    }
+    return value;
+}
+function stringRecord(record) {
+    const output = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (typeof value === 'string')
+            output[key] = value;
+    }
+    return output;
+}
+function hasCommandTemplate(prompt) {
+    return /\{\{\s*(?:arg|args)\.[A-Za-z0-9_.-]+\s*\}\}|\{\{\s*stdin\s*\}\}/.test(prompt);
+}
+function renderMarkdownCommandPrompt(prompt, args, stdin) {
+    return prompt.replace(/\{\{\s*((?:arg|args)\.([A-Za-z0-9_.-]+)|stdin)\s*\}\}/g, (_match, token, argName) => {
+        if (token === 'stdin')
+            return stdin;
+        const value = argName ? args[argName] : undefined;
+        if (value === undefined || value === null)
+            return '';
+        if (typeof value === 'string')
+            return value;
+        return JSON.stringify(value);
+    });
+}
 function isExpiredWorker(worker) {
     const expiresAt = typeof worker.expiresAt === 'string' ? Date.parse(worker.expiresAt) : Number.NaN;
     return Number.isFinite(expiresAt) && expiresAt <= Date.now();
@@ -3010,6 +3220,32 @@ function turnStatus(status) {
         return 'cancelled';
     return 'completed';
 }
+function shellToolEventStatus(result) {
+    if (result.status === 'waiting_approval')
+        return 'waiting_approval';
+    if (result.status === 'committed' || result.status === 'completed')
+        return 'completed';
+    if (typeof result.code === 'number')
+        return result.code === 0 ? 'completed' : 'failed';
+    return 'failed';
+}
+function execToolUseMessageFromApproval(current, toolUseId) {
+    const script = stringField(current, 'shellScript') || stringField(current, 'script');
+    return {
+        role: 'assistant',
+        by: stringField(current, 'by') || 'approval',
+        content: [{
+                type: 'tool_use',
+                id: toolUseId,
+                name: 'shell',
+                input: {
+                    script,
+                    cwd: stringField(current, 'cwd'),
+                    foreground: typeof current.foreground === 'boolean' ? current.foreground : undefined,
+                },
+            }],
+    };
+}
 function shouldExpandBraces(token) {
     let hasUnquotedBrace = false;
     for (const part of token.parts) {