@husk-ai/core 0.1.1

package/dist/errors.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Two of these are reserved rather than live. See `RESERVED_ERROR_CODES`.
+ */
+export type HuskErrorCode = 'E_PROVIDER_UNAVAILABLE' | 'E_COMPUTER_NOT_FOUND' | 'E_COMPUTER_FAILED' | 'E_EXEC_FAILED'
+/**
+ * Reserved. Nothing throws this.
+ *
+ * An exec that runs out of time still produces stdout, stderr and an exit
+ * code, and the caller usually wants all three -- so a timeout is reported as
+ * `ExecResult.timedOut: true`, not as a thrown error. Throwing would discard
+ * the output the agent needs in order to explain what happened.
+ *
+ * Kept because it is the honest code for the *status* of such a result: the
+ * server maps it to 504 and `@husk-ai/sdk` decodes 504 back to it, so a proxy or
+ * gateway timing out a request still round-trips into a sensible `HuskError`.
+ */
+ | 'E_EXEC_TIMEOUT' | 'E_EXEC_DENIED' | 'E_FS_DENIED' | 'E_QUOTA' | 'E_MODEL_UNAVAILABLE' | 'E_MODEL_ERROR' | 'E_NO_CREDENTIALS' | 'E_SPEC_INVALID' | 'E_IMPORT_FAILED' | 'E_TOOL_ERROR' | 'E_BUDGET_EXCEEDED'
+/**
+ * Reserved. Nothing throws this.
+ *
+ * Hitting `limits.maxSteps` is a normal ending, not a failure: the run has
+ * real text, real messages and real usage to return, and the caller learns
+ * why it stopped from `RunResult.stopReason: 'step_limit'`. Throwing here
+ * would throw the run away with it.
+ */
+ | 'E_STEP_LIMIT' | 'E_ABORTED' | 'E_NOT_IMPLEMENTED' | 'E_CONFIG' | 'E_INTERNAL';
+/**
+ * Codes that are part of the contract but are never thrown by husk itself.
+ *
+ * They are declared so the status mapping in `@husk-ai/server` and the decoder in
+ * `@husk-ai/sdk` have something to name, and so removing one is a deliberate
+ * breaking change rather than an accident. The condition each describes
+ * surfaces as data -- `ExecResult.timedOut`, `RunResult.stopReason` -- because
+ * a timeout or a step ceiling is a result the caller wants to read, not an
+ * exception that destroys it.
+ */
+export declare const RESERVED_ERROR_CODES: readonly ["E_EXEC_TIMEOUT", "E_STEP_LIMIT"];
+export declare class HuskError extends Error {
+    readonly code: HuskErrorCode;
+    readonly details?: Record<string, unknown>;
+    /** A one-line, human-actionable next step. Surfaced verbatim by the CLI. */
+    readonly hint?: string;
+    constructor(code: HuskErrorCode, message: string, opts?: {
+        hint?: string;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+    toJSON(): {
+        name: string;
+        code: HuskErrorCode;
+        message: string;
+        hint: string | undefined;
+        details: Record<string, unknown> | undefined;
+    };
+}
+export declare function isHuskError(e: unknown): e is HuskError;
+/** Never throw from a cleanup path. */
+export declare function quiet<T>(fn: () => Promise<T>): Promise<T | undefined>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,wBAAwB,GACxB,sBAAsB,GACtB,mBAAmB,GACnB,eAAe;AACjB;;;;;;;;;;;GAWG;GACD,gBAAgB,GAChB,eAAe,GACf,aAAa,GACb,SAAS,GACT,qBAAqB,GACrB,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,mBAAmB;AACrB;;;;;;;GAOG;GACD,cAAc,GACd,WAAW,GACX,mBAAmB,GACnB,UAAU,GACV,YAAY,CAAC;AAEjB;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,6CAAiF,CAAC;AAEnH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAGrB,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;IASlF,MAAM;;;;;;;CAGP;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,SAAS,CAEtD;AAED,uCAAuC;AACvC,wBAAsB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAM3E"}

package/dist/errors.js

@@ -0,0 +1,40 @@
+/**
+ * Codes that are part of the contract but are never thrown by husk itself.
+ *
+ * They are declared so the status mapping in `@husk-ai/server` and the decoder in
+ * `@husk-ai/sdk` have something to name, and so removing one is a deliberate
+ * breaking change rather than an accident. The condition each describes
+ * surfaces as data -- `ExecResult.timedOut`, `RunResult.stopReason` -- because
+ * a timeout or a step ceiling is a result the caller wants to read, not an
+ * exception that destroys it.
+ */
+export const RESERVED_ERROR_CODES = ['E_EXEC_TIMEOUT', 'E_STEP_LIMIT'];
+export class HuskError extends Error {
+    code;
+    details;
+    /** A one-line, human-actionable next step. Surfaced verbatim by the CLI. */
+    hint;
+    constructor(code, message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.name = 'HuskError';
+        this.code = code;
+        this.hint = opts.hint;
+        this.details = opts.details;
+    }
+    toJSON() {
+        return { name: this.name, code: this.code, message: this.message, hint: this.hint, details: this.details };
+    }
+}
+export function isHuskError(e) {
+    return e instanceof HuskError;
+}
+/** Never throw from a cleanup path. */
+export async function quiet(fn) {
+    try {
+        return await fn();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AA6CA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,gBAAgB,EAAE,cAAc,CAA6C,CAAC;AAEnH,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAgB;IACpB,OAAO,CAA2B;IAC3C,4EAA4E;IACnE,IAAI,CAAU;IAEvB,YACE,IAAmB,EACnB,OAAe,EACf,OAA8E,EAAE;QAEhF,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC7E,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;IAC9B,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC7G,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,CAAU;IACpC,OAAO,CAAC,YAAY,SAAS,CAAC;AAChC,CAAC;AAED,uCAAuC;AACvC,MAAM,CAAC,KAAK,UAAU,KAAK,CAAI,EAAoB;IACjD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/ids.d.ts

@@ -0,0 +1,7 @@
+/** Short, URL-safe id. */
+export declare function id(prefix?: string, len?: number): string;
+/** Id with a millisecond time prefix -- sorts lexicographically by creation. */
+export declare function tid(prefix?: string): string;
+/** Deterministic, filesystem-safe slug. */
+export declare function slug(input: string, max?: number): string;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAIA,0BAA0B;AAC1B,wBAAgB,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,MAAM,CAKpD;AAED,gFAAgF;AAChF,wBAAgB,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3C;AAED,2CAA2C;AAC3C,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAK,GAAG,MAAM,CAWpD"}

package/dist/ids.js

@@ -0,0 +1,29 @@
+import { randomBytes } from 'node:crypto';
+const ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz'; // Crockford-ish, no i/l/o/u
+/** Short, URL-safe id. */
+export function id(prefix, len = 12) {
+    const bytes = randomBytes(len);
+    let out = '';
+    for (let i = 0; i < len; i++)
+        out += ALPHABET[bytes[i] % ALPHABET.length];
+    return prefix ? `${prefix}_${out}` : out;
+}
+/** Id with a millisecond time prefix -- sorts lexicographically by creation. */
+export function tid(prefix) {
+    const t = Date.now().toString(36).padStart(9, '0');
+    return `${prefix ? prefix + '_' : ''}${t}${id(undefined, 6)}`;
+}
+/** Deterministic, filesystem-safe slug. */
+export function slug(input, max = 48) {
+    const s = input
+        .normalize('NFKD')
+        .replace(/[^\w\s-]/g, '')
+        .trim()
+        .replace(/[\s_]+/g, '-')
+        .replace(/-+/g, '-')
+        .toLowerCase()
+        .slice(0, max)
+        .replace(/^-|-$/g, '');
+    return s || 'husk';
+}
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,QAAQ,GAAG,kCAAkC,CAAC,CAAC,4BAA4B;AAEjF,0BAA0B;AAC1B,MAAM,UAAU,EAAE,CAAC,MAAe,EAAE,GAAG,GAAG,EAAE;IAC1C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AAC3C,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,GAAG,CAAC,MAAe;IACjC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnD,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC;AAChE,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,IAAI,CAAC,KAAa,EAAE,GAAG,GAAG,EAAE;IAC1C,MAAM,CAAC,GAAG,KAAK;SACZ,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,IAAI,EAAE;SACN,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,WAAW,EAAE;SACb,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;SACb,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,CAAC,IAAI,MAAM,CAAC;AACrB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @husk-ai/core -- the contracts.
+ *
+ * Every other package depends on this one and nothing else in the workspace.
+ * If a type belongs to more than one package, it belongs here.
+ */
+export * from './ids.js';
+export * from './errors.js';
+export * from './logger.js';
+export * from './util.js';
+export * from './lifecycle.js';
+export * from './audit.js';
+export * from './config.js';
+export * from './spec.js';
+export * from './net.js';
+export * from './browse.js';
+export type { ProviderName, ComputerState, NetworkPolicy, MountSpec, Flavor, ComputerSpec, ComputerInfo, PortBinding, ExecRequest, ExecResult, DirEntry, WriteFileOptions, Computer, Availability, ComputerProvider, } from './types/computer.js';
+export type { Role, TextPart, ImagePart, ToolCallPart, ToolResultPart, ThinkingPart, ContentPart, ModelMessage, JSONSchema, ToolSchema, ToolChoice, ChatRequest, Usage, FinishReason, ChatResponse, StreamEvent, ModelInfo, ModelProvider, } from './types/model.js';
+export { messageText } from './types/model.js';
+export type { ToolContext, Tool, ApprovalMode, ApprovalRequest, Approver, RunOptions, RunEvent, RunResult, } from './types/agent.js';
+export type { TranscriptSource, TranscriptMessage, Transcript, ImportInput, TranscriptImporter, DistilledAgent, } from './types/transcript.js';
+export declare const HUSK_VERSION = "0.1.0";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAG5B,YAAY,EACV,YAAY,EACZ,aAAa,EACb,aAAa,EACb,SAAS,EACT,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,YAAY,EACZ,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,IAAI,EACJ,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,UAAU,EACV,UAAU,EACV,UAAU,EACV,WAAW,EACX,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,SAAS,EACT,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,YAAY,EACV,WAAW,EACX,IAAI,EACJ,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,SAAS,GACV,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,cAAc,GACf,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,YAAY,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * @husk-ai/core -- the contracts.
+ *
+ * Every other package depends on this one and nothing else in the workspace.
+ * If a type belongs to more than one package, it belongs here.
+ */
+export * from './ids.js';
+export * from './errors.js';
+export * from './logger.js';
+export * from './util.js';
+export * from './lifecycle.js';
+export * from './audit.js';
+export * from './config.js';
+export * from './spec.js';
+export * from './net.js';
+export * from './browse.js';
+export { messageText } from './types/model.js';
+export const HUSK_VERSION = '0.1.0';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAyC5B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAsB/C,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Things that must be torn down when a computer goes away.
+ *
+ * The leak this exists to close: a browser session outlives its computer.
+ * `@husk-ai/browser` keeps a Chromium running inside the machine and a `pkill` in
+ * `close()` to stop it -- but nothing called `close()` when the computer was
+ * destroyed. Only `DELETE /v1/computers/:id/browser` did, which is a route
+ * almost nobody calls. So every machine that ever opened a page left a browser
+ * running: measured, 23 `headless_shell` processes still alive the next day,
+ * each holding its workspace directory open so `husk rm` could not delete it
+ * and ~325 MB per machine stayed on disk.
+ *
+ * A registry rather than a direct call because of layering. `@husk-ai/runtime`
+ * owns the lifecycle and must not import `@husk-ai/browser` -- the browser is an
+ * optional thing built *on* computers, and a runtime that depended on it would
+ * drag Chromium provisioning into every install. So the runtime announces, and
+ * whoever cares subscribes.
+ */
+export type DestroyHook = (computerId: string) => void | Promise<void>;
+/**
+ * Run `fn` when any computer is destroyed. Returns an unsubscribe.
+ *
+ * Register at module load in the package that owns the resource, so the hook is
+ * in place before anything could have created one.
+ */
+export declare function onComputerDestroyed(fn: DestroyHook): () => void;
+/**
+ * Announce a destroyed computer and wait for every subscriber.
+ *
+ * Failures are swallowed deliberately: this runs on the teardown path, and a
+ * cleanup that throws must not stop the destroy it is cleaning up after, nor
+ * stop the other subscribers. A browser that cannot be closed is a smaller
+ * problem than a computer that cannot be removed.
+ */
+export declare function notifyComputerDestroyed(computerId: string): Promise<void>;
+/** Test seam. Not for production use -- hooks are registered at module load. */
+export declare function clearDestroyHooks(): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAIvE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,IAAI,CAG/D;AAED;;;;;;;GAOG;AACH,wBAAsB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/E;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}

package/dist/lifecycle.js

@@ -0,0 +1,52 @@
+/**
+ * Things that must be torn down when a computer goes away.
+ *
+ * The leak this exists to close: a browser session outlives its computer.
+ * `@husk-ai/browser` keeps a Chromium running inside the machine and a `pkill` in
+ * `close()` to stop it -- but nothing called `close()` when the computer was
+ * destroyed. Only `DELETE /v1/computers/:id/browser` did, which is a route
+ * almost nobody calls. So every machine that ever opened a page left a browser
+ * running: measured, 23 `headless_shell` processes still alive the next day,
+ * each holding its workspace directory open so `husk rm` could not delete it
+ * and ~325 MB per machine stayed on disk.
+ *
+ * A registry rather than a direct call because of layering. `@husk-ai/runtime`
+ * owns the lifecycle and must not import `@husk-ai/browser` -- the browser is an
+ * optional thing built *on* computers, and a runtime that depended on it would
+ * drag Chromium provisioning into every install. So the runtime announces, and
+ * whoever cares subscribes.
+ */
+const hooks = new Set();
+/**
+ * Run `fn` when any computer is destroyed. Returns an unsubscribe.
+ *
+ * Register at module load in the package that owns the resource, so the hook is
+ * in place before anything could have created one.
+ */
+export function onComputerDestroyed(fn) {
+    hooks.add(fn);
+    return () => hooks.delete(fn);
+}
+/**
+ * Announce a destroyed computer and wait for every subscriber.
+ *
+ * Failures are swallowed deliberately: this runs on the teardown path, and a
+ * cleanup that throws must not stop the destroy it is cleaning up after, nor
+ * stop the other subscribers. A browser that cannot be closed is a smaller
+ * problem than a computer that cannot be removed.
+ */
+export async function notifyComputerDestroyed(computerId) {
+    await Promise.all([...hooks].map(async (fn) => {
+        try {
+            await fn(computerId);
+        }
+        catch {
+            // teardown is best-effort by construction
+        }
+    }));
+}
+/** Test seam. Not for production use -- hooks are registered at module load. */
+export function clearDestroyHooks() {
+    hooks.clear();
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAe,CAAC;AAErC;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAAe;IACjD,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACd,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,UAAkB;IAC9D,MAAM,OAAO,CAAC,GAAG,CACf,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QAC1B,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,UAAU,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,0CAA0C;QAC5C,CAAC;IACH,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,iBAAiB;IAC/B,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,20 @@
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+export interface Logger {
+    level: LogLevel;
+    trace(msg: string, meta?: unknown): void;
+    debug(msg: string, meta?: unknown): void;
+    info(msg: string, meta?: unknown): void;
+    warn(msg: string, meta?: unknown): void;
+    error(msg: string, meta?: unknown): void;
+    child(scope: string): Logger;
+}
+export interface LoggerOptions {
+    level?: LogLevel;
+    scope?: string;
+    /** Emit newline-delimited JSON instead of pretty text. HUSK_LOG_JSON=1 forces it. */
+    json?: boolean;
+    sink?: (line: string) => void;
+}
+export declare function createLogger(opts?: LoggerOptions): Logger;
+export declare const log: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAIhF,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qFAAqF;IACrF,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAaD,wBAAgB,YAAY,CAAC,IAAI,GAAE,aAAkB,GAAG,MAAM,CAuC7D;AAUD,eAAO,MAAM,GAAG,QAAkC,CAAC"}

package/dist/logger.js

@@ -0,0 +1,59 @@
+const ORDER = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, silent: 99 };
+const CSI = String.fromCharCode(27) + '[';
+const RESET = CSI + '0m';
+const DIM = CSI + '2m';
+const COLOR = {
+    trace: CSI + '90m',
+    debug: CSI + '36m',
+    info: CSI + '32m',
+    warn: CSI + '33m',
+    error: CSI + '31m',
+};
+export function createLogger(opts = {}) {
+    const envLevel = process.env.HUSK_LOG_LEVEL;
+    const json = opts.json ?? process.env.HUSK_LOG_JSON === '1';
+    const sink = opts.sink ?? ((line) => process.stderr.write(line + '\n'));
+    const state = { level: opts.level ?? envLevel ?? 'info', scope: opts.scope ?? '' };
+    const useColor = !json && process.stderr.isTTY === true && !process.env.NO_COLOR;
+    function emit(level, msg, meta) {
+        if (ORDER[level] < ORDER[state.level])
+            return;
+        if (json) {
+            sink(JSON.stringify({ t: new Date().toISOString(), level, scope: state.scope || undefined, msg, meta }));
+            return;
+        }
+        const tag = useColor ? COLOR[level] + level.padEnd(5) + RESET : level.padEnd(5);
+        const scope = state.scope ? (useColor ? `${DIM}[${state.scope}]${RESET} ` : `[${state.scope}] `) : '';
+        let line = `${tag} ${scope}${msg}`;
+        if (meta !== undefined) {
+            const s = typeof meta === 'string' ? meta : safeStringify(meta);
+            line += useColor ? ` ${DIM}${s}${RESET}` : ` ${s}`;
+        }
+        sink(line);
+    }
+    const logger = {
+        get level() {
+            return state.level;
+        },
+        set level(l) {
+            state.level = l;
+        },
+        trace: (m, x) => emit('trace', m, x),
+        debug: (m, x) => emit('debug', m, x),
+        info: (m, x) => emit('info', m, x),
+        warn: (m, x) => emit('warn', m, x),
+        error: (m, x) => emit('error', m, x),
+        child: (scope) => createLogger({ ...opts, level: state.level, scope: state.scope ? `${state.scope}:${scope}` : scope }),
+    };
+    return logger;
+}
+function safeStringify(v) {
+    try {
+        return JSON.stringify(v, (_k, val) => (val instanceof Error ? { name: val.name, message: val.message } : val)) ?? '';
+    }
+    catch {
+        return String(v);
+    }
+}
+export const log = createLogger({ scope: 'husk' });
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

package/dist/net.d.ts

@@ -0,0 +1,48 @@
+import type { NetworkPolicy } from './types/computer.js';
+/**
+ * Network policy, in one place.
+ *
+ * This lived in three copies -- `@husk-ai/runtime`, `@husk-ai/agent`, and by
+ * implication the docs -- and they drifted: one blocked the cloud metadata
+ * endpoint in `mode: 'full'` and one did not. A security check with two answers
+ * is not a security check, so it lives here and everything re-exports it.
+ */
+/** Match a hostname against one pattern. Supports a single leading `*.` wildcard. */
+export declare function hostMatches(host: string, pattern: string): boolean;
+export declare function isInternalHost(host: string): boolean;
+/** Loopback specifically, as distinct from the rest of the private ranges. */
+export declare function isLoopbackHost(host: string): boolean;
+/** Whether this provider's loopback belongs to the computer rather than the host. */
+export declare function ownsLoopback(provider: string): boolean;
+/**
+ * Whether the computer shares a network stack with whoever is running husk.
+ *
+ * The inverse of {@link ownsLoopback}, named for the thing a caller usually
+ * wants to warn about.
+ */
+export declare function sharesHostNetwork(provider: string): boolean;
+export interface HostPolicyContext {
+    /**
+     * True when this computer's loopback is its own, not the host's.
+     *
+     * The whole point of the loopback rule is to stop an agent reaching the
+     * *host's* services. On docker, podman and fly, `127.0.0.1` inside the
+     * computer is a separate network namespace, so "start a dev server and look
+     * at it" -- the single most common thing an agent does -- is both safe and
+     * necessary. On the `local` provider loopback is literally the host's, and on
+     * `ssh` it is a box the user may well be running things on, so both stay shut
+     * unless the operator names the host in `allow`.
+     */
+    loopbackIsOwn?: boolean;
+}
+export declare function isHostAllowed(host: string, policy: NetworkPolicy | undefined, ctx?: HostPolicyContext): boolean;
+/** The hostname of a URL, or null when it does not parse. */
+export declare function urlHost(url: string): string | null;
+/**
+ * Parse and authorise a URL in one step.
+ *
+ * Returns the parsed URL so a caller cannot accidentally check one string and
+ * then fetch a different one.
+ */
+export declare function assertUrlAllowed(url: string, policy: NetworkPolicy | undefined, ctx?: HostPolicyContext): URL;
+//# sourceMappingURL=net.d.ts.map

package/dist/net.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net.d.ts","sourceRoot":"","sources":["../src/net.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;GAOG;AAEH,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CASlE;AAuDD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAmBpD;AAED,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMpD;AAiBD,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,GAAG,GAAE,iBAAsB,GAC1B,OAAO,CA0BT;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMlD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,GAAG,GAAE,iBAAsB,GAC1B,GAAG,CAiCL"}