@byok-sdk/client 0.1.1 → 0.3.0

package/dist/daemon/task-runner.d.ts

@@ -1,5 +1,5 @@
-import { type Envelope, type PermissionPolicy, type RuntimeId, type TaskOfferPayload } from '@byok-sdk/protocol';
-import { type RuntimeAdapter } from '../types';
+import { type Envelope, type PermissionPolicy, type RuntimeId, type TaskOfferPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+import { type McpToolsetConfig, type RuntimeAdapter } from '../types';
 import { type ApprovalDecision, type ApprovalOrigin, type ApprovalRegistry } from './approvals';
 import type { BlobResolver } from './blob-client';
 import type { TaskQueueWatermark } from './control-protocol';
@@ -101,6 +101,56 @@ export declare const MAX_TRACKED_TASK_IDS = 2000;
 export declare const MAX_DURATION_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxDurationMs";
 /** M5 batch-3 (workstream 2): same contract as {@link MAX_DURATION_EXCEEDED_REASON_PREFIX}, for `DaemonConfig.maxTaskOutputBytes` — see `TaskRunner.pump`'s own per-event byte counting. */
 export declare const MAX_OUTPUT_BYTES_EXCEEDED_REASON_PREFIX = "resource limit exceeded: maxTaskOutputBytes";
+/**
+ * additive-minor (`task.complete.document`): same stable-PREFIX contract as
+ * {@link MAX_DURATION_EXCEEDED_REASON_PREFIX} above, carried by every
+ * `task.fail` this daemon reports because a configured
+ * `DaemonConfig.resultDocument` extractor produced a document that could not
+ * be delivered — over the cap, not JSON-serializable, or destined for a
+ * server that never advertised the `result-document` capability. All three
+ * are `retryable: false`: none of them can come out differently on a retry
+ * against the same server with the same extractor. Everything after the
+ * prefix is human-readable detail (including the measured size), not part of
+ * the stable shape.
+ *
+ * There is deliberately no "send it anyway" or "send it truncated" path.
+ * A document is the task's PRIMARY structured result, so quietly dropping or
+ * mangling it would report success while destroying the thing the task
+ * existed to produce.
+ */
+export declare const RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX = "result document undeliverable";
+/**
+ * The task identity handed to a {@link ResultDocumentExtractor} alongside the
+ * final output text. Deliberately minimal — identity only, no session
+ * handle, no workspace path, no adapter: this seam exists to turn text the
+ * runtime already produced into the product's own JSON, not to become a
+ * general-purpose end-of-task callback with access to the daemon's innards.
+ */
+export interface ResultDocumentTask {
+    readonly taskId: string;
+    readonly sessionRef: string;
+}
+/**
+ * Host-supplied glue that turns a finished task's final output into the
+ * product's structured terminal result (`task.complete.document`). Returning
+ * `undefined` means "this task has no structured result" and completes the
+ * task exactly as it would have without an extractor configured at all.
+ *
+ * SYNCHRONOUS by contract, like every other single-purpose callback on
+ * `TaskRunnerDeps`, and the runtime ENFORCES that rather than trusting it:
+ * the returned value is treated as data and JSON-encoded as-is, never
+ * awaited, so a returned promise would encode to an empty document (`{}`) —
+ * a well-formed, under-cap, and completely WRONG result. A thenable return
+ * is therefore rejected exactly like a throw (`task.fail`, `retryable:
+ * false`), because delivering a confidently wrong terminal result is worse
+ * than delivering none.
+ *
+ * Throwing is a real outcome, not a nuisance: it fails the task
+ * (`retryable: false`) rather than completing it without the result the
+ * extractor was supposed to produce — see {@link
+ * RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX}.
+ */
+export type ResultDocumentExtractor = (finalOutput: string, task: ResultDocumentTask) => unknown;
 /**
  * M5 batch-3 (workstream 2): default cap (64 MiB) on accumulated
  * (approximate) agent-event output bytes this daemon tolerates for a single
@@ -130,6 +180,8 @@ export interface TaskRunnerDeps {
     runtimeEnvironment?: Record<string, {
         allow?: string[];
     }>;
+    /** Validated, device-local registry keyed by wire-level logical toolset id. */
+    mcpToolsets?: ReadonlyMap<string, McpToolsetConfig>;
     permissionDefaults?: PermissionPolicy;
     workspaceRoot: string;
     deviceId: string;
@@ -240,8 +292,22 @@ export interface TaskRunnerDeps {
      */
     admissionGuard?: (offer: {
         readonly taskId: string;
-        readonly payload: TaskOfferPayload;
+        readonly payload: AcceptedOfferPayload;
     }) => AdmissionGuardDecision;
+    /**
+     * additive-minor (`task.complete.document`): the host's structured-result
+     * extractor, consulted once per task at the moment `task.complete` is
+     * built — see {@link ResultDocumentExtractor} and `DaemonConfig
+     * .resultDocument` (`create-daemon.ts`) for the full contract.
+     *
+     * Optional, and absent by default: with no extractor supplied, the
+     * completion path is byte-identical to what it was before this seam
+     * existed — no document is computed, no capability is consulted, and
+     * `task.complete` carries exactly the fields it always did.
+     */
+    resultDocument?: {
+        readonly extract: ResultDocumentExtractor;
+    };
 }
 /** See {@link TaskRunnerDeps.admissionGuard}. */
 export type AdmissionGuardDecision = {
@@ -251,6 +317,7 @@ export type AdmissionGuardDecision = {
     readonly reason: string;
     readonly retryable: boolean;
 };
+type AcceptedOfferPayload = TaskOfferPayload | TaskOfferWithToolsetsPayload;
 /**
  * Per-connection task orchestration: offer -> (decline | claim -> adapter
  * session -> started) -> seq-ordered progress batches -> complete/fail/
@@ -508,6 +575,8 @@ export declare class TaskRunner {
     private handleOffer;
     /** Protocol §7: an instruction too large to inline arrives as a `blobRef` — resolve it via the blob client rather than failing closed. */
     private resolveInstruction;
+    /** Resolve every requested logical id locally and reject missing/colliding server authority before claim. */
+    private resolveMcpServers;
     private pump;
     /**
      * Protocol §7: an `artifact` `AgentEvent` only names a file the runtime
@@ -824,6 +893,62 @@ export declare class TaskRunner {
     /** Pre-claim, fail-closed rejection (protocol §3.2) — never claims first. */
     private decline;
     private fail;
+    /**
+     * additive-minor (`task.complete.document`): the whole daemon-side gate
+     * between a configured {@link ResultDocumentExtractor} and the wire —
+     * called once, from the `turn_end` completion path, immediately before
+     * `task.complete` is built.
+     *
+     * `{deliver: true}` means "go on and send `task.complete`", carrying the
+     * document when there is one. `{deliver: false}` means this method has
+     * ALREADY reported `task.fail` and finished the task; the caller must
+     * return without sending anything further.
+     *
+     * Four fail-closed branches, all `retryable: false` (see
+     * {@link RESULT_DOCUMENT_UNDELIVERABLE_REASON_PREFIX} for why none of them
+     * can succeed on a retry):
+     *
+     *   1. The extractor threw — its error is surfaced, never swallowed.
+     *   2. The extractor returned a thenable, violating the synchronous
+     *      contract in the one way that would otherwise ship a wrong answer.
+     *   3. The document is over the cap, not JSON-serializable, or not plain
+     *      JSON data, per `checkResultDocument` — the protocol's OWN check,
+     *      imported rather than reimplemented, so this gate and the server's
+     *      schema validation can never disagree about what is legal.
+     *   4. The connected server never advertised `result-document`. Its
+     *      tolerant `z.object()` would silently strip the field on arrival
+     *      (`version.ts`'s own flag doc comment), so "send anyway" is not a
+     *      degraded-but-working path — it is the task's primary structured
+     *      result being deleted in transit with nothing reported anywhere.
+     *
+     * The capability is checked LAST, deliberately: a document that is itself
+     * invalid is the host's own bug and is worth reporting as such even when
+     * the connected server could not have accepted any document at all. It is
+     * then re-checked once more by the caller after its own last await, since
+     * a reconnect can invalidate this answer in between (F3).
+     *
+     * **Residual window (bounded, deliberately not hacked around).** Even the
+     * caller's re-check happens before `ConnectionManager.send` hands the
+     * envelope to a transport, and a queued envelope can outlive the
+     * connection it was queued for: a reconnect between `send()` and the
+     * outbox actually draining could still deliver this `task.complete` to a
+     * rolled-back N-1 server that strips the document. Closing that would
+     * mean teaching the transport outbox to inspect payload semantics and
+     * mint a substitute `task.fail` for a task this runner already finished —
+     * a second authority over terminal outcomes living in the queue, which is
+     * worse than the window it closes. Documented instead, here and in
+     * docs/protocol.md §7.2.
+     */
+    private resolveResultDocument;
+    /**
+     * Whether the CURRENTLY connected server advertised `result-document` —
+     * read fresh on every call, never captured, because the answer changes
+     * across a reconnect (`ConnectionManager.getServerCapabilities` returns
+     * `[]` from the moment an acked connection closes until a fresh
+     * `conn.ack` repopulates it). An absent `getServerCapabilities` seam is
+     * "no capabilities", the fail-closed reading.
+     */
+    private hasResultDocumentCapability;
     private observeGit;
     private updateGitPhaseBestEffort;
     private finish;
@@ -860,3 +985,4 @@ export declare class TaskRunner {
      */
     private pickAdapter;
 }
+export {};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { RuntimeAdapter, RuntimeCapabilities, RuntimeDetectResult, Session, TaskContext, GitWorkspaceConfig, } from './types';
+export type { RuntimeAdapter, RuntimeCapabilities, RuntimeDetectResult, Session, TaskContext, GitWorkspaceConfig, McpStdioServerConfig, McpToolsetConfig, } from './types';
 export { PolicyUnsupportedError, SteerUnsupportedError } from './types';
 export type { RuntimeEnvironmentRequirements } from './daemon/environment';
 export { GitWorkspaceManager, GitWorkspaceError, isGitWorkspaceConfig, prependGitWorkspaceGuidance } from './daemon/git-workspace';
@@ -6,7 +6,17 @@ export type { GitWorkspaceObservation, GitWorkspaceLease, GitWorkspaceOptions, G
 export { GitWorkspaceStore } from './daemon/git-workspace-store';
 export type { GitWorkspaceLedger, GitWorkspaceLedgerRecord, GitWorkspacePhase } from './daemon/git-workspace-store';
 export { createDaemon, createDaemonWithAdapters } from './daemon/create-daemon';
-export type { Daemon, DaemonConfig, DaemonStatus, DaemonOverrides, DaemonBranding, HostedJournalConfig } from './daemon/create-daemon';
+export type { Daemon, DaemonConfig, DaemonStatus, DaemonOverrides, DaemonBranding, HostedJournalConfig, DeviceAssertionConfig } from './daemon/create-daemon';
+/**
+ * Plan `device-assertion-broker`: the ONLY control-socket capability this
+ * package exposes publicly. `connectControlClient`/`ControlClient` are
+ * deliberately NOT exported and must never be — they also carry `shutdown`,
+ * approval resolution and the raw task-event stream, and exporting the client
+ * would make all of it public API in one line. See `daemon/assertion-client.ts`
+ * and the constraint test that pins this.
+ */
+export { requestDeviceAssertion } from './daemon/assertion-client';
+export type { RequestDeviceAssertionOptions, RequestDeviceAssertionResult, RequestDeviceAssertionErrorCode, } from './daemon/assertion-client';
 export type { OperationalHealthSnapshot, OperationalHealthState } from './daemon/operational-health';
 export { journalHash, JournalUnavailableError, JournalCorruptError, JournalRecordTooLargeError, JournalUnknownTaskError, JournalClosedError, } from './daemon/journal/journal';
 export type { LocalTaskJournal, JournalIdentity, JournalReceipt, ReceivedEnvelopeRecord, AdmissionRecord, LocalTransitionRecord, LocalTerminalRecord, TerminalTruthState, RecoverableTask, RecoveryOutcome, RecoveryDisposition, LocalStorageUsage, StorageCategory, CategoryUsage, CleanableCategory, CleanupCandidate, CleanupResult, CompactOptions, CompactResult, } from './daemon/journal/journal';
@@ -18,6 +28,15 @@ export type { DeviceRecord } from './daemon/store';
 export { AuthManager, DeviceRevokedError } from './daemon/auth-manager';
 export { StoredDeviceProofSigner } from './daemon/device-proof-signer';
 export type { DeviceProofRequest, DeviceProofSigner, StoredDeviceProofSignerOptions, } from './daemon/device-proof-signer';
+/**
+ * Plan `skill-pack-delivery-channel`: the device half of the `skills.pack`
+ * channel. The install pipeline and the two read APIs are public because the
+ * HOST, not this SDK, decides where a vendor CLI keeps its skills (K4) — a host
+ * lists what is installed and projects the pack it wants into the directory its
+ * own runtime reads. Nothing here ever writes to a vendor CLI's skill directory.
+ */
+export { SKILL_PACKS_CAPABILITY, SKILL_PACKS_DIRNAME, SKILL_PACK_AUDIT_FILENAME, SKILL_PACK_INSTALL_ERROR_CODES, SKILL_PACK_LOCK_FILENAME, SKILL_PACK_LOCK_SCHEMA, SKILL_PACK_RESPONSE_MAX_BYTES, SkillPackInstallError, installSkillPacks, listInstalledSkillPacks, projectSkillPack, skillPacksRoot, } from './daemon/skill-pack-installer';
+export type { InstallSkillPacksOptions, InstalledSkillPack, ProjectedSkillPack, SkillPackInstallErrorCode, SkillPackInstallResult, SkillPackLock, } from './daemon/skill-pack-installer';
 export { TruthMemoryClient, TruthMemoryClientError } from './daemon/truth-memory-client';
 export type { LocalMemoryFilter, MemorySelector, TruthManifestQueryInput, TruthManifestRecord, TruthMemoryClientErrorCode, TruthMemoryClientOptions, TruthMemoryMetric, TruthSnapshotCandidateInput, TruthSnapshotWriteInput, TruthTerminalWriteInput, TruthWriteBody, TruthWriteResult, VerifiedTruthRecord, } from './daemon/truth-memory-client';
 export type { ConnectionState } from './daemon/ws-transport';
@@ -35,7 +54,7 @@ export { generateWinswXml } from './lifecycle/winsw';
 export { ensureSecureDir, buildIcaclsArgs, SecureDirHardeningError } from './util/secure-dir';
 export type { EnsureSecureDirOptions } from './util/secure-dir';
 export { PiAdapter } from './adapters/pi/pi-adapter';
-export type { PiAdapterOptions } from './adapters/pi/pi-adapter';
+export type { PiAdapterOptions, PiByokLauncherConfig } from './adapters/pi/pi-adapter';
 export { PI_PACKAGE_NAME } from './adapters/pi/resolve-bin';
 export { ClaudeAdapter } from './adapters/claude/claude-adapter';
 export type { ClaudeAdapterOptions } from './adapters/claude/claude-adapter';