@byok-sdk/client 0.8.0-beta.0 → 0.8.1

package/README.md

@@ -108,6 +108,14 @@ createDaemon({
 });
 ```
 
+For task-free desired-state projection, use
+`createAgentHomeProjectionConsumer`. Its hook must atomically and idempotently
+ensure its opaque product bytes. BYOK may invoke it again under the same
+canonical-home writer lease when a new request carries the exact current
+revision/hash; the terminal outcome remains `idempotent`. This permits repair
+of locally lost derived files without giving the SDK product path or schema
+knowledge. Stale and same-revision/different-hash requests do not invoke it.
+
 Startup materializes and write-probes the canonical root before publishing
 `agent-home-contract`. `agentHome` and `gitWorkspace` are mutually exclusive;
 strict Agent execution has one workspace authority and never falls back to a
@@ -131,6 +139,13 @@ keeps runtime activity metadata/status-only; enabling it is an explicit product
 decision and requires the server capability. Reliable events are fsynced under
 the canonical Agent home and retire only after an exact ack.
 
+Hosts that need cold setup or diagnostic state use
+`readDeviceEnrollmentStatus({ productId, storeDir })`. It validates the
+complete SDK-owned record but returns only `unpaired`, `paired` with
+`deviceId`, or `re_pair_required`; tenant, token, expiry and device keys are
+never projected. Only explicit pairing may replace `re_pair_required` state,
+while filesystem-safety failures remain errors.
+
 ```ts
 createDaemon({
   // ...normal device, transport and agentHome configuration

package/dist/agent-home.d.ts

@@ -1,7 +1,8 @@
-import { type AgentRef } from '@byok-sdk/protocol';
+import { type AgentHomeProjectionOutcome, type AgentHomeProjectionPayload, type AgentRef } from '@byok-sdk/protocol';
 export type { AgentRef } from '@byok-sdk/protocol';
 export declare const AGENT_HOME_DIRECTORY = "agents";
 export declare const AGENT_HOME_INTERNAL_DIRECTORY = ".byok";
+export declare const AGENT_HOME_PROJECTION_STATE_FILE = "agent-home-projection.json";
 export declare class AgentHomeError extends Error {
     constructor(message: string);
 }
@@ -34,15 +35,28 @@ export interface AgentHomeResolution {
 export interface AgentHomeProjectionInput extends AgentHomeResolution {
     readonly cwd: string;
 }
+export interface AgentHomeProjectionApplyInput extends AgentHomeProjectionInput {
+    readonly requestId: string;
+    readonly projectionHash: string;
+    readonly projection: unknown;
+}
 /**
  * Optional downstream projection hook. The SDK supplies the canonical home;
  * the host supplies opaque, redacted product content and never joins
  * `agents/<agentId>` itself. The SDK does not parse the projected content.
  */
 export interface AgentHomeProjection {
-    prepare(input: AgentHomeProjectionInput): void | Promise<void>;
+    /** Optional creation/task-time host preparation retained as a distinct lifecycle. */
+    prepare?(input: AgentHomeProjectionInput): void | Promise<void>;
+    /**
+     * Task-free opaque desired-state consumer. It must atomically and
+     * idempotently ensure its own durable bytes because exact revision/hash
+     * requests may replay after local derived-file loss or transport failure.
+     */
+    apply?(input: AgentHomeProjectionApplyInput): void | Promise<void>;
 }
 export type AgentHomeProjectionFunction = (input: AgentHomeProjectionInput) => void | Promise<void>;
+export type AgentHomeProjectionApplyFunction = (input: AgentHomeProjectionApplyInput) => void | Promise<void>;
 export interface AgentHomeLease {
     readonly leaseId: string;
     readonly agentRef: AgentRef;
@@ -72,7 +86,15 @@ export declare class AgentHomeLayout {
      * file is created by this preflight.
      */
     preflight(): Promise<void>;
+    /**
+     * Construction-time validation is deliberately non-mutating. The actual
+     * writable preflight runs asynchronously after daemon ownership is acquired
+     * and before transport/capability publication, where it can participate in
+     * the cross-process relocation gate without a sync shadow lock.
+     */
+    preflightSync(): void;
     private resolveRoot;
+    private acquireRootMutationGate;
 }
 export declare function stableAgentHomeOwnerId(storeDir: string, productId: string): string;
 /** One-writer lease backed by both a process registry and an exclusive marker. */
@@ -98,9 +120,26 @@ export declare class AgentHomeManager {
     prepare(agentRef: AgentRef): Promise<AgentHomeBinding>;
     /** Validate the configured root before capability publication. */
     preflight(): Promise<void>;
+    /** Synchronous construction-time preflight for strict Agent-only admission. */
+    preflightSync(): void;
     /** Resolve and lease without applying downstream projection side effects. */
     acquire(agentRef: AgentRef): Promise<AgentHomeBinding>;
     /** Initialize only after any requested session exact-match has succeeded. */
     initialize(binding: AgentHomeBinding): Promise<void>;
+    supportsTaskFreeProjection(): boolean;
+    /**
+     * Apply one task-free projection under the same canonical-home writer lease
+     * used by Agent execution. The host hook owns an atomic/idempotent ensure of
+     * its opaque product bytes, so an exact desired-state replay invokes it again
+     * before returning `idempotent`. Only a successful new-state hook followed
+     * by the SDK-owned fsynced ordering record can return `applied`.
+     */
+    project(input: AgentHomeProjectionPayload): Promise<AgentHomeProjectionOutcome>;
 }
 export declare function createAgentHomeProjection(prepare: AgentHomeProjectionFunction): AgentHomeProjection;
+/**
+ * Create the task-free atomic/idempotent opaque desired-state consumer.
+ * Exact revision/hash delivery may invoke it again before an idempotent receipt;
+ * no task-time fallback is inferred.
+ */
+export declare function createAgentHomeProjectionConsumer(apply: AgentHomeProjectionApplyFunction): AgentHomeProjection;