@byok-sdk/cloud-dataplane 0.6.0 → 0.6.1

package/dist/sql/0012_agent_home_contract.sql

@@ -0,0 +1,41 @@
+-- 0012_agent_home_contract.sql — durable Agent capability and attempt identity.
+--
+-- Additive only. Existing legacy device/task rows remain valid with NULL
+-- Agent fields and therefore cannot accidentally acquire Agent semantics.
+-- The hosted gate treats a NULL capability snapshot as unknown and refuses an
+-- Agent offer before either a mailbox row or a task attempt is created.
+
+ALTER TABLE device
+  ADD COLUMN capabilities jsonb;
+
+ALTER TABLE device
+  ADD CONSTRAINT device_capabilities_shape
+  CHECK (capabilities IS NULL OR jsonb_typeof(capabilities) = 'array');
+
+ALTER TABLE task
+  ADD COLUMN agent_id text,
+  ADD COLUMN agent_profile_revision text,
+  ADD COLUMN terminal_cause text;
+
+ALTER TABLE task
+  ADD CONSTRAINT task_agent_ref_pair
+  CHECK ((agent_id IS NULL) = (agent_profile_revision IS NULL));
+
+ALTER TABLE task
+  ADD CONSTRAINT task_agent_ref_bounded
+  CHECK (
+    agent_id IS NULL
+    OR (
+      octet_length(agent_id) BETWEEN 1 AND 160
+      AND octet_length(agent_profile_revision) BETWEEN 1 AND 160
+      AND position('/' IN agent_id) = 0
+      AND position(E'\\' IN agent_id) = 0
+      AND position(':' IN agent_id) = 0
+      AND agent_id !~ '[<>"|?*]'
+      AND agent_id NOT IN ('.', '..')
+      AND agent_id !~ '[. ]$'
+      AND lower(split_part(agent_id, '.', 1)) !~ '^(con|prn|aux|nul|com[1-9]|lpt[1-9])$'
+      AND agent_id !~ '[[:cntrl:]]'
+      AND agent_profile_revision !~ '[[:cntrl:]]'
+    )
+  );

package/dist/sql/0013_agent_egress_contract.sql

@@ -0,0 +1,47 @@
+-- 0013_agent_egress_contract.sql — first-write-wins reliable Agent egress facts.
+--
+-- The typed policy never authorizes raw workspace/transcript/artifact bytes to
+-- this table. `payload_json` is the daemon's sanitized JSON projection; exact
+-- AgentRef, session, cursor, content hash, and cloud receipt identity remain
+-- independently addressable so a readback never has to reinterpret an opaque
+-- envelope body.
+
+CREATE TABLE agent_egress_event (
+  tenant_id              text        NOT NULL,
+  device_id              text        NOT NULL,
+  event_id               uuid        NOT NULL,
+  agent_id               text        NOT NULL,
+  agent_profile_revision text        NOT NULL,
+  session_ref            text        NOT NULL,
+  policy_revision        text        NOT NULL,
+  cursor                 bigint      NOT NULL,
+  payload_json           jsonb       NOT NULL,
+  content_hash           text        NOT NULL,
+  byte_count             integer     NOT NULL,
+  receipt_id             uuid        NOT NULL,
+  recorded_at            timestamptz NOT NULL,
+  PRIMARY KEY (tenant_id, device_id, event_id),
+  CONSTRAINT agent_egress_event_cursor_positive CHECK (cursor > 0 AND cursor <= 2147483647),
+  CONSTRAINT agent_egress_event_byte_count CHECK (byte_count >= 0 AND byte_count <= 262144),
+  CONSTRAINT agent_egress_event_hash_shape CHECK (content_hash ~ '^sha256:[a-f0-9]{64}$'),
+  CONSTRAINT agent_egress_event_agent_ref_bounded CHECK (
+    octet_length(agent_id) BETWEEN 1 AND 160
+    AND octet_length(agent_profile_revision) BETWEEN 1 AND 160
+    AND agent_id !~ '[[:cntrl:]]'
+    AND agent_profile_revision !~ '[[:cntrl:]]'
+  ),
+  CONSTRAINT agent_egress_event_session_bounded CHECK (
+    octet_length(session_ref) BETWEEN 1 AND 512
+    AND session_ref !~ '[[:cntrl:]]'
+  ),
+  CONSTRAINT agent_egress_event_policy_bounded CHECK (
+    octet_length(policy_revision) BETWEEN 1 AND 160
+    AND policy_revision !~ '[[:cntrl:]]'
+  )
+);
+
+-- Readback and operational inspection preserve the same tenant/device/session
+-- partition as the wire cursor. This is intentionally not unique: event id is
+-- the reliable idempotency authority, and cursor is an exact observation.
+CREATE INDEX agent_egress_event_cursor_idx
+  ON agent_egress_event (tenant_id, device_id, agent_id, agent_profile_revision, session_ref, cursor);

package/dist/stores/agent-egress.d.ts

@@ -0,0 +1,14 @@
+import type { AgentEgressRecord, AgentEgressStore } from '@byok-sdk/cloud';
+import type { Clock, TenantId } from '@byok-sdk/core';
+import type { Pool } from 'pg';
+/** Postgres implementation of the immutable reliable Agent egress receipt fact. */
+export declare class PostgresAgentEgressStore implements AgentEgressStore {
+    private readonly pool;
+    private readonly clock;
+    constructor(pool: Pool, clock: Clock);
+    record(tenant: TenantId, input: Omit<AgentEgressRecord, 'tenantId' | 'recordedAt'>): Promise<{
+        readonly record: AgentEgressRecord;
+        readonly created: boolean;
+    }>;
+    get(tenant: TenantId, deviceId: string, eventId: string): Promise<AgentEgressRecord | undefined>;
+}

package/dist/stores/devices.d.ts

@@ -18,6 +18,10 @@ export declare class PostgresDeviceDirectory implements DeviceDirectory {
     register(tenant: TenantId, input: DeviceRegistration): Promise<DeviceRecord>;
     get(tenant: TenantId, deviceId: string): Promise<DeviceRecord | undefined>;
     revoke(tenant: TenantId, deviceId: string): Promise<void>;
+    recordCapabilities(tenant: TenantId, input: {
+        readonly deviceId: string;
+        readonly capabilities: readonly string[];
+    }): Promise<DeviceRecord | undefined>;
     list(tenant: TenantId): Promise<readonly DeviceRecord[]>;
     readiness(tenant: TenantId, _presence: PresenceStore): Promise<TenantReadiness>;
     resolveByDeviceId(deviceId: string): Promise<DeviceRecord | undefined>;

package/dist/stores/index.d.ts

@@ -34,11 +34,12 @@ export { PostgresTaskAttemptStore } from './task-attempts';
 export { PostgresTaskCancellationStore } from './task-cancellations';
 export { PostgresActivityStore } from './activity';
 export { PostgresApprovalTimelineStore } from './approval-timeline';
+export { PostgresAgentEgressStore } from './agent-egress';
 export { PostgresDeviceAssertionReplayAuthority } from './device-assertion-replay';
 export { DEFAULT_MAX_ATTEMPTS, DEFAULT_PRESIGN_TTL_SECONDS, DEFAULT_RETRY_DELAY_MS, MAX_PRESIGN_TTL_SECONDS, MIN_PRESIGN_TTL_SECONDS, ObjectStoreRequestError, R2_BLOB_ERROR_CODES, R2BlobStoreError, R2CloudBlobStore, R2ObjectMaintenanceStore, } from './r2-blobs';
 export type { ObjectStoreFetch, R2BlobErrorCode, R2BlobStoreOptions } from './r2-blobs';
 export type { R2DeleteResult, R2ListedObject, R2ObjectMaintenance, R2ObjectMaintenanceOptions, R2ObjectPage, } from './r2-blobs';
-/** Every cloud-local port. All eleven, or it is not a composition. */
+/** Every cloud-local port. All twelve, or it is not a composition. */
 export type PostgresCloudStores = CloudStores;
 /** Everything the blob store needs that is not already a composition-wide input. */
 export type PostgresObjectStorageOptions = Omit<R2BlobStoreOptions, 'objects'>;

package/dist/stores/task-attempts.d.ts

@@ -14,21 +14,24 @@
  * `claim` and `recordStatus` on a task this tenant never offered write nothing
  * and return `undefined`.
  */
-import type { TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '@byok-sdk/cloud';
+import type { AgentRef, TaskAttempt, TaskAttemptStatus, TaskAttemptStore } from '@byok-sdk/cloud';
 import type { Clock, TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
 export interface TaskRow {
     readonly tenant_id: string;
     readonly task_id: string;
     readonly device_id: string;
+    readonly agent_id: string | null;
+    readonly agent_profile_revision: string | null;
     readonly owner_device_id: string | null;
     readonly status: string;
+    readonly terminal_cause: string | null;
     readonly cancel_requested_at: Date | null;
     readonly cancel_reason: string | null;
     readonly cancel_message_id: string | null;
     readonly updated_at: Date;
 }
-export declare const TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, owner_device_id, status, cancel_requested_at, cancel_reason, cancel_message_id, updated_at";
+export declare const TASK_SELECT_COLUMNS = "tenant_id, task_id, device_id, agent_id, agent_profile_revision, owner_device_id, status, terminal_cause, cancel_requested_at, cancel_reason, cancel_message_id, updated_at";
 export declare function taskRowToAttempt(row: TaskRow): TaskAttempt;
 export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
     #private;
@@ -36,7 +39,16 @@ export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
     open(tenant: TenantId, input: {
         readonly taskId: string;
         readonly deviceId: string;
+        readonly agentRef?: AgentRef;
     }): Promise<TaskAttempt>;
+    reserveAgentOffer(tenant: TenantId, input: {
+        readonly taskId: string;
+        readonly deviceId: string;
+        readonly agentRef: AgentRef;
+    }): Promise<{
+        readonly attempt: TaskAttempt;
+        readonly created: boolean;
+    }>;
     get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
     getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
     claim(tenant: TenantId, input: {
@@ -46,5 +58,7 @@ export declare class PostgresTaskAttemptStore implements TaskAttemptStore {
     recordStatus(tenant: TenantId, input: {
         readonly taskId: string;
         readonly status: TaskAttemptStatus;
+        readonly agentRef?: AgentRef;
+        readonly terminalCause?: string;
     }): Promise<TaskAttempt | undefined>;
 }

package/dist/tenant-erasure.d.ts

@@ -1,8 +1,8 @@
 import { type Clock, type TenantId } from '@byok-sdk/core';
 import type { Pool } from 'pg';
 import { type R2BlobStoreOptions, type R2ObjectMaintenance } from './stores/r2-blobs';
-/** Every tenant-owned table as of 0010, in child-before-parent deletion order. */
-export declare const TENANT_ERASURE_TABLES: readonly ['object_reference', 'object_manifest', 'storage_reservation', 'storage_usage', 'storage_entitlement', 'gc_cursor', 'cleanup_job', 'tenant_retention_policy', 'skill_pack_file', 'skill_pack', 'approval_timeline_tail', 'activity_tail', 'attested_record', 'board_item', 'tenant_stream', 'outbox', 'device_request_receipts', 'proof_request_receipt', 'task', 'device_presence', 'device_assertion_replay', 'device_stream', 'inbound_dedup', 'auth_nonce', 'pairing_code', 'device'];
+/** Every tenant-owned table as of 0013, in child-before-parent deletion order. */
+export declare const TENANT_ERASURE_TABLES: readonly ['object_reference', 'object_manifest', 'storage_reservation', 'storage_usage', 'storage_entitlement', 'gc_cursor', 'cleanup_job', 'tenant_retention_policy', 'skill_pack_file', 'skill_pack', 'approval_timeline_tail', 'activity_tail', 'attested_record', 'board_item', 'tenant_stream', 'outbox', 'agent_egress_event', 'device_request_receipts', 'proof_request_receipt', 'task', 'device_presence', 'device_assertion_replay', 'device_stream', 'inbound_dedup', 'auth_nonce', 'pairing_code', 'device'];
 export declare const TENANT_ERASURE_ERROR_CODES: {
     readonly tenant_erasure_invalid_input: 'tenant_erasure_invalid_input';
     readonly tenant_erasure_schema_drift: 'tenant_erasure_schema_drift';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/cloud-dataplane",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "BYOK SDK hosted data plane: canonical Postgres + R2 stores, migrations, truth transactions, and maintenance",
   "type": "module",
   "license": "MIT",
@@ -49,9 +49,9 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@byok-sdk/cloud": "0.6.0",
-    "@byok-sdk/core": "0.6.0",
-    "@byok-sdk/protocol": "0.6.0",
+    "@byok-sdk/cloud": "0.6.1",
+    "@byok-sdk/core": "0.6.1",
+    "@byok-sdk/protocol": "0.6.1",
     "aws4fetch": "1.0.20",
     "fast-xml-parser": "^5.10.1",
     "pg": "^8.22.0"