@byok-sdk/client 0.2.0 → 0.3.0

package/dist/daemon/create-daemon.d.ts

@@ -1,6 +1,6 @@
 import type { RuntimeId } from '@byok-sdk/protocol';
 import type { PermissionPolicy } from '@byok-sdk/protocol';
-import type { RuntimeAdapter, GitWorkspaceConfig } from '../types';
+import type { RuntimeAdapter, GitWorkspaceConfig, McpToolsetConfig } from '../types';
 import type { BackoffOptions, LivenessOptions } from './ws-transport';
 import { type OperationalHealthSnapshot } from './operational-health';
 import { type DaemonEventListener, type DaemonTaskInfo, type Unsubscribe } from './observer';
@@ -10,6 +10,7 @@ import { type DeviceRecord } from './store';
 import { type LocalTaskJournal } from './journal/journal';
 import { type JournalOpenFaultSeam } from './journal/sqlite-support';
 import { LocalStoragePressureEngine, type LocalStoragePolicyInput } from './journal/storage-policy';
+import { type ResultDocumentExtractor } from './task-runner';
 import type { ProgressBatcherOptions } from './progress-batcher';
 /**
  * Optional white-label product display info — purely opaque passthrough
@@ -104,6 +105,12 @@ export interface DaemonConfig {
      * unchanged from M1/M2.
      */
     runtimeAllowlist?: string[];
+    /**
+     * Separate-process Pi BYOK credential boundary. Required only for a
+     * `dispatchSelection` in the BYOK lane; subscription runtimes and legacy
+     * Pi tasks do not invoke it.
+     */
+    piByokLauncher?: import('../adapters/pi/pi-adapter').PiByokLauncherConfig;
     /**
      * M5 batch-3 (workstream 1): explicit auto-select priority order for
      * `TaskRunner.pickAdapter`'s no-explicit-runtime branch (`task-runner.ts`)
@@ -175,6 +182,13 @@ export interface DaemonConfig {
     runtimeEnvironment?: Record<string, {
         allow?: string[];
     }>;
+    /**
+     * Device-local registry behind wire-level `requiredToolsets` ids. Only
+     * logical ids cross the SaaS wire; MCP executable definitions stay here.
+     * The first slice supports stdio servers (`command` + `args`) only and
+     * deliberately has no task-provided env/header/secret surface.
+     */
+    mcpToolsets?: Record<string, McpToolsetConfig>;
     /**
      * M5: explicit escape hatch for `url.ts`'s `assertServerUrlAllowed` — see
      * that function's own doc comment for the full allow/deny rule. Default
@@ -209,6 +223,48 @@ export interface DaemonConfig {
      * explicitly instead to opt out of enforcement altogether.
      */
     maxTaskOutputBytes?: number;
+    /**
+     * additive-minor (`task.complete.document`): the seam through which this
+     * product turns a finished task's final output text into the STRUCTURED
+     * terminal result the wire carries as `task.complete.document`, and the
+     * server projects into `TaskResult.document`.
+     *
+     * `extract(finalOutput, task)` is called exactly once per task, at the
+     * moment `task.complete` is built, with the same text that becomes
+     * `summary` (the concatenated `progress` events for that task) plus the
+     * task's `taskId`/`sessionRef`. Return `undefined` for "no structured
+     * result this time". Everything about the document's SHAPE is the
+     * product's business — the SDK never inspects, validates, or transforms
+     * it; extraction logic (prompting for JSON, parsing a fenced block,
+     * validating against the product's own schema) is product glue and belongs
+     * in this callback, not in the SDK.
+     *
+     * The SDK enforces exactly two wire rules, via the protocol's own
+     * `checkResultDocument`: the value must be JSON-serializable, and at most
+     * `RESULT_DOCUMENT_MAX_BYTES` (1 MiB) as canonical JSON. Stay under ~512
+     * KiB in practice (docs/protocol.md); a bigger result belongs in an
+     * artifact, not here.
+     *
+     * FAIL-CLOSED, never silent: if the extractor throws, returns a promise
+     * (the seam is synchronous and the runtime enforces it — an unawaited
+     * promise would be encoded as an empty document), produces something
+     * unsendable, or produces a document while the connected server never
+     * advertised the `result-document` capability (an old server would strip
+     * the field on arrival without a word), the task is reported as
+     * `task.fail` with `retryable: false` and a reason prefixed
+     * `result document undeliverable` — see
+     * `RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX` (`task-runner.ts`).
+     * Completing a task while quietly discarding the structured result it
+     * exists to produce is not an option this SDK offers.
+     *
+     * Omitted entirely by default, in which case the completion path is
+     * unchanged in every respect — no extractor call, no capability check, and
+     * a `task.complete` payload byte-identical to the one sent before this
+     * field existed.
+     */
+    resultDocument?: {
+        readonly extract: ResultDocumentExtractor;
+    };
     /**
      * M5 batch-3 (workstream 2): deadline bound on the graceful-shutdown
      * sequence's own wait for `TaskRunner.shutdownActiveTasks` to finish
@@ -221,6 +277,85 @@ export interface DaemonConfig {
      * existed.
      */
     shutdownGraceMs?: number;
+    /**
+     * Cadence for the `online` presence heartbeat (§12.3), when — and only when
+     * — the deployment's capability declaration contains `presence.hints` (see
+     * `capabilities-client.ts`; a deployment that declares nothing, or one this
+     * daemon could not read a declaration from, publishes nothing at all).
+     *
+     * Every field is optional and defaults to `presence-publisher.ts`'s own
+     * constants, which are chosen against the hosted defaults. `ttlMs` and
+     * `minimumIntervalMs` describe THE DEPLOYMENT's hint TTL and publication
+     * throttle as this operator understands them: the daemon never learns either
+     * from the wire, and uses them only to validate `intervalMs` sits strictly
+     * between them — a cadence outside that band is rejected synchronously here,
+     * the same way `maxTaskOutputBytes` is above, rather than degrading into a
+     * rate-limited or flickering hint nobody sees an error for.
+     */
+    presence?: PresenceConfig;
+    /**
+     * Plan `device-assertion-broker`: opt-in local assertion broker — lets a
+     * sibling process on this same machine (typically the host's own CLI,
+     * installed alongside this daemon) ask the daemon, over the already
+     * authenticated control socket, to mint a short-lived audience-scoped
+     * assertion signed with the paired device key. See
+     * {@link DeviceAssertionConfig}.
+     *
+     * OFF by default, and off is expressed two ways that mean the same thing: an
+     * absent section, or a present one with an empty `audiences` list. Both make
+     * `assertion.issue` answer `assertion_disabled` without looking at anything
+     * else. A new local authentication surface does not get to be on because
+     * someone left a config key behind.
+     */
+    deviceAssertion?: DeviceAssertionConfig;
+}
+/**
+ * Plan `device-assertion-broker`. Two fields, both about what this daemon will
+ * refuse.
+ *
+ * Every field is validated synchronously at construction, the same way
+ * `maxTaskOutputBytes` and the presence cadence are — a misconfigured
+ * authentication surface must fail when the daemon is built, not on the first
+ * call that needed it.
+ */
+export interface DeviceAssertionConfig {
+    /**
+     * The EXACT audience strings this daemon will mint for. Matched with
+     * `Set.has` — exact string equality, never a prefix or suffix or subdomain
+     * rule.
+     *
+     * Prefix matching is the classic hole here: an allowlist entry of
+     * `salesko-api` under a `startsWith` rule also admits `salesko-api.evil.com`,
+     * and a suffix rule admits `evil-salesko-api`. There is no configuration
+     * that turns this into a pattern match, because there is no pattern-matching
+     * code to configure.
+     *
+     * An empty list means the feature is off (see
+     * `DaemonConfig.deviceAssertion`). Duplicate entries, empty entries, and
+     * entries over 256 UTF-8 bytes are construction errors — a duplicate is
+     * usually a copy-paste that hid a typo'd second entry, and silently
+     * de-duplicating it would hide it for good.
+     */
+    audiences: string[];
+    /**
+     * Assertion lifetime, ms. Default
+     * `DEVICE_ASSERTION_DEFAULT_TTL_MS` (120s), hard ceiling
+     * `DEVICE_ASSERTION_MAX_TTL_MS` (300s) — both from `@byok-sdk/core`, which
+     * enforces the same ceiling again at verification time, so a daemon patched
+     * to ignore this one still cannot get a longer-lived assertion accepted.
+     *
+     * Deliberately NOT caller-selectable over the control socket: a lifetime a
+     * caller can ask for is a lifetime every caller asks the maximum of.
+     */
+    ttlMs?: number;
+}
+export interface PresenceConfig {
+    /** Heartbeat cadence. Default 30s. */
+    intervalMs?: number;
+    /** The deployment's presence hint TTL. Default 90s (core §12.7.5 suggests 60-120s). */
+    ttlMs?: number;
+    /** The deployment's minimum interval between accepted publications. Default 5s. */
+    minimumIntervalMs?: number;
 }
 export interface DaemonStatus {
     paired: boolean;
@@ -340,7 +475,40 @@ export interface DaemonOverrides {
         pressureEngine?: LocalStoragePressureEngine;
     };
 }
+/**
+ * Plan `device-assertion-broker` (codex round-2 F3): the internal, NON-public
+ * test seam for observing assertion issuance.
+ *
+ * This is NOT reachable through `DaemonConfig`/`DaemonOverrides`, and is NOT
+ * re-exported from the package `index.ts` — a test imports it straight from
+ * this module. That isolation is the point. The earlier `DaemonOverrides.
+ * deviceAssertion.mint` seam replaced the SIGNER, which meant a production
+ * embedder (`DaemonOverrides` is public API) could inject a callback that
+ * received the whole `DeviceRecord` — private key included — and exfiltrate it
+ * or forge claims.
+ *
+ * `onIssued` is a strict OBSERVER, called only AFTER a real, successful sign,
+ * with non-secret metadata ONLY (`jti`, `audience`). It cannot see the private
+ * key, cannot alter the signature, the claims, or the audit event, and cannot
+ * be reached from any public type. A test counts these calls to prove a gate
+ * rejection never reached the signer (a rejection never calls `onIssued`).
+ */
+export interface AssertionIssueProbe {
+    onIssued(meta: {
+        jti: string;
+        audience: string;
+    }): void;
+}
 export declare function createDaemonWithAdapters(config: DaemonConfig, adapters: RuntimeAdapter[], overrides?: DaemonOverrides): Daemon;
+/**
+ * codex round-2 F3: the real builder. Exported from THIS module but NOT from
+ * the package `index.ts`, so the optional `assertionProbe` (an
+ * {@link AssertionIssueProbe} post-sign observer) is reachable only by tests
+ * importing this module directly — never through any public type. The public
+ * `createDaemonWithAdapters` above forwards without it, so production has no
+ * observer and no signer-injection surface at all.
+ */
+export declare function buildDaemonWithAdapters(config: DaemonConfig, adapters: RuntimeAdapter[], overrides?: DaemonOverrides, assertionProbe?: AssertionIssueProbe): Daemon;
 /**
  * Public white-label entry point (M0-M3): the "5-line launcher" — a product
  * only needs a `DaemonConfig`, no hand-built adapter list. The bundled

package/dist/daemon/daemon-owner.d.ts

@@ -11,6 +11,41 @@ interface OwnerRecord {
 export interface DaemonOwnerLease {
     release(): Promise<void>;
 }
+/**
+ * Where this store's lock lives. Keyed by the CANONICAL storeDir alone — not
+ * by product id or OS user — because the store is the resource being
+ * serialized: a symlink alias and its target, or two products pointed at one
+ * store directory, must contend for the same endpoint (see
+ * `acquireDaemonOwner`'s own note on resolving aliases before deriving this).
+ *
+ * POSIX prefers `<storeDir>/mutex.sock`, keeping the lock beside the store
+ * state it guards in a directory `ensureSecureDir` has already made 0700. A
+ * storeDir can be long enough that no address under it fits
+ * {@link UNIX_SOCKET_PATH_SOFT_LIMIT} — a storeDir alone can exceed the whole
+ * `sun_path` budget — so the second candidate drops the storeDir from the path
+ * entirely and carries it as a hash under {@link STORE_MUTEX_FALLBACK_ROOT},
+ * nested one level deep so that directory can be created 0700 BEFORE anything
+ * binds inside it (the nesting convention is `controlSocketPath`'s).
+ *
+ * `controlSocketPath` reaches for `os.tmpdir()` at this point; this must not,
+ * for two independent reasons proven by CI job 94334133652. Correctness:
+ * `os.tmpdir()` is environment-derived, and a lock address that differs
+ * between two contending processes admits two writers. Reachability: the
+ * caller may have pointed `TMPDIR` INSIDE the very tree that made the natural
+ * path too long — there, `os.tmpdir()` yields an address LONGER than the one
+ * being escaped (152 bytes vs 126 in that job), so the "fallback" cannot bind
+ * at all. A fixed short root is immune to both.
+ *
+ * win32 has no socket file to place; a named pipe lives in one flat
+ * machine-wide namespace, so the name carries the store hash to keep two
+ * stores from colliding, and no length branch is needed.
+ *
+ * @internal Exported for the regression guard only (never re-exported from
+ * `index.ts`): the crashed-holder recovery path can only be exercised by
+ * planting a stale socket file at the exact address this derives, and a test
+ * recomputing the derivation itself would prove nothing about this one.
+ */
+export declare function storeMutexEndpoint(canonicalStoreDir: string, identity: string, platform?: NodeJS.Platform): string;
 export declare class DaemonOwnerActiveError extends Error {
     readonly role: OwnerRecord['role'] | 'unknown';
     constructor(role: OwnerRecord['role'] | 'unknown');

package/dist/daemon/device-assertion-signer.d.ts

@@ -0,0 +1,41 @@
+import { type DeviceAssertionClaims, type DeviceAssertionEnvelopeV1 } from '@byok-sdk/core';
+import type { DeviceRecord } from './store';
+/**
+ * Mints one device assertion (plan `device-assertion-broker`).
+ *
+ * This module exists so there is exactly ONE place in the client that touches
+ * the device private key for this envelope, and so "the key is never cached"
+ * is a property of a small readable file rather than a claim about a
+ * 2000-line one. Two rules it enforces structurally:
+ *
+ * 1. **No module-level key state.** There is no cache, no memo, no
+ *    module-scope variable of any kind here. The `KeyObject` is created inside
+ *    {@link mintDeviceAssertion} from the record the caller just read off disk
+ *    and becomes unreachable when the function returns — the same
+ *    read-the-store-every-time discipline `StoredDeviceProofSigner` documents,
+ *    for the same reason: clearing `device.json` must remove local signing
+ *    authority immediately, not at the next process restart.
+ * 2. **The caller supplies the record.** This function does not load the
+ *    store, check revocation, or consult an allowlist. All of that is the
+ *    daemon's fail-closed gate sequence (`create-daemon.ts`), and duplicating
+ *    any of it here would create a second, quieter authority on whether an
+ *    assertion may be minted at all.
+ */
+export interface MintDeviceAssertionInput {
+    /** The record just read from disk — never a cached one. */
+    readonly record: DeviceRecord;
+    /** The paired server's normalized origin (`url.ts`'s `toHttpBase` → `origin`). */
+    readonly issuer: string;
+    readonly productId: string;
+    /** Already checked against the configured allowlist by the caller. */
+    readonly audience: string;
+    /** Already range-checked at daemon construction time. */
+    readonly ttlMs: number;
+    readonly now: Date;
+}
+export interface MintedDeviceAssertion {
+    readonly envelope: DeviceAssertionEnvelopeV1;
+    readonly claims: DeviceAssertionClaims;
+    readonly expiresAt: string;
+}
+export declare function mintDeviceAssertion(input: MintDeviceAssertionInput): MintedDeviceAssertion;

package/dist/daemon/device-keys.d.ts

@@ -24,22 +24,24 @@ export declare function exportPrivateKeyPem(privateKey: KeyObject): string;
 export declare function importPrivateKeyPem(pem: string): KeyObject;
 /**
  * S1 (GAP-004): the domain-separation prefix this device signs along with a
- * challenge nonce, byte-identical to the server's own
- * `NONCE_SIGNING_DOMAIN` (`packages/server/src/auth.ts`). The device key is a
- * long-lived identity key that later planes will also sign structured
- * messages with; tagging the domain is what stops a signature made for one of
- * those from being replayable as a token-renewal credential.
+ * challenge nonce. The device key is a long-lived identity key that later
+ * planes will also sign structured messages with; tagging the domain is what
+ * stops a signature made for one of those from being replayable as a
+ * token-renewal credential.
  *
- * Not shared through a package: the two ends agree on a wire constant, and
- * inventing a dependency between server and client to hold one string literal
- * would couple them far harder than the literal does.
+ * The literal itself now lives in `@byok-sdk/core` (`src/pairing.ts`), which
+ * the daemon, the hosted surface, and the reference server all already depend
+ * on. It used to be three copies, each commented as byte-identical to the
+ * others — an agreement that holds only until someone edits one of them.
+ * Re-exported here so this module's public surface is unchanged.
  */
-export declare const NONCE_SIGNING_DOMAIN = "byok-nonce-v1\n";
+export { NONCE_SIGNING_DOMAIN } from '@byok-sdk/core';
 /**
  * Sign a challenge nonce with the device private key: the signed message is
- * {@link NONCE_SIGNING_DOMAIN} followed by `nonce` (UTF-8), and the result is
- * the raw 64-byte Ed25519 signature, base64url-encoded (protocol §6.2). A
- * server on the domain-separated contract rejects the undomained form, so
- * there is no variant of this that omits the prefix.
+ * `NONCE_SIGNING_DOMAIN` followed by `nonce` (UTF-8) — core's
+ * {@link nonceSigningBytes} produces those bytes — and the result is the raw
+ * 64-byte Ed25519 signature, base64url-encoded (protocol §6.2). A server on the
+ * domain-separated contract rejects the undomained form, so there is no variant
+ * of this that omits the prefix.
  */
 export declare function signNonce(privateKey: KeyObject, nonce: string): string;

package/dist/daemon/observer.d.ts

@@ -20,8 +20,8 @@ import type { ConnectionState } from './ws-transport';
  * - `ConnectionManagerOptions.onEnvelope`/`onStateChange` — likewise already
  *   `create-daemon.ts`'s own closures (`(envelope) =>
  *   runner?.handleEnvelope(envelope)`, `(state) => { connectionState = state;
- *   }`). `onEnvelope` additionally exposes the raw INBOUND `task.offer` — the
- *   one event with no corresponding outbound envelope of its own — see
+ *   }`). `onEnvelope` additionally exposes the raw INBOUND offer variants —
+ *   the one event class with no corresponding outbound envelope of its own — see
  *   `handleInboundEnvelope`.
  *
  * Neither seam required adding anything to `TaskRunnerDeps`/`TaskRunner`
@@ -188,6 +188,50 @@ export type DaemonEvent = {
         conflicted: number;
     };
     errorCategory?: string;
+}
+/**
+ * Plan `device-assertion-broker`: one `assertion.issue` control call
+ * resolved — either an assertion was minted (`issued`) or one of the six
+ * fail-closed gates refused (`denied`, with `reason` naming which one; see
+ * `ASSERTION_ISSUE_ERROR_CODES`, `control-protocol.ts`).
+ *
+ * ONE kind for both outcomes, so an operator reading the feed sees the
+ * issuance rate and the refusal rate on the same line shape rather than
+ * having to correlate two.
+ *
+ * The signature and the envelope bytes are NOT fields of this event and
+ * never can be. That is structural, not a redaction rule: `bin/audit-log.ts`
+ * can only drop what it is handed, and an event type that cannot carry a
+ * signature cannot leak one into a durable file no matter how the audit
+ * projection is later edited. What IS carried is the metadata an incident
+ * needs — which audience, which `jti` (so a suspect assertion presented to
+ * the host's cloud can be traced back to the exact local call that minted
+ * it), and when it expires.
+ *
+ * codex round-2 F4 — the union is split by `result` for the same structural
+ * reason: on the ISSUED path `audience` came from this daemon's own
+ * configured allowlist (operator-authored, safe verbatim), but on the DENIED
+ * path it is whatever the CALLER sent — free text that could be a PEM, a
+ * signature, or any secret shaped as an audience. So the denied variant has
+ * NO raw `audience` field at all; it carries only `audienceSize` (a byte
+ * count), computed at event-construction time (`noteDeviceAssertion`). The
+ * raw denied audience therefore never reaches the observer feed, `format.ts`,
+ * daemon stdout, or the audit file — there is no field to carry it, rather
+ * than a redactor that has to remember to strip it.
+ */
+ | {
+    kind: 'device-assertion';
+    ts: string;
+    result: 'issued';
+    audience: string;
+    jti: string;
+    expiresAt: string;
+} | {
+    kind: 'device-assertion';
+    ts: string;
+    result: 'denied';
+    reason: string;
+    audienceSize?: number;
 };
 export type DaemonEventListener = (event: DaemonEvent) => void;
 export type Unsubscribe = () => void;
@@ -246,7 +290,7 @@ export declare class DaemonObserver {
     tasks(): DaemonTaskInfo[];
     /**
      * Feed a raw INBOUND (server -> daemon) envelope. Deliberately narrow: only
-     * `task.offer` produces a local event here — every other inbound type
+     * either offer variant produces a local event here — every other inbound type
      * (`task.cancel`/`task.steer`/`task.approve`/`task.reject`) is a
      * best-effort notification whose OWN observable effect already surfaces
      * through the daemon's outbound envelopes (`task.cancelled`, `task.progress`
@@ -269,6 +313,27 @@ export declare class DaemonObserver {
     noteShutdownRequested(reason: string): void;
     /** M4 Phase 2: see the `shutdown-complete` `DaemonEvent` variant's own doc comment (finding F5(b): `undeliveredOutboxCount`). */
     noteShutdownComplete(reason: string, undeliveredOutboxCount?: number): void;
+    /**
+     * Plan `device-assertion-broker`: see the `device-assertion` `DaemonEvent`
+     * variant's own doc comment. The parameter type is what keeps the signature
+     * out — there is no field to pass one through.
+     *
+     * codex round-2 F4: the DENIED caller can pass its raw `audience` here, but
+     * it is converted to a byte SIZE the instant the event is constructed and the
+     * raw string is dropped — it is never placed on the emitted `DaemonEvent`, so
+     * it cannot reach a subscriber, `format.ts`, stdout, or the audit file. The
+     * ISSUED `audience` came from the allowlist and is kept verbatim.
+     */
+    noteDeviceAssertion(event: {
+        result: 'issued';
+        audience: string;
+        jti: string;
+        expiresAt: string;
+    } | {
+        result: 'denied';
+        reason: string;
+        audience?: string;
+    }): void;
     /** M4 Phase 3 hardening: see the `stale-approval-decision` `DaemonEvent` variant's own doc comment. */
     noteStaleApprovalDecision(taskId: string, decision: 'approve' | 'reject', reason?: string): void;
     noteGitWorkspace(event: {

package/dist/daemon/presence-publisher.d.ts

@@ -0,0 +1,69 @@
+import type { AuthManager } from './auth-manager';
+/**
+ * Client-side defaults, chosen against the hosted defaults
+ * (`@byok-sdk/cloud`'s `DEFAULT_PRESENCE_TTL_MS` = 90s,
+ * `DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS` = 5s) and core §12.7.5's suggested
+ * 60-120s presence TTL. Spelled out here rather than imported: the daemon must
+ * not depend on the hosted package, and these are this producer's own cadence
+ * expectations, not a mirror of any deployment's configuration.
+ *
+ * The invariant that matters is `minimumIntervalMs < intervalMs < ttlMs`,
+ * asserted in the constructor: beat faster than the store's throttle and every
+ * other beat is rejected as `hint_rate_limited`; beat slower than the TTL and
+ * the device flickers offline between beats.
+ */
+export declare const DEFAULT_PRESENCE_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const DEFAULT_PRESENCE_TTL_MS = 90000;
+export declare const DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS = 5000;
+/**
+ * The cadence invariant, as a function so the two places that need it — this
+ * module's constructor and `create-daemon.ts`'s synchronous config validation —
+ * share one authority instead of two spellings of the same band.
+ *
+ * @throws {Error} when the cadence is outside `minimumIntervalMs < intervalMs < ttlMs`.
+ */
+export declare function assertPresenceHeartbeatCadence(cadence: {
+    intervalMs: number;
+    ttlMs: number;
+    minimumIntervalMs: number;
+}): void;
+export interface PresencePublisherOptions {
+    serverUrl: string;
+    auth: AuthManager;
+    /** Heartbeat cadence. Must sit strictly between {@link PresencePublisherOptions.minimumIntervalMs} and {@link PresencePublisherOptions.ttlMs}. */
+    intervalMs?: number;
+    /** The deployment's presence hint TTL, as this daemon understands it. Only used to validate the cadence. */
+    ttlMs?: number;
+    /** The deployment's minimum accepted interval between publications, as this daemon understands it. Only used to validate the cadence. */
+    minimumIntervalMs?: number;
+    /**
+     * Observable degradation sink — one line per publish failure and one for the
+     * permanent stop. The daemon passes its `console.warn` convention; tests read
+     * it directly instead of scraping stdout.
+     */
+    onDegraded?: (reason: string) => void;
+}
+/**
+ * Periodic `online` heartbeat. Construct once per `start()`, {@link stop} it in
+ * the shutdown sequence.
+ *
+ * The loop is a self-rescheduling `setTimeout` rather than `setInterval`: a slow
+ * publish must delay the next beat, not queue a second one behind it.
+ */
+export declare class PresencePublisher {
+    private readonly opts;
+    private readonly url;
+    private readonly intervalMs;
+    private timer;
+    private running;
+    /** Set once a revoked device is observed. Terminal: `start()` will not restart this instance. */
+    private stoppedPermanently;
+    constructor(opts: PresencePublisherOptions);
+    /** Publishes immediately, then every `intervalMs`. Idempotent; a no-op after a permanent stop. */
+    start(): void;
+    /** Stops the cadence. Idempotent, and the only "offline" signal this producer emits — the hint's TTL does the rest. */
+    stop(): void;
+    private schedule;
+    private beat;
+    private stopPermanently;
+}

package/dist/daemon/skill-pack-installer.d.ts

@@ -0,0 +1,116 @@
+import { type CapabilityDeclaration } from '@byok-sdk/core';
+import type { AuthManager } from './auth-manager';
+/**
+ * The hosted capability this pipeline gates on. A plain string, not an import
+ * from `@byok-sdk/cloud`: the daemon must not gain a dependency on the hosted
+ * implementation, and ADR-010 makes capability names deployment vocabulary that
+ * core validates the shape of but never the meaning of. Same rule the presence
+ * producer's `PRESENCE_HINTS_CAPABILITY` follows.
+ */
+export declare const SKILL_PACKS_CAPABILITY = "skills.pack";
+/** Directory under `dataDir` this module owns end to end. */
+export declare const SKILL_PACKS_DIRNAME = "skill-packs";
+/** Per-pack pointer at the installed content-addressed revision. */
+export declare const SKILL_PACK_LOCK_FILENAME = "lock.json";
+/** Append-only install/refusal record, beside the packs it describes. */
+export declare const SKILL_PACK_AUDIT_FILENAME = "audit.jsonl";
+export declare const SKILL_PACK_LOCK_SCHEMA = "byok-skill-pack-lock-v1";
+/**
+ * Ceiling on a single HTTP response this pipeline will read into memory.
+ *
+ * Deliberately derived from the pack cap rather than chosen independently: the
+ * largest legitimate manifest list is bounded by what a pack may declare, and a
+ * response beyond that is refused before it is parsed rather than after. A
+ * transfer cap that is not evaluated is the exact failure this plan set out not
+ * to repeat.
+ */
+export declare const SKILL_PACK_RESPONSE_MAX_BYTES: number;
+export declare const SKILL_PACK_INSTALL_ERROR_CODES: readonly ['capability_unavailable', 'transport_failed', 'response_invalid', 'response_too_large', 'manifest_invalid', 'content_rejected', 'store_unsafe'];
+export type SkillPackInstallErrorCode = (typeof SKILL_PACK_INSTALL_ERROR_CODES)[number];
+/**
+ * Every way an install can be refused, as one type with a `code`.
+ *
+ * Code-based branching rather than a class per failure — the same idiom
+ * `@byok-sdk/core` uses — because a caller only ever needs two decisions from
+ * this: "was the channel unavailable" (retry later, or the deployment simply
+ * does not offer it) versus "was the content refused" (a publication problem
+ * nobody on this device can fix by retrying).
+ */
+export declare class SkillPackInstallError extends Error {
+    readonly code: SkillPackInstallErrorCode;
+    readonly packName: string | undefined;
+    constructor(code: SkillPackInstallErrorCode, message: string, options?: {
+        cause?: unknown;
+        packName?: string;
+    });
+}
+/** What a device recorded about one installed pack. Mirrors `lock.json` on disk. */
+export interface SkillPackLock {
+    readonly schema: typeof SKILL_PACK_LOCK_SCHEMA;
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly content_hash: string;
+    /** The deployment the pack came from, normalized to its http(s) origin. Never a token, never a path. */
+    readonly source: string;
+    readonly installed_at: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly sha256: string;
+        readonly bytes: number;
+    }[];
+}
+export interface InstalledSkillPack {
+    readonly name: string;
+    readonly lock: SkillPackLock;
+    /** Absolute path of the content-addressed revision `lock.json` points at. */
+    readonly directory: string;
+}
+export interface InstallSkillPacksOptions {
+    /** The SDK data directory. A daemon passes its `storeDir`; the pack tree lives beside its other private state. */
+    readonly dataDir: string;
+    readonly serverUrl: string;
+    readonly auth: AuthManager;
+    /** The declaration read from `GET /byok/capabilities`. Never re-derived here, and never assumed. */
+    readonly declaration: CapabilityDeclaration;
+    readonly signal?: AbortSignal;
+}
+export interface SkillPackInstallResult {
+    readonly installed: readonly InstalledSkillPack[];
+    /** Packs already present at the same content hash. Re-installing is a no-op, not a rewrite. */
+    readonly unchanged: readonly string[];
+}
+/** The store root this module owns. */
+export declare function skillPacksRoot(dataDir: string): string;
+/**
+ * Fetches, verifies and installs every pack this deployment offers.
+ *
+ * @throws {SkillPackInstallError} `capability_unavailable` before any request
+ * is issued when the declaration does not name `skills.pack`.
+ */
+export declare function installSkillPacks(options: InstallSkillPacksOptions): Promise<SkillPackInstallResult>;
+/**
+ * Every pack this device has a valid lock for, sorted by name.
+ *
+ * Reads only the locks — never the pack bytes — so a caller listing what is
+ * installed pays nothing for packs it is not about to project.
+ */
+export declare function listInstalledSkillPacks(dataDir: string): Promise<readonly InstalledSkillPack[]>;
+export interface ProjectedSkillPack {
+    readonly name: string;
+    readonly contentHash: string;
+    readonly targetDir: string;
+    readonly files: readonly string[];
+}
+/**
+ * Copies an installed pack's files into a host-chosen directory.
+ *
+ * Copy, not symlink, and re-verified on the way out: the store is on the same
+ * machine as whatever else runs there, so the bytes are hashed again and
+ * compared against the lock before they are handed to a runtime. An install
+ * that was verified last week is not evidence about the file on disk today.
+ *
+ * @throws {SkillPackInstallError} `store_unsafe` for a missing pack, a symlink
+ * anywhere in the pack, or a file whose bytes no longer match the lock.
+ */
+export declare function projectSkillPack(dataDir: string, name: string, targetDir: string): Promise<ProjectedSkillPack>;