@kruntime/komputer 0.1.0

package/README.md

@@ -0,0 +1,368 @@
+# @kruntime/komputer
+
+Runtime SDK and kernel surface for K.
+
+This package owns the durable runtime truth:
+
+- `Komputer`
+- `AgentSession`
+- `.kstate`
+- VFS
+- Runtime Authority
+- events
+- messages
+- receipts
+- vProcess recovery
+
+It intentionally does not scan image source trees. Source layout and active files belong to `@kruntime/kimage`.
+
+## Agent Computer Surface
+
+`agent.exec(...)` always enters K's local shell layer first. If a command cannot
+run inside the virtual computer, K may delegate it to a configured remote shell.
+The following work without any remote shell:
+
+```text
+pwd cd ls cat chmod install stat du base64 echo printf grep wc head jq tail sort uniq sed sha256sum awk tr cut diff tee xargs
+find basename dirname realpath readlink mkdir mktemp touch rm cp mv ln
+command type which help env printenv read source . set sh bash export unset id whoami hostname uname date true false test [ [[
+sleep curl wget jobs ps kill fg bg wait
+registered image commands
+```
+
+Output from K-local commands and remote commands is projected through the same
+`process` event family. Streaming stdout/stderr uses
+`{ type: 'process', status: 'output' }`.
+
+K-local builtins support `ls -la`/`ls -F`, quote-aware variables, `$?`,
+`${VAR:-fallback}`-style parameter defaults, `${#VAR}` length probes,
+`${path##*/}`/`${path%/*}` trimming, `$((...))`, KFS glob expansion,
+unquoted field splitting, bounded brace expansion, stdin/stdout/stderr
+redirection, heredoc stdin, `$()` and backtick command substitution, pipes, top-level
+`if` branches, top-level `for ... in` loops, and bounded `while`/`until` loops
+through the VFS, so no-shell remote runtimes can still run familiar shell-shaped work
+without a remote shell. `chmod` stores real mode bits in Drive/KState metadata;
+`stat -c %a/%A`, `ls -l`, `test -x`, and PATH executable lookup all read those
+same bits.
+such as `echo note > ~/work/note.txt`, `grep alpha < notes.txt`,
+`cat > file <<'EOF'`, `if test -f notes.txt; then grep alpha notes.txt; fi`,
+`mkdir -p app/{src,test}`, `for file in *.ts; do basename "$file"; done`, and
+`i=0; while test "$i" -lt 3; do echo "$i"; i=$((i + 1)); done`.
+`printf "%s\n" one two` repeats the format for remaining args, with basic
+`%s`/`%d`, width, left alignment, zero padding, and `%%` support.
+`find ... -maxdepth 2 -print0 | xargs -0 -n1 ...` works inside the K shell, so
+common Agent scripts can compose file discovery and text tools without a remote
+shell. `find ... -exec ... {} \;` is also supported for familiar
+one-file-at-a-time workflows.
+`mkdir` follows normal Unix shell semantics: without `-p`, the parent must
+already exist and the target must not; `mkdir -p` is the recursive, idempotent
+form.
+`touch -c`/`touch --no-create` follows Unix no-create behavior for existence
+probes.
+`rm -f` is safe as a cleanup no-op when no paths are passed, and `--` separates
+options from paths that begin with `-`.
+`cp --` and `mv --` follow the same path separator rule, while `cp -r` keeps
+directory copies inside KFS.
+`sed -n '1,20p' file`, `sed -n '$p' file`, and `sed -n '/pattern/p' file`
+cover the common file-slice and match-print probes Agents use before editing.
+`awk -F, '{print $1,$2,$NF,NF}'` covers the usual field-splitting and simple
+projection probes without a remote shell.
+`tail -n +2 file` follows Unix start-at-line semantics for header-skipping
+pipelines. `head -c` and `tail -c` select UTF-8 bytes for common file sniffing
+and log-tail probes.
+`find -type l`, `test -L`, and `ls -F` also understand K symbolic links.
+`grep -R -n pattern ~/work` searches recursively through KFS directories;
+`grep -F`, `grep -E`, and repeated `grep -e` patterns cover the usual fixed
+string, regex, and multiple-pattern probes.
+`ln -s`, `readlink`, `realpath`, and `readlink -f` are KState-backed, so
+symbolic links work on no-shell remote runtimes and survive recovery.
+`curl ... | jq -r .field` also works for common API JSON responses.
+`read` supports common stdin parsing patterns, including `read NAME`,
+`read FIRST REST`, and `read -r RAW`.
+`source file` and `. file` execute KFS shell files in the current shell state,
+so profile-style files can export variables, change cwd, or adjust shell
+options for later commands.
+`sh file` / `bash file` and `bash -c '...'` run through the same K shell in a
+child shell disk: positional parameters work, but cwd, exported variables, and
+shell options do not leak back to the Agent's parent shell.
+`env NAME=value cmd` runs a command with scoped temporary environment entries,
+`env -u NAME cmd` temporarily removes a variable, and `env -i NAME=value cmd`
+starts that command from an empty environment. These child environments do not
+pollute the Agent's persistent shell state.
+
+Network follows the same Unix-shaped rule. Runtime code can bind virtual hosts:
+
+```ts
+const computer = await Komputer.boot(image, {
+  hosts: {
+    api: {
+      '/hello': 'hello\n',
+      '/data.json': { ok: true },
+    },
+  },
+})
+```
+
+The Agent sees those names in `/sys/hosts.md` and can use normal shell commands:
+
+```sh
+curl http://api/hello
+curl -I http://api/data.json
+curl -i http://api/data.json
+curl -fsSL -D ~/work/headers.txt http://api/data.json
+curl -O http://api/data.json
+wget -qO- http://api/data.json
+```
+
+If a host is not bound and the current runtime profile has real `fetch`, K can use the
+real network. If neither exists, the command fails clearly. K-local `curl`
+supports common script options including compact flags like `-fsSL`, header
+dumps with `-D`, stdout output with `-o -`, and remote-name downloads with
+`-O`; `wget` follows redirects and supports Agent-friendly `-qO-` downloads.
+
+Background remote commands are recorded as virtual processes. Agents can inspect
+them with `jobs` and `ps`, move live handles with `fg`/`bg`, wait on them with
+`wait`, and signal them with `kill` when the active remote implements process
+signaling.
+
+The VFS intentionally keeps a Node-like shape:
+
+```ts
+await agent.fs.readFile('~/work/plan.md')
+await agent.fs.writeFile('~/work/report.md', '...')
+await agent.fs.mkdir('~/work/archive')
+await agent.fs.rename('~/work/a.md', '~/work/archive/a.md')
+await agent.fs.rm('~/work/archive', { recursive: true })
+
+const tree = await agent.fs.walk('~/work')
+```
+
+Mounted Drives are the only bridge between K paths and backing resources.
+Custom Drives may implement lifecycle hooks:
+
+```ts
+const drive = {
+  kind: 'drive',
+  name: 'crm-docs',
+  async mount(ctx) {
+    // connect, validate credentials, warm indexes
+  },
+  async unmount() {
+    // release backend handles
+  },
+  // readText/writeText/readdir/stat...
+}
+```
+
+When K delegates a script to a remote shell, it rewrites K paths only through the
+mounted Drive's `realPath(...)`. If a Drive has no real backing path, that script
+is rejected instead of pretending the remote can see the virtual resource. K-local
+builtins and image commands can still work with that Drive through the VFS.
+
+Command handlers receive submitted input as `ctx.args`/`ctx.input`, and can run
+shell work through `ctx.exec(...)`, which follows the same K shell authority and
+path rules as `agent.exec(...)`.
+
+`agent.events()` follows the ordered event log until the caller aborts or the
+local session handle closes. `agent.close()` explicitly ends the durable
+session, emits a `session.closed` signal, and lets event tails finish after
+draining already-written events. `agent.detach()` only releases the current
+worker lease and preserves the durable session for another worker.
+
+Forked sessions inherit image hooks by default:
+
+```ts
+const reviewer = await agent.fork({ mode: 'readonly' })
+const maintenance = await agent.fork({ mode: 'limited', hooks: false })
+```
+
+`hooks: false` is for deliberate internal maintenance sessions created from a
+hook. Normal application forks should keep hooks enabled.
+
+`disk: 'overlay'` gives the fork an isolated upper layer for K-owned disk:
+
+```ts
+const experiment = await agent.fork({ disk: 'overlay' })
+```
+
+Writes to KState-backed paths stay in the fork overlay. External custom drives
+are readonly in overlay forks so experiments cannot accidentally write through
+to real services.
+
+`fork({ mode: 'limited', scope })` carries the scope into the child session.
+Forked sessions are registered with the parent `Komputer`, so `computer.close()`
+releases their leases together with normal logged-in sessions.
+
+Each active session holds a durable worker lease in `.kstate`. A second worker
+cannot drive the same session until the lease is released or expires. Long
+running sessions renew the lease with a heartbeat. `computer.close()` detaches
+local workers by default, while `computer.close({ endSessions: true })` ends
+them. `computer.recoverSessions()` can take over detached or expired sessions
+after process shutdown or crash.
+
+Long-running workers can call `computer.detachIdleSessions({ idleForMs })` to
+release idle AgentSession handles without ending durable sessions. Running
+background jobs are skipped by default. A later `login(agent, { id })` restores
+the same Agent from KState.
+
+For fleets, use `KomputerPool` as a thin lifecycle cache around the same boot
+and login primitives:
+
+```ts
+import { Komputer, KomputerPool } from '@kruntime/komputer'
+
+const pool = new KomputerPool({
+  maxWarm: 100,
+  idleForMs: 60_000,
+  boot: key => Komputer.boot(image, {
+    disk: stateFor(key),
+    remote,
+    models,
+  }),
+})
+
+const agent = await pool.login('tenant:alice:assistant', 'assistant', {
+  id: 'chat:inbox',
+})
+
+await pool.withLogin('tenant:alice:assistant', { id: 'chat:inbox' }, async agent => {
+  await agent.exec('cat ~/task.md')
+})
+
+await pool.sweep()
+console.log(pool.stats())
+```
+
+The pool is not a task system and not another storage abstraction. A key maps
+to one durable Computer. `KomputerPool` only coalesces concurrent boots, keeps a
+bounded set of warm JavaScript handles, detaches idle sessions, and closes idle
+Computers. Use `withLogin(...)` with `maxWarm: 0` for browser, extension,
+embedded, or serverless profiles that should keep no warm Computers between
+requests. Plain `get(...)` and `login(...)` keep a warm handle until
+`sweep(...)` or `release(...)`.
+
+For operations dashboards and leak checks, use `pool.stats()`,
+`computer.stats()`, and `agent.stats()`. These are local-worker counters for
+warm Computers, booting entries, local session handles, active virtual
+processes, commands, hooks, crons, mounts, hosts, handlers, and shell
+functions. They do not scan durable JSONL history and do not hold extra
+references.
+
+`computer.close()` releases local active process handles as well as session
+handlers. Durable background process rows stay in KState for recovery instead
+of keeping worker timers or remote stream readers alive after shutdown.
+
+Custom disk and remote adapters can expose `close()`. `computer.close()`
+releases them after sessions and mounts are settled, which keeps browser,
+plugin, cloud, and DB-backed runtimes from leaking bridge handles or caches.
+
+On recovery, K seals unfinished tool calls with an uncertain tool result and
+seals any running turn with a terminal `turn` event. That keeps the provider
+message stream, event stream, and input queue from containing dangling state
+after a worker takeover.
+
+K also separates provider-message sealing from event-stream sealing. If a
+durable assistant message contains `tool_use`, recovery appends an uncertain
+`tool_result` message. If only a streamed public `tool` event was durable before
+the crash, recovery emits a sealed/uncertain `tool` event without inventing a
+provider message.
+
+Background process receipts are also sealed append-only. Starting a background
+remote or K-local process writes an `uncertain` receipt; normal completion appends
+the same receipt id again as `committed` or `failed`. If a worker dies before
+that final row exists, the receipt remains `uncertain` for reconciliation.
+VFS effects also write receipts for `vfs.write`, `vfs.append`, `vfs.mkdir`,
+`vfs.rm`, `vfs.rename`, `vfs.symlink`, `vfs.chmod`, and `vfs.utime`. Those
+receipts carry caller provenance through `by` and record operation metadata such
+as path and byte count, not file contents.
+Deterministic K-owned virtual processes can do better when their state is fully
+recoverable: for example, a crashed `sleep 10 &` is resumed from its durable
+start time or completed immediately if its deadline already passed. Remote
+processes and non-replayable K scripts stay conservative and reconcile through
+`uncertain`.
+
+Approvals use one simple public pair: hooks call `ctx.ask(...)`, and external
+code calls `agent.decide(id, 'allow' | 'reject')`. K stores the paused action in
+`.kstate`; allowing it resumes the same shell, command, filesystem, model, or
+turn action, including after a worker detach and later login recovery.
+
+Restricted modes do not trust arbitrary remote shell execution. A remote must
+declare hard shell sandbox support before `readonly`, `plan`, or `limited` can
+delegate external shell commands to it. K hardens every remote sandbox request
+with mandatory `denyWrite` entries for sensitive startup/config paths such as
+shell rc files, `.mcp.json`, editor config directories, `.git/config`,
+`.git/hooks`, and `_shared`, then validates paths and host allow-lists before a
+Remote adapter sees the request.
+
+`limited` is an explicit allow-list mode. It applies to filesystem writes,
+remote shell commands, K shell commands, and direct `agent.command(...)` calls.
+Filesystem scope entries may use `~/...`; K normalizes them against the Agent's
+home directory when the session or fork is created.
+
+Markdown commands can request invocation-local mode changes, such as
+`readonly: true`; K applies that only for the command turn and restores the
+AgentSession mode afterward.
+
+## Model Providers
+
+K models are LLM adapters with one stable surface:
+
+```ts
+model.complete({ messages })
+```
+
+The package includes cross-platform fetch-based adapters for the primary LLM
+protocol families:
+
+```ts
+import {
+  anthropicMessagesModel,
+  deepseekMessagesModel,
+  deepseekOpenAIModel,
+  minimaxOpenAIModel,
+  openaiChatCompletionsModel,
+  openaiResponsesModel,
+} from '@kruntime/komputer'
+```
+
+Provider-specific continuation data is stored as adapter-owned sidecar state on
+the message. K core only sees the standard `content` blocks and an optional
+generic `provider.anchor` bit that asks the message window to retain a cache
+anchor. OpenAI Responses encrypted reasoning, DeepSeek `reasoning_content`,
+Anthropic signatures, and MiniMax `reasoning_details` are interpreted only by
+their own adapters.
+
+Other services should be exposed as commands, mounts, MCP tools, or application
+APIs unless they are actually LLM-like.
+
+## Secrets
+
+Secrets are bound at runtime, not baked into images. Agents can inspect
+`/sys/secrets.md` to know which handles exist, but the raw values are only
+available to trusted command/hook/cron code through:
+
+```ts
+ctx.secret('github')
+```
+
+## Entrypoints
+
+```ts
+import { boot, memoryDisk, noShellRemote } from '@kruntime/komputer'
+```
+
+The root entrypoint is cross-platform and must be importable anywhere
+JavaScript can run.
+
+```ts
+import { Komputer } from '@kruntime/komputer'
+import { localDisk, localRemote } from '@kruntime/komputer/node'
+
+const computer = await Komputer.boot(image, {
+  disk: localDisk('.kstate'),
+  remotes: { local: localRemote() },
+})
+```
+
+Node-only helpers live in the `/node` subpath so browser, mini program,
+extension, and embedded bundles do not inherit Node filesystem/process modules.

package/dist/agent/approvals.d.ts

@@ -0,0 +1,28 @@
+import type { KState } from '../kstate.js';
+export interface ApprovalRecord extends Record<string, unknown> {
+    id: string;
+    status?: string;
+    hook?: string;
+    actionKey?: string;
+    request?: Record<string, unknown>;
+    current?: Record<string, unknown>;
+    createdAt?: string;
+    decidedAt?: string;
+    consumedAt?: string;
+    decision?: unknown;
+    by?: string;
+    result?: unknown;
+}
+export declare class SessionApprovals {
+    private readonly kstate;
+    private readonly sessionId;
+    constructor(kstate: KState, sessionId: string);
+    create(hook: string, current: Record<string, unknown>, request: Record<string, unknown>): Promise<ApprovalRecord>;
+    byId(approvalId: string): Promise<ApprovalRecord | undefined>;
+    forAction(hook: string, current: Record<string, unknown>): Promise<ApprovalRecord | undefined>;
+    append(row: Record<string, unknown>): Promise<void>;
+    consume(approval: ApprovalRecord): Promise<Record<string, unknown>>;
+    resumed(approvalId: string, result: unknown): Promise<void>;
+}
+export declare function normalizeApprovalDecision(decision: unknown): 'allowed' | 'rejected';
+export declare function resultSummary(value: unknown): Record<string, unknown>;

package/dist/agent/approvals.js

@@ -0,0 +1,109 @@
+import { id, now, sha256 } from "../utils.js";
+export class SessionApprovals {
+    kstate;
+    sessionId;
+    constructor(kstate, sessionId) {
+        this.kstate = kstate;
+        this.sessionId = sessionId;
+    }
+    async create(hook, current, request) {
+        const approval = {
+            id: id('approval'),
+            status: 'pending',
+            hook,
+            actionKey: approvalActionKey(hook, current),
+            request,
+            current,
+            createdAt: now(),
+        };
+        await this.kstate.appendSessionJsonl(this.sessionId, 'approvals.jsonl', approval);
+        return approval;
+    }
+    async byId(approvalId) {
+        const rows = await this.kstate.readSessionJsonl(this.sessionId, 'approvals.jsonl');
+        const related = rows.filter((row) => row.id === approvalId);
+        if (!related.length)
+            return undefined;
+        return Object.assign({}, ...related);
+    }
+    async forAction(hook, current) {
+        const actionKey = approvalActionKey(hook, current);
+        const rows = await this.kstate.readSessionJsonl(this.sessionId, 'approvals.jsonl');
+        const grouped = new Map();
+        for (const row of rows) {
+            if (row.actionKey !== actionKey && !grouped.has(row.id))
+                continue;
+            const previous = grouped.get(row.id) || {};
+            const next = { ...previous, ...row };
+            if (next.actionKey === actionKey)
+                grouped.set(row.id, next);
+        }
+        const candidates = [...grouped.values()]
+            .filter((row) => row.hook === hook && (row.status === 'pending' || row.status === 'allowed'))
+            .sort((a, b) => String(b.createdAt || b.decidedAt || '').localeCompare(String(a.createdAt || a.decidedAt || '')));
+        return candidates[0];
+    }
+    async append(row) {
+        await this.kstate.appendSessionJsonl(this.sessionId, 'approvals.jsonl', row);
+    }
+    async consume(approval) {
+        const row = {
+            id: approval.id,
+            status: 'consumed',
+            consumedAt: now(),
+        };
+        await this.append(row);
+        return row;
+    }
+    async resumed(approvalId, result) {
+        await this.append({
+            id: approvalId,
+            status: 'resumed',
+            resumedAt: now(),
+            result: resultSummary(result),
+        });
+    }
+}
+export function normalizeApprovalDecision(decision) {
+    if (decision === true)
+        return 'allowed';
+    if (decision === false)
+        return 'rejected';
+    if (typeof decision === 'string') {
+        const clean = decision.toLowerCase();
+        if (clean === 'allow' || clean === 'allowed' || clean === 'yes' || clean === 'approve' || clean === 'approved')
+            return 'allowed';
+        if (clean === 'reject' || clean === 'rejected' || clean === 'no' || clean === 'deny' || clean === 'denied')
+            return 'rejected';
+    }
+    if (decision && typeof decision === 'object') {
+        const record = decision;
+        return normalizeApprovalDecision(record.decision ?? record.status ?? record.action);
+    }
+    throw new Error(`approval decision must be "allow" or "reject"`);
+}
+export function resultSummary(value) {
+    if (value && typeof value === 'object') {
+        const record = value;
+        return {
+            status: record.status,
+            code: record.code,
+            inputId: record.inputId,
+            turnId: record.turnId,
+            type: record.type,
+        };
+    }
+    return { type: typeof value };
+}
+function approvalActionKey(hook, current) {
+    return sha256(stableJson({ hook, current }));
+}
+function stableJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(',')}}`;
+}
+//# sourceMappingURL=approvals.js.map

package/dist/agent/approvals.js.map

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

package/dist/agent/messages.d.ts

@@ -0,0 +1,67 @@
+import type { KState } from '../kstate.js';
+import type { KMessage } from '../types.js';
+export interface MessagePageOptions {
+    view?: 'full' | 'current';
+    since?: number;
+    before?: number;
+    limit?: number;
+}
+export interface MessageTailOptions {
+    view?: 'full' | 'current';
+    since?: number;
+    signal?: AbortSignal;
+}
+export interface SessionMessagesInit {
+    kstate: KState;
+    sessionId: string;
+    isClosed: () => boolean;
+    system: () => string;
+}
+export declare class SessionMessages {
+    private readonly kstate;
+    private readonly sessionId;
+    private readonly isClosed;
+    private readonly system;
+    private readonly waiters;
+    constructor({ kstate, sessionId, isClosed, system }: SessionMessagesInit);
+    append(message: Omit<KMessage, 'seq' | 'at'>): Promise<KMessage>;
+    appendMany(messages: Array<Omit<KMessage, 'seq' | 'at'>>): Promise<KMessage[]>;
+    appendCurrent(message: KMessage): Promise<void>;
+    forModel(): Promise<KMessage[]>;
+    view(): {
+        get: (options?: {}) => Promise<{
+            messages: KMessage[];
+            cursor: number;
+            hasMore: boolean;
+        }>;
+        current: (options?: {}) => Promise<{
+            messages: KMessage[];
+            cursor: number;
+            hasMore: boolean;
+        }>;
+        full: (options?: {}) => Promise<{
+            messages: KMessage[];
+            cursor: number;
+            hasMore: boolean;
+        }>;
+        tail: (options?: {}) => AsyncIterable<{
+            cursor: number;
+            message: KMessage;
+        }>;
+    };
+    get({ view, since, before, limit }?: MessagePageOptions): Promise<{
+        messages: KMessage[];
+        cursor: number;
+        hasMore: boolean;
+    }>;
+    tail({ view, since, signal }?: MessageTailOptions): AsyncIterable<{
+        cursor: number;
+        message: KMessage;
+    }>;
+    private readFullRange;
+    private indexFullMessage;
+    private offsetForCursor;
+    wake(): void;
+    clear(): void;
+    private waitForMessageOrPoll;
+}