@husk-ai/core 0.1.1

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;GAKG;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AAEH,eAAO,MAAM,oBAAoB;IAC/B,uEAAuE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmBvE;;;;OAIG;;IAEH;;;;;;;;;;OAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,eAAO,MAAM,YAAY;;;;;IAKvB,2CAA2C;;;;;;;;;;;;;;;;;EAG3C,CAAC;AAEH,eAAO,MAAM,gBAAgB;;IAE3B,8DAA8D;;;IAG9D,iDAAiD;;IAEjD,mFAAmF;;;;;;;;;;;;;;EAEnF,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAoBxB,CAAC;AAEH,eAAO,MAAM,YAAY;;;IAGvB,4EAA4E;;;;;;;;;;;;;EAG5E,CAAC;AAEH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;EAI9B,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;EAGxB,CAAC;AAEH,eAAO,MAAM,cAAc;IACzB,uDAAuD;;;;;;IAUvD,qDAAqD;;IAErD,oFAAoF;;;IAGpF,8EAA8E;;;;;;;;;;;;;;;;;;;;;;;;;IAI9E,gEAAgE;;;QAzHhE,uEAAuE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAmBvE;;;;WAIG;;QAEH;;;;;;;;;;WAUG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QASH,2CAA2C;;;;;;;;;;;;;;;;;;;;QAO3C,8DAA8D;;;QAG9D,iDAAiD;;QAEjD,mFAAmF;;;;;;;;;;;;;;;;;;QA6BnF,4EAA4E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA2C5E,4CAA4C;;IAE5C,iEAAiE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EASjE,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAC3D,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAClE,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC1D,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,kFAAkF;AAClF,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAUlD;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,OAAO,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAOhE;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAOlD;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CAavF"}

package/dist/spec.js

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+import { HuskError } from './errors.js';
+/**
+ * husk.yaml -- the whole agent in one file.
+ *
+ * This is the artifact a chat becomes. It is portable, diffable, reviewable,
+ * and it is the only thing the runtime needs in order to bring a bot up.
+ */
+export const NetworkPolicySchema = z.object({
+    mode: z.enum(['none', 'egress', 'full']).default('egress'),
+    allow: z.array(z.string()).optional(),
+    deny: z.array(z.string()).optional(),
+});
+export const ComputerConfigSchema = z.object({
+    /** false disables the machine entirely; true accepts every default. */
+    enabled: z.boolean().default(true),
+    provider: z.string().optional(),
+    flavor: z.enum(['base', 'python', 'node', 'full']).default('base'),
+    image: z.string().optional(),
+    cpus: z.number().positive().max(64).optional(),
+    memoryMb: z.number().int().positive().max(131072).optional(),
+    diskMb: z.number().int().positive().optional(),
+    idleTimeoutSec: z.number().int().min(0).default(900),
+    maxLifetimeSec: z.number().int().min(0).default(0),
+    network: NetworkPolicySchema.default({ mode: 'egress' }),
+    packages: z.array(z.string()).default([]),
+    setup: z.string().optional(),
+    env: z.record(z.string()).default({}),
+    workdir: z.string().default('/work'),
+    persist: z.boolean().default(false),
+    mounts: z
+        .array(z.object({ source: z.string(), target: z.string(), readonly: z.boolean().default(true) }))
+        .default([]),
+    /**
+     * Unprivileged user inside the machine. Omitted means "whatever the provider
+     * defaults to" (`husk` on the container images), which is why there is no
+     * default here: writing one in would override a provider that knows better.
+     */
+    user: z.string().optional(),
+    /**
+     * Provider-specific configuration, carried through to `ComputerSpec.labels`.
+     *
+     * This is how a single husk.yaml points itself at a particular box or Fly app
+     * without an environment variable: `husk.ssh`, `husk.ssh.key`, `husk.fly.app`,
+     * `husk.fly.region`, `husk.fly.ports`. The ssh and fly providers read these
+     * first and fall back to the environment.
+     *
+     * Optional rather than `.default({})` so a spec that never mentions labels
+     * serialises exactly as it did before.
+     */
+    labels: z.record(z.string()).optional(),
+});
+export const LimitsSchema = z.object({
+    maxSteps: z.number().int().positive().max(500).default(24),
+    maxCostUsd: z.number().min(0).default(0.5),
+    maxTokens: z.number().int().positive().default(200_000),
+    timeoutSec: z.number().int().positive().default(300),
+    /** Per-exec ceiling inside the machine. */
+    execTimeoutSec: z.number().int().positive().default(120),
+    maxOutputBytes: z.number().int().positive().default(262_144),
+});
+export const GuardrailsSchema = z.object({
+    approvalMode: z.enum(['auto', 'ask', 'readonly']).default('auto'),
+    /** Regexes matched against a shell command before it runs. */
+    denyCommands: z.array(z.string()).default([]),
+    allowCommands: z.array(z.string()).default([]),
+    /** Refuse and explain, rather than answering. */
+    refuse: z.array(z.string()).default([]),
+    /** Strip credential-shaped strings from tool output before the model sees them. */
+    redactSecrets: z.boolean().default(true),
+});
+export const TriggerSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('http'),
+        path: z.string().default('/'),
+        auth: z.enum(['none', 'token']).default('token'),
+    }),
+    z.object({ type: z.literal('cron'), schedule: z.string(), prompt: z.string() }),
+    z.object({
+        type: z.literal('discord'),
+        channels: z.array(z.string()).default([]),
+        mentionOnly: z.boolean().default(true),
+    }),
+    z.object({
+        type: z.literal('slack'),
+        channels: z.array(z.string()).default([]),
+        mentionOnly: z.boolean().default(true),
+    }),
+    z.object({ type: z.literal('telegram'), allowlist: z.array(z.string()).default([]) }),
+    z.object({ type: z.literal('webhook'), path: z.string(), secret: z.string().optional() }),
+    z.object({ type: z.literal('cli') }),
+]);
+export const MemorySchema = z.object({
+    enabled: z.boolean().default(false),
+    backend: z.enum(['sqlite', 'memory', 'file']).default('sqlite'),
+    /** Turns of raw history kept verbatim before older turns get summarised. */
+    windowTurns: z.number().int().positive().default(20),
+    summarise: z.boolean().default(true),
+});
+export const KnowledgeItemSchema = z.object({
+    title: z.string(),
+    content: z.string(),
+    source: z.string().optional(),
+});
+export const ExampleSchema = z.object({
+    user: z.string(),
+    assistant: z.string(),
+});
+export const HuskSpecSchema = z.object({
+    /** Schema version. Bumped only on breaking changes. */
+    apiVersion: z.literal('husk/v1').default('husk/v1'),
+    name: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, 'name must be lowercase alphanumeric with dashes'),
+    displayName: z.string().max(96).optional(),
+    version: z.string().default('0.1.0'),
+    description: z.string().max(280).default(''),
+    /** Primary model, by alias or fully-qualified id. */
+    model: z.string().default('auto'),
+    /** Tried in order when the primary is unavailable, rate limited, or over budget. */
+    fallbackModels: z.array(z.string()).default([]),
+    temperature: z.number().min(0).max(2).optional(),
+    /** The system prompt. Supports {{var}} interpolation from RunOptions.vars. */
+    persona: z.string().default(''),
+    knowledge: z.array(KnowledgeItemSchema).default([]),
+    examples: z.array(ExampleSchema).default([]),
+    /** Tool names, or the computer / files / web / http bundles. */
+    tools: z.array(z.string()).default(['computer']),
+    computer: ComputerConfigSchema.default({}),
+    limits: LimitsSchema.default({}),
+    guardrails: GuardrailsSchema.default({}),
+    memory: MemorySchema.default({}),
+    triggers: z.array(TriggerSchema).default([{ type: 'cli' }]),
+    /** Free-form, carried through untouched. */
+    metadata: z.record(z.unknown()).default({}),
+    /** Provenance: which transcript this husk was distilled from. */
+    origin: z
+        .object({
+        source: z.string(),
+        transcriptId: z.string().optional(),
+        importedAt: z.string().optional(),
+        messageCount: z.number().optional(),
+    })
+        .optional(),
+});
+/** Parse and normalise. Throws a HuskError carrying every field-level problem. */
+export function parseSpec(input) {
+    const result = HuskSpecSchema.safeParse(input);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
+        throw new HuskError('E_SPEC_INVALID', `husk.yaml is not valid:\n  ${issues.join('\n  ')}`, {
+            hint: 'Run `husk validate` to see the expected shape, or `husk init` to regenerate.',
+            details: { issues },
+        });
+    }
+    return result.data;
+}
+export function safeParseSpec(input) {
+    const result = HuskSpecSchema.safeParse(input);
+    if (result.success)
+        return { ok: true, spec: result.data };
+    return {
+        ok: false,
+        issues: result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`),
+    };
+}
+/** A minimal, valid husk. Used by `husk init` and by tests. */
+export function defaultSpec(name) {
+    return HuskSpecSchema.parse({
+        name,
+        displayName: name.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+        description: 'A husk.',
+        persona: 'You are a careful, concise assistant with access to a Linux computer.',
+    });
+}
+/** Interpolate {{var}} placeholders in the persona. Unknown vars are left intact. */
+export function renderPersona(spec, vars = {}) {
+    const base = spec.persona.replace(/\{\{\s*(\w+)\s*\}\}/g, (m, k) => vars[k] ?? m);
+    const parts = [base];
+    if (spec.knowledge.length) {
+        parts.push('\n## Reference\n' + spec.knowledge.map((k) => `### ${k.title}\n${k.content}`).join('\n\n'));
+    }
+    if (spec.guardrails.refuse.length) {
+        parts.push('\n## Out of scope\nDecline these, briefly, and say what you can do instead:\n' +
+            spec.guardrails.refuse.map((r) => `- ${r}`).join('\n'));
+    }
+    return parts.join('\n').trim();
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

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

package/dist/types/agent.d.ts

@@ -0,0 +1,168 @@
+import type { Computer } from './computer.js';
+import type { ChatResponse, JSONSchema, ModelMessage, ToolCallPart, Usage } from './model.js';
+import type { Logger } from '../logger.js';
+export interface ToolContext {
+    /** The machine this agent is driving, when it has one. */
+    computer?: Computer;
+    log: Logger;
+    signal?: AbortSignal;
+    huskId: string;
+    runId: string;
+    /** Scratch space shared across tool calls within one run. */
+    state: Map<string, unknown>;
+    emit(event: RunEvent): void;
+    /** Ask the operator to approve a dangerous call. Resolves false when no approver is wired. */
+    confirm(prompt: string, details?: Record<string, unknown>): Promise<boolean>;
+}
+export interface Tool<I = Record<string, unknown>, O = unknown> {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+    /** Requires approval when the run is in ask mode. */
+    dangerous?: boolean;
+    /** Withheld from the model unless the husk explicitly enables it. */
+    optIn?: boolean;
+    handler(input: I, ctx: ToolContext): Promise<O>;
+    /** Render the result for the model. Defaults to JSON.stringify. */
+    render?(output: O): string;
+}
+export type ApprovalMode = 'auto' | 'ask' | 'readonly';
+/**
+ * What a human is being asked to approve.
+ *
+ * Covers both a `dangerous` tool call and a free-form `ctx.confirm`, so an
+ * approver written once handles every pause the runtime can raise.
+ */
+export interface ApprovalRequest {
+    runId: string;
+    huskId: string;
+    /** The tool being called, or undefined for a free-form `ctx.confirm`. */
+    tool?: string;
+    /** The originating tool call, when there is one. Lets a client correlate. */
+    callId?: string;
+    args?: Record<string, unknown>;
+    /** Human-readable question. Always populated. */
+    prompt: string;
+    details?: Record<string, unknown>;
+    dangerous: boolean;
+}
+/**
+ * Decide whether a paused call may proceed.
+ *
+ * Returning false, throwing, and not being supplied at all must all deny.
+ * Approval is a security boundary: absent means no.
+ */
+export type Approver = (req: ApprovalRequest) => Promise<boolean>;
+export interface RunOptions {
+    input: string | ModelMessage[];
+    /** Prior turns to continue from. */
+    history?: ModelMessage[];
+    model?: string;
+    maxSteps?: number;
+    maxCostUsd?: number;
+    maxTokens?: number;
+    timeoutSec?: number;
+    approvalMode?: ApprovalMode;
+    signal?: AbortSignal;
+    onEvent?: (event: RunEvent) => void;
+    /**
+     * Called before a `dangerous` tool runs in `ask` mode.
+     *
+     * Absent means deny. A headless process running an `ask`-mode husk must fail
+     * closed, not quietly behave as though it were in `auto`.
+     */
+    onApproval?: Approver;
+    /** Named values interpolated into the persona template. */
+    vars?: Record<string, string>;
+}
+export type RunEvent = {
+    type: 'run_start';
+    runId: string;
+    husk: string;
+    model: string;
+} | {
+    type: 'step_start';
+    step: number;
+} | {
+    type: 'thinking_delta';
+    text: string;
+} | {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'message';
+    message: ModelMessage;
+} | {
+    type: 'tool_start';
+    call: ToolCallPart;
+}
+/**
+ * Output from a running tool, as it arrives.
+ *
+ * Deliberately not `text_delta`: that is the model's token stream, and a
+ * consumer rendering it must not find a build log spliced into the middle.
+ */
+ | {
+    type: 'tool_delta';
+    callId: string;
+    tool: string;
+    stream: 'stdout' | 'stderr';
+    text: string;
+} | {
+    type: 'tool_end';
+    call: ToolCallPart;
+    output: string;
+    isError: boolean;
+    durationMs: number;
+} | {
+    type: 'tool_denied';
+    call: ToolCallPart;
+    reason: string;
+}
+/**
+ * The run is blocked on a human. Answer by resolving the `Approver`, or over
+ * HTTP by POSTing to /v1/approvals/:approvalId. An unanswered request is
+ * denied when it times out.
+ */
+ | {
+    type: 'approval_required';
+    approvalId: string;
+    request: ApprovalRequest;
+} | {
+    type: 'computer_ready';
+    computerId: string;
+    provider: string;
+} | {
+    type: 'usage';
+    usage: Usage;
+    cumulative: Usage;
+} | {
+    type: 'warning';
+    message: string;
+} | {
+    type: 'run_end';
+    result: RunResult;
+} | {
+    type: 'error';
+    error: {
+        message: string;
+        code?: string;
+    };
+};
+export interface RunResult {
+    runId: string;
+    text: string;
+    messages: ModelMessage[];
+    steps: number;
+    usage: Usage;
+    durationMs: number;
+    /** `loop` means the run was cut short because the agent kept repeating itself. */
+    stopReason: 'complete' | 'step_limit' | 'budget' | 'timeout' | 'aborted' | 'loop' | 'error';
+    error?: {
+        message: string;
+        code?: string;
+    };
+    /** Every model call made during the run, for replay and debugging. */
+    trace?: ChatResponse[];
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

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

package/dist/types/agent.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":""}

package/dist/types/computer.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The computer contract.
+ *
+ * A Husk "computer" is a small, disposable Linux machine an agent can drive.
+ * Every provider -- Docker, Podman, a plain guarded directory, SSH, Fly --
+ * implements this same surface, so an agent never learns where it is running.
+ */
+export type ProviderName = 'docker' | 'podman' | 'local' | 'ssh' | 'fly' | (string & {});
+export type ComputerState = 'creating' | 'running' | 'paused' | 'stopped' | 'destroyed' | 'error';
+/** How much the machine is allowed to talk to the outside world. */
+export interface NetworkPolicy {
+    /** none: no egress at all. egress: allowlist only. full: unrestricted. */
+    mode: 'none' | 'egress' | 'full';
+    /** Hostnames or CIDRs permitted when mode === 'egress'. Supports leading '*.' wildcards. */
+    allow?: string[];
+    /** Always-denied hosts, applied even in 'full' mode. */
+    deny?: string[];
+}
+export interface MountSpec {
+    /** Absolute path on the host. */
+    source: string;
+    /** Absolute path inside the computer. */
+    target: string;
+    readonly?: boolean;
+}
+/** Prebuilt environments. A provider maps these onto concrete images. */
+export type Flavor = 'base' | 'python' | 'node' | 'full';
+export interface ComputerSpec {
+    /** Human label. Also used for the container name when it is unique. */
+    name?: string;
+    provider?: ProviderName;
+    /** Explicit image reference. Overrides `flavor`. */
+    image?: string;
+    flavor?: Flavor;
+    cpus?: number;
+    memoryMb?: number;
+    diskMb?: number;
+    /** Destroy the computer after this many seconds of no exec activity. 0 disables. */
+    idleTimeoutSec?: number;
+    /** Hard ceiling on total lifetime regardless of activity. 0 disables. */
+    maxLifetimeSec?: number;
+    network?: NetworkPolicy;
+    env?: Record<string, string>;
+    mounts?: MountSpec[];
+    /** Default working directory. Defaults to /work. */
+    workdir?: string;
+    /** Unprivileged user inside the machine. Defaults to `husk`. */
+    user?: string;
+    /** Keep the filesystem across restarts (named volume / retained directory). */
+    persist?: boolean;
+    /** Extra packages to install on first boot, resolved by the flavor's package manager. */
+    packages?: string[];
+    /** Shell snippet run once after creation. */
+    setup?: string;
+    labels?: Record<string, string>;
+}
+export interface ComputerInfo {
+    id: string;
+    name: string;
+    provider: ProviderName;
+    state: ComputerState;
+    image: string;
+    workdir: string;
+    createdAt: string;
+    lastUsedAt: string;
+    spec: ComputerSpec;
+    /** Provider-native handle (container id, machine id, pid namespace, ...). */
+    nativeId?: string;
+    /** Ports published to the host, keyed by the in-computer port. */
+    ports?: Record<number, PortBinding>;
+    /**
+     * Set when `image` is not the image the spec asked for.
+     *
+     * husk prefers its own images and falls back to a stock public one when the
+     * registry has nothing -- which is every install until the images are
+     * published. The fallback is a bare `debian:bookworm-slim`: no python3, no
+     * curl, no `huskinfo`, and no `husk` user. That is a perfectly usable Linux
+     * box and a surprising one if you were told you had the other, so the
+     * substitution is recorded rather than performed quietly.
+     */
+    imageFallback?: {
+        wanted: string;
+        reason: string;
+    };
+    error?: string;
+}
+export interface PortBinding {
+    hostPort: number;
+    url: string;
+    /** Set when the provider can offer a public tunnel. */
+    publicUrl?: string;
+    /**
+     * Whether anything actually answered on `url` when the binding was made.
+     *
+     * `false` is not necessarily an error -- an agent that exposes a port before
+     * its server finishes starting is the ordinary case -- but a URL nobody has
+     * ever connected to should not be handed back as though it were known good.
+     * Undefined means the provider did not check.
+     */
+    reachable?: boolean;
+}
+export interface ExecRequest {
+    /** A shell string, or an argv array to execute without a shell. */
+    cmd: string | string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutSec?: number;
+    stdin?: string;
+    user?: string;
+    /** Allocate a pty. Required for interactive tools and for programs that check isatty. */
+    tty?: boolean;
+    /** Output is clamped to this many bytes per stream. Defaults to 256 KiB. */
+    maxOutputBytes?: number;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    truncated: boolean;
+    timedOut: boolean;
+}
+export interface DirEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'dir' | 'symlink' | 'other';
+    size: number;
+    modifiedAt?: string;
+    mode?: string;
+}
+export interface WriteFileOptions {
+    /** Octal string, e.g. '0755'. */
+    mode?: string;
+    /** Create parent directories. Defaults to true. */
+    mkdirp?: boolean;
+    append?: boolean;
+}
+/** A live computer. All paths are absolute inside the machine unless noted. */
+export interface Computer {
+    readonly id: string;
+    readonly info: ComputerInfo;
+    refresh(): Promise<ComputerInfo>;
+    exec(req: ExecRequest): Promise<ExecResult>;
+    writeFile(path: string, content: string | Uint8Array, opts?: WriteFileOptions): Promise<void>;
+    readFile(path: string): Promise<Uint8Array>;
+    readTextFile(path: string, maxBytes?: number): Promise<string>;
+    listDir(path: string): Promise<DirEntry[]>;
+    stat(path: string): Promise<DirEntry | null>;
+    remove(path: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /** Copy a host path into the machine. Directories are copied recursively. */
+    upload(hostPath: string, targetPath: string): Promise<void>;
+    /** Copy a machine path back out to the host. */
+    download(path: string, hostPath: string): Promise<void>;
+    /** Publish an in-computer port to the host. Idempotent. */
+    exposePort(port: number): Promise<PortBinding>;
+    stop(): Promise<void>;
+    start(): Promise<void>;
+    destroy(): Promise<void>;
+    /** Optional capabilities -- callers must feature-detect. */
+    snapshot?(name?: string): Promise<{
+        id: string;
+        sizeBytes?: number;
+    }>;
+    restore?(snapshotId: string): Promise<void>;
+}
+export interface Availability {
+    available: boolean;
+    /** Why it is not available, in one line. */
+    reason?: string;
+    /** What the user should do about it, in one line. */
+    hint?: string;
+    version?: string;
+    /** True when the boundary is real. See `isolationKind` for what kind of real. */
+    isolated?: boolean;
+    /**
+     * What the boundary actually is.
+     *
+     * - `kernel` — namespaces and cgroups on this machine (docker, podman, fly).
+     * - `machine` — a different computer entirely (ssh). Isolated from *your* laptop,
+     *   but the agent still holds your user's shell on the far end, so it is not
+     *   isolated from that box. Rendering this as a plain green "isolated" badge
+     *   overclaims, which is the whole reason this field exists.
+     * - `guardrails` — process-level checks only (local). Stops accidents, not attackers.
+     */
+    isolationKind?: 'kernel' | 'machine' | 'guardrails';
+}
+export interface ComputerProvider {
+    readonly name: ProviderName;
+    /** One-line description shown in `husk doctor`. */
+    readonly description: string;
+    /** Higher wins when auto-selecting a provider. */
+    readonly priority: number;
+    isAvailable(): Promise<Availability>;
+    create(spec: ComputerSpec): Promise<Computer>;
+    get(id: string): Promise<Computer | null>;
+    list(): Promise<ComputerInfo[]>;
+    /** Remove computers that have outlived their idle or lifetime budget. */
+    reap?(): Promise<string[]>;
+}
+//# sourceMappingURL=computer.d.ts.map

package/dist/types/computer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"computer.d.ts","sourceRoot":"","sources":["../../src/types/computer.ts"],"names":[],"mappings":"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"}

package/dist/types/computer.js

@@ -0,0 +1,9 @@
+/**
+ * The computer contract.
+ *
+ * A Husk "computer" is a small, disposable Linux machine an agent can drive.
+ * Every provider -- Docker, Podman, a plain guarded directory, SSH, Fly --
+ * implements this same surface, so an agent never learns where it is running.
+ */
+export {};
+//# sourceMappingURL=computer.js.map

package/dist/types/computer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computer.js","sourceRoot":"","sources":["../../src/types/computer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}