acn-client 0.13.0 → 0.14.0

package/dist/index.d.ts

@@ -115,17 +115,17 @@ interface AgentSearchOptions {
     skills?: string;
     /** online (default) | offline | all. Public list does not include verification_code. */
     status?: AgentSearchStatus;
-    subnet_id?: string;
+    slug?: string;
 }
 /** Subnet information */
 interface SubnetInfo {
     /**
-     * Subnet identifier. The server wire field is `subnet_id`; some
-     * older responses may also surface `id`. Prefer `subnet_id` when
-     * present, falling back to `id`.
+     * Opaque UUID identifier from the persistence layer.
      */
     id: string;
-    /** Wire-side identifier (ADR-0003+ servers always emit this). */
+    /** URL-safe slug identifier (server wire field). */
+    slug?: string;
+    /** @deprecated Use `slug` instead. */
     subnet_id?: string;
     name: string;
     description?: string;
@@ -135,8 +135,16 @@ interface SubnetInfo {
     owner?: string;
     harness_url?: string;
     harness_registered?: boolean;
-    /** ADR-0003 — parent subnet when this is a nested child. */
+    /**
+     * Deprecated — ACL V6 B6: the server no longer emits the slug.
+     * Use `parent_id` (UUID) instead.  Kept for backward-compat parsing
+     * of responses from older server versions.
+     */
+    parent_slug?: string | null;
+    /** @deprecated Use `parent_slug` instead. */
     parent_subnet_id?: string | null;
+    /** ACL V6 B6 — parent subnet's opaque UUID. */
+    parent_id?: string | null;
     /** ADR-0003 — defaults to `'persistent'` on the server. */
     lifecycle?: SubnetLifecycle;
     /** ADR-0003 — bound task when `lifecycle === 'task_scoped'`. */
@@ -162,10 +170,10 @@ interface SubnetCreateRequest {
     metadata?: Record<string, unknown>;
     /**
      * ADR-0003 nested-subnet parent. When set, the new subnet becomes a
-     * child of `parent_subnet_id`. Single-layer cap: the parent itself
+     * child of `parent_slug`. Single-layer cap: the parent itself
      * must be top-level. Immutable after creation.
      */
-    parent_subnet_id?: string;
+    parent_slug?: string;
     /**
      * ADR-0003 lifecycle. Defaults to `'persistent'` when omitted.
      * `'task_scoped'` requires `linked_task_id` and the subnet
@@ -190,7 +198,7 @@ interface SubnetCreateRequest {
 /** Subnet creation response */
 interface SubnetCreateResponse {
     success: boolean;
-    subnet_id: string;
+    slug: string;
     message: string;
 }
 /** Subnet join-policy values. Immutable post-creation. */
@@ -204,7 +212,7 @@ interface SubnetAllowlistEntry {
 }
 /** Response envelope for `subnetAllowlistList` (owner only). */
 interface SubnetAllowlistListResponse {
-    subnet_id: string;
+    slug: string;
     entries: SubnetAllowlistEntry[];
     [key: string]: unknown;
 }
@@ -218,7 +226,7 @@ interface SubnetAllowlistListResponse {
  */
 interface SubnetJoinRequestRow {
     request_id: string;
-    subnet_id: string;
+    slug: string;
     kind: 'join_request' | 'allowlist_auto' | 'invitation';
     status: 'pending' | 'approved' | 'rejected' | 'withdrawn';
     initiated_by: string;
@@ -231,13 +239,13 @@ interface SubnetJoinRequestRow {
 }
 /** Response envelope for `subnetJoinRequestList` (owner only). */
 interface SubnetJoinRequestListResponse {
-    subnet_id: string;
+    slug: string;
     items: SubnetJoinRequestRow[];
     [key: string]: unknown;
 }
 /** Response envelope for `subnetInvitationList` (owner only). */
 interface SubnetInvitationListResponse {
-    subnet_id: string;
+    slug: string;
     items: SubnetJoinRequestRow[];
     [key: string]: unknown;
 }
@@ -552,7 +560,7 @@ interface Task {
     required_tags?: string[];
     /** Reward in numeric form — convenience alias, equals `parseFloat(reward)`. */
     reward_amount?: number;
-    subnet_id: string | null;
+    subnet_slug: string | null;
     created_at: string;
     deadline?: string | null;
     use_escrow?: boolean;
@@ -588,7 +596,7 @@ interface TaskCreateRequest {
     reward: string;
     /** Deadline in hours (1–2 160). Required. */
     deadline_hours: number;
-    subnet_id?: string | null;
+    subnet_slug?: string | null;
     /** Default: "credits" */
     reward_currency?: string;
     /** Default: 1 */
@@ -856,6 +864,7 @@ interface AllowlistListResponse {
     entries: AllowlistEntry[];
     total: number;
 }
+declare const KNOWN_INBOX_MESSAGE_STATUSES: readonly ["unread", "read", "processed"];
 
 /**
  * ACN HTTP Client
@@ -887,6 +896,7 @@ declare class ACNClient {
     private request;
     private get;
     private post;
+    private patch;
     private delete;
     /** Check if ACN server is healthy */
     health(): Promise<{
@@ -988,37 +998,37 @@ declare class ACNClient {
         subnets: SubnetInfo[];
     }>;
     /** Get subnet by ID */
-    getSubnet(subnetId: string): Promise<SubnetInfo>;
+    getSubnet(slug: string): Promise<SubnetInfo>;
     /**
      * List immediate children of a subnet (ADR-0003).
      *
-     * Wraps `GET /api/v1/subnets/{parentSubnetId}/children`. Returns
+     * Wraps `GET /api/v1/subnets/{parentSlug}/children`. Returns
      * `SUBNET_NOT_FOUND` when the parent does not exist. Visibility
      * matches `listSubnets` — private children you cannot see are
      * omitted from the result set.
      */
-    listChildren(parentSubnetId: string): Promise<SubnetInfo[]>;
+    listChildren(parentSlug: string): Promise<SubnetInfo[]>;
     /**
      * Promote a `task_scoped` subnet to `persistent` (ADR-0003).
      *
      * Owner-only. Idempotent — promoting an already-persistent subnet
      * returns its current state unchanged.
      */
-    promoteSubnet(subnetId: string): Promise<SubnetInfo>;
+    promoteSubnet(slug: string): Promise<SubnetInfo>;
     /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
-    deleteSubnet(subnetId: string): Promise<{
+    deleteSubnet(slug: string): Promise<{
         success: boolean;
     }>;
     /** Get agents in a subnet */
-    getSubnetAgents(subnetId: string): Promise<{
+    getSubnetAgents(slug: string): Promise<{
         agents: AgentInfo[];
     }>;
     /** Join agent to subnet */
-    joinSubnet(agentId: string, subnetId: string): Promise<{
+    joinSubnet(agentId: string, slug: string): Promise<{
         success: boolean;
     }>;
     /** Remove agent from subnet */
-    leaveSubnet(agentId: string, subnetId: string): Promise<{
+    leaveSubnet(agentId: string, slug: string): Promise<{
         success: boolean;
     }>;
     /** Get agent's subnets */
@@ -1026,7 +1036,7 @@ declare class ACNClient {
         subnets: string[];
     }>;
     /**
-     * Pre-authorise `agentId` on `subnetId`'s allowlist (owner only).
+     * Pre-authorise `agentId` on `slug`'s allowlist (owner only).
      *
      * Allowlisted agents skip the approval queue: their next
      * `joinSubnet` lands in branch 4 (allowlist hit) and becomes an
@@ -1036,24 +1046,24 @@ declare class ACNClient {
      * return 409 ALREADY_ON_ALLOWLIST (raised as an error, never
      * silently no-op'd).
      */
-    subnetAllowlistAdd(subnetId: string, agentId: string): Promise<SubnetAllowlistEntry>;
+    subnetAllowlistAdd(slug: string, agentId: string): Promise<SubnetAllowlistEntry>;
     /**
-     * Remove `agentId` from `subnetId`'s allowlist (owner only).
+     * Remove `agentId` from `slug`'s allowlist (owner only).
      *
      * Idempotent — removing an entry that doesn't exist still
      * returns 204. Per ADR-0004 §"Allowlist mutation does not
      * affect agents who already joined", this does NOT revoke
      * membership for agents already admitted via the allowlist.
      */
-    subnetAllowlistRemove(subnetId: string, agentId: string): Promise<void>;
+    subnetAllowlistRemove(slug: string, agentId: string): Promise<void>;
     /**
-     * List `subnetId`'s allowlist entries (owner only).
+     * List `slug`'s allowlist entries (owner only).
      *
      * Owner-only by design — the allowlist is a privacy-sensitive
      * trust signal and exposing it publicly would leak relationship
      * metadata.
      */
-    subnetAllowlistList(subnetId: string, options?: {
+    subnetAllowlistList(slug: string, options?: {
         limit?: number;
         offset?: number;
     }): Promise<SubnetAllowlistListResponse>;
@@ -1068,7 +1078,7 @@ declare class ACNClient {
      *
      * Optional `note` (≤500 chars) is recorded on the audit row.
      */
-    subnetJoinRequestApprove(subnetId: string, requestId: string, options?: {
+    subnetJoinRequestApprove(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1076,7 +1086,7 @@ declare class ACNClient {
      *
      * No membership change. `subnet.join_rejected` webhook fires.
      */
-    subnetJoinRequestReject(subnetId: string, requestId: string, options?: {
+    subnetJoinRequestReject(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1085,18 +1095,18 @@ declare class ACNClient {
      * Self-only — caller must be the agent who originally created
      * the request. `subnet.join_withdrawn` webhook fires.
      */
-    subnetJoinRequestWithdraw(subnetId: string, requestId: string, options?: {
+    subnetJoinRequestWithdraw(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
-     * Owner lists join_request / allowlist_auto rows for `subnetId`.
+     * Owner lists join_request / allowlist_auto rows for `slug`.
      *
      * `kind` defaults to `'join_request'`; pass `'allowlist_auto'`
      * to inspect synthesised allowlist-hit audit rows. Server
      * rejects `kind='invitation'` with 400 INVALID_KIND_FILTER —
      * use `subnetInvitationList` instead.
      */
-    subnetJoinRequestList(subnetId: string, options?: SubnetJoinRequestListOptions): Promise<SubnetJoinRequestListResponse>;
+    subnetJoinRequestList(slug: string, options?: SubnetJoinRequestListOptions): Promise<SubnetJoinRequestListResponse>;
     /**
      * Owner sends an invitation to `agentId` (or merges into a
      * pending join_request from the same target).
@@ -1109,7 +1119,7 @@ declare class ACNClient {
      *
      * Discriminate on `auto_resolved` to dispatch.
      */
-    subnetInvitationSend(subnetId: string, agentId: string, options?: {
+    subnetInvitationSend(slug: string, agentId: string, options?: {
         note?: string;
     }): Promise<SubnetInvitationSendResponse>;
     /**
@@ -1120,7 +1130,7 @@ declare class ACNClient {
      * gains the back-reference, and `subnet.invitation_accepted`
      * webhook fires.
      */
-    subnetInvitationAccept(subnetId: string, requestId: string, options?: {
+    subnetInvitationAccept(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1129,7 +1139,7 @@ declare class ACNClient {
      * No membership change. `subnet.invitation_rejected` webhook
      * fires.
      */
-    subnetInvitationReject(subnetId: string, requestId: string, options?: {
+    subnetInvitationReject(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
@@ -1139,16 +1149,16 @@ declare class ACNClient {
      * `withdrawn` (not `rejected`) — distinct audit token so
      * consumers can tell "owner gave up" from "invitee said no".
      */
-    subnetInvitationCancel(subnetId: string, requestId: string, options?: {
+    subnetInvitationCancel(slug: string, requestId: string, options?: {
         note?: string;
     }): Promise<SubnetJoinRequestRow>;
     /**
-     * Owner lists invitation rows for `subnetId`.
+     * Owner lists invitation rows for `slug`.
      *
      * Owner-only — invitees use `agentSubnetInvitations` for their
      * own cross-subnet view.
      */
-    subnetInvitationList(subnetId: string, options?: SubnetInvitationListOptions): Promise<SubnetInvitationListResponse>;
+    subnetInvitationList(slug: string, options?: SubnetInvitationListOptions): Promise<SubnetInvitationListResponse>;
     /**
      * Invitee's cross-subnet pending-invitation list (self only).
      *
@@ -1220,6 +1230,33 @@ declare class ACNClient {
     }): Promise<{
         messages: Message[];
     }>;
+    /**
+     * Precisely acknowledge (remove) specific messages from the inbox.
+     *
+     * Unlike `getMessageHistory({ consume: true })` which clears the entire inbox,
+     * this method removes only the messages whose `route_id` values are listed.
+     *
+     * @param agentId   Must match the authenticated agent's ID.
+     * @param routeIds  List of `route_id` values to remove (up to 500).
+     * @returns         Number of messages actually removed.
+     */
+    ackInbox(agentId: string, routeIds: string[]): Promise<{
+        acked: number;
+    }>;
+    /**
+     * Update the lifecycle status of a specific inbox message.
+     *
+     * @param agentId  Must match the authenticated agent's ID.
+     * @param routeId  `route_id` of the target message (from inbox listing).
+     * @param status   New status: `"unread"` | `"read"` | `"processed"`.
+     * @returns        Object with `agent_id`, `route_id`, and `status`.
+     * @throws         404 (`inbox_message_not_found`) if route_id is absent from inbox.
+     */
+    updateInboxMessageStatus(agentId: string, routeId: string, status: string): Promise<{
+        agent_id: string;
+        route_id: string;
+        status: string;
+    }>;
     /**
      * List manifest queue entries for the authenticated agent.
      *
@@ -1599,7 +1636,7 @@ declare class ACNClient {
      * Register (or clear) an org-harness webhook URL for a subnet.
      * Pass `harnessUrl: null` to deregister.
      */
-    registerSubnetHarness(subnetId: string, harnessUrl: string | null, harnessSecret?: string | null): Promise<void>;
+    registerSubnetHarness(slug: string, harnessUrl: string | null, harnessSecret?: string | null): Promise<void>;
 }
 /**
  * ACN API Error
@@ -1715,4 +1752,4 @@ declare class ACNRealtime {
  */
 declare function subscribeToACN<T = unknown>(baseUrl: string, channel: string, handler: WSEventHandler<T>): () => void;
 
-export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentSearchStatus, type AgentStatus, type AgentSubnetInvitationsResponse, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type CommunicationProfile, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type ManifestMessageType, type ManifestSendRequest, type Message, type MessageType, type MetricsData, type Participation, type ParticipationListResponse, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type PendingSessionsResponse, type SendMessageRequest, type SendMessageResponse, type SessionEntry, type SessionInviteRequest, type SessionStatus, type SubnetAllowlistEntry, type SubnetAllowlistListResponse, type SubnetChildrenListResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetHarnessRequest, type SubnetInfo, type SubnetInvitationListOptions, type SubnetInvitationListResponse, type SubnetInvitationSendResponse, type SubnetJoinPolicy, type SubnetJoinRequestListOptions, type SubnetJoinRequestListResponse, type SubnetJoinRequestRow, type SubnetLifecycle, type SystemHealth, type Task, type TaskAcceptResponse, type TaskCreateRequest, type TaskListOptions, type TaskListResponse, type TaskStatus, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };
+export { ACNClient, type ACNClientOptions, ACNError, ACNRealtime, type ActivityEntry, type AgentActivity, type AgentAnalytics, type AgentInfo, type AgentJoinRequest, type AgentJoinResponse, type AgentRegisterRequest, type AgentRegisterResponse, type AgentSearchOptions, type AgentSearchResponse, type AgentSearchStatus, type AgentStatus, type AgentSubnetInvitationsResponse, type AllowlistActionResponse, type AllowlistEntry, type AllowlistListResponse, type ApiResponse, type AttentionFee, type AuditEvent, type AuditQueryOptions, type BroadcastBySkillRequest, type BroadcastByTagRequest, type BroadcastRequest, type BroadcastStrategy, type CommunicationPolicyMode, type CommunicationPolicyResponse, type CommunicationProfile, type ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_INBOX_MESSAGE_STATUSES, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, type ManifestMessageType, type ManifestSendRequest, type Message, type MessageType, type MetricsData, type Participation, type ParticipationListResponse, type PaymentCapability, type PaymentDiscoveryOptions, type PaymentMethod, type PaymentNetwork, type PaymentRoleStats, type PaymentStats, type PaymentTask, type PaymentTaskStatus, type PendingSessionsResponse, type SendMessageRequest, type SendMessageResponse, type SessionEntry, type SessionInviteRequest, type SessionStatus, type SubnetAllowlistEntry, type SubnetAllowlistListResponse, type SubnetChildrenListResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetHarnessRequest, type SubnetInfo, type SubnetInvitationListOptions, type SubnetInvitationListResponse, type SubnetInvitationSendResponse, type SubnetJoinPolicy, type SubnetJoinRequestListOptions, type SubnetJoinRequestListResponse, type SubnetJoinRequestRow, type SubnetLifecycle, type SystemHealth, type Task, type TaskAcceptResponse, type TaskCreateRequest, type TaskListOptions, type TaskListResponse, type TaskStatus, type WSConnectionOptions, type WSEventHandler, type WSEventType, type WSMessage, type WSState, subscribeToACN };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   ACNClient: () => ACNClient,
   ACNError: () => ACNError,
   ACNRealtime: () => ACNRealtime,
+  KNOWN_INBOX_MESSAGE_STATUSES: () => KNOWN_INBOX_MESSAGE_STATUSES,
   KNOWN_PAYMENT_TASK_STATUSES: () => KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN: () => subscribeToACN
 });
@@ -123,6 +124,9 @@ var ACNClient = class {
   post(path, body) {
     return this.request("POST", path, { body });
   }
+  patch(path, body) {
+    return this.request("PATCH", path, { body });
+  }
   delete(path) {
     return this.request("DELETE", path);
   }
@@ -239,20 +243,20 @@ var ACNClient = class {
     return this.get("/api/v1/subnets");
   }
   /** Get subnet by ID */
-  async getSubnet(subnetId) {
-    return this.get(`/api/v1/subnets/${subnetId}`);
+  async getSubnet(slug) {
+    return this.get(`/api/v1/subnets/${slug}`);
   }
   /**
    * List immediate children of a subnet (ADR-0003).
    *
-   * Wraps `GET /api/v1/subnets/{parentSubnetId}/children`. Returns
+   * Wraps `GET /api/v1/subnets/{parentSlug}/children`. Returns
    * `SUBNET_NOT_FOUND` when the parent does not exist. Visibility
    * matches `listSubnets` — private children you cannot see are
    * omitted from the result set.
    */
-  async listChildren(parentSubnetId) {
+  async listChildren(parentSlug) {
     const data = await this.get(
-      `/api/v1/subnets/${parentSubnetId}/children`
+      `/api/v1/subnets/${parentSlug}/children`
     );
     return data.subnets;
   }
@@ -262,16 +266,16 @@ var ACNClient = class {
    * Owner-only. Idempotent — promoting an already-persistent subnet
    * returns its current state unchanged.
    */
-  async promoteSubnet(subnetId) {
-    return this.post(`/api/v1/subnets/${subnetId}/promote`);
+  async promoteSubnet(slug) {
+    return this.post(`/api/v1/subnets/${slug}/promote`);
   }
   /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
-  async deleteSubnet(subnetId) {
-    return this.request("DELETE", `/api/v1/subnets/${subnetId}`);
+  async deleteSubnet(slug) {
+    return this.request("DELETE", `/api/v1/subnets/${slug}`);
   }
   /** Get agents in a subnet */
-  async getSubnetAgents(subnetId) {
-    return this.get(`/api/v1/subnets/${subnetId}/agents`);
+  async getSubnetAgents(slug) {
+    return this.get(`/api/v1/subnets/${slug}/agents`);
   }
   // ──────────────────────────────────────────────────────────────────────
   //  Subnet membership (agent-side)
@@ -286,12 +290,12 @@ var ACNClient = class {
   //  scheduled for removal. Requires ACN backend ≥ post-PR-#42.
   // ──────────────────────────────────────────────────────────────────────
   /** Join agent to subnet */
-  async joinSubnet(agentId, subnetId) {
-    return this.post(`/api/v1/agents/${agentId}/subnets/${subnetId}`);
+  async joinSubnet(agentId, slug) {
+    return this.post(`/api/v1/agents/${agentId}/subnets/${slug}`);
   }
   /** Remove agent from subnet */
-  async leaveSubnet(agentId, subnetId) {
-    return this.delete(`/api/v1/agents/${agentId}/subnets/${subnetId}`);
+  async leaveSubnet(agentId, slug) {
+    return this.delete(`/api/v1/agents/${agentId}/subnets/${slug}`);
   }
   /** Get agent's subnets */
   async getAgentSubnets(agentId) {
@@ -317,7 +321,7 @@ var ACNClient = class {
   // `/api/v1/agents/{a}/allowlist/{target}` and is unrelated).
   // ----- Allowlist (owner-only, 3 verbs) ---------------------------------
   /**
-   * Pre-authorise `agentId` on `subnetId`'s allowlist (owner only).
+   * Pre-authorise `agentId` on `slug`'s allowlist (owner only).
    *
    * Allowlisted agents skip the approval queue: their next
    * `joinSubnet` lands in branch 4 (allowlist hit) and becomes an
@@ -327,35 +331,35 @@ var ACNClient = class {
    * return 409 ALREADY_ON_ALLOWLIST (raised as an error, never
    * silently no-op'd).
    */
-  async subnetAllowlistAdd(subnetId, agentId) {
-    return this.post(`/api/v1/subnets/${subnetId}/allowlist`, {
+  async subnetAllowlistAdd(slug, agentId) {
+    return this.post(`/api/v1/subnets/${slug}/allowlist`, {
       agent_id: agentId
     });
   }
   /**
-   * Remove `agentId` from `subnetId`'s allowlist (owner only).
+   * Remove `agentId` from `slug`'s allowlist (owner only).
    *
    * Idempotent — removing an entry that doesn't exist still
    * returns 204. Per ADR-0004 §"Allowlist mutation does not
    * affect agents who already joined", this does NOT revoke
    * membership for agents already admitted via the allowlist.
    */
-  async subnetAllowlistRemove(subnetId, agentId) {
-    await this.delete(`/api/v1/subnets/${subnetId}/allowlist/${agentId}`);
+  async subnetAllowlistRemove(slug, agentId) {
+    await this.delete(`/api/v1/subnets/${slug}/allowlist/${agentId}`);
   }
   /**
-   * List `subnetId`'s allowlist entries (owner only).
+   * List `slug`'s allowlist entries (owner only).
    *
    * Owner-only by design — the allowlist is a privacy-sensitive
    * trust signal and exposing it publicly would leak relationship
    * metadata.
    */
-  async subnetAllowlistList(subnetId, options) {
+  async subnetAllowlistList(slug, options) {
     const params = {
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
-    return this.get(`/api/v1/subnets/${subnetId}/allowlist`, params);
+    return this.get(`/api/v1/subnets/${slug}/allowlist`, params);
   }
   // ----- Join requests (4 verbs: 3 owner-side + 1 applicant-side) --------
   /**
@@ -369,9 +373,9 @@ var ACNClient = class {
    *
    * Optional `note` (≤500 chars) is recorded on the audit row.
    */
-  async subnetJoinRequestApprove(subnetId, requestId, options) {
+  async subnetJoinRequestApprove(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/join-requests/${requestId}/approve`,
+      `/api/v1/subnets/${slug}/join-requests/${requestId}/approve`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -380,9 +384,9 @@ var ACNClient = class {
    *
    * No membership change. `subnet.join_rejected` webhook fires.
    */
-  async subnetJoinRequestReject(subnetId, requestId, options) {
+  async subnetJoinRequestReject(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/join-requests/${requestId}/reject`,
+      `/api/v1/subnets/${slug}/join-requests/${requestId}/reject`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -392,29 +396,29 @@ var ACNClient = class {
    * Self-only — caller must be the agent who originally created
    * the request. `subnet.join_withdrawn` webhook fires.
    */
-  async subnetJoinRequestWithdraw(subnetId, requestId, options) {
+  async subnetJoinRequestWithdraw(slug, requestId, options) {
     return this.request(
       "DELETE",
-      `/api/v1/subnets/${subnetId}/join-requests/${requestId}`,
+      `/api/v1/subnets/${slug}/join-requests/${requestId}`,
       options?.note !== void 0 ? { body: { note: options.note } } : void 0
     );
   }
   /**
-   * Owner lists join_request / allowlist_auto rows for `subnetId`.
+   * Owner lists join_request / allowlist_auto rows for `slug`.
    *
    * `kind` defaults to `'join_request'`; pass `'allowlist_auto'`
    * to inspect synthesised allowlist-hit audit rows. Server
    * rejects `kind='invitation'` with 400 INVALID_KIND_FILTER —
    * use `subnetInvitationList` instead.
    */
-  async subnetJoinRequestList(subnetId, options) {
+  async subnetJoinRequestList(slug, options) {
     const params = {
       kind: options?.kind ?? "join_request",
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
     if (options?.status !== void 0) params.status = options.status;
-    return this.get(`/api/v1/subnets/${subnetId}/join-requests`, params);
+    return this.get(`/api/v1/subnets/${slug}/join-requests`, params);
   }
   // ----- Invitations (5 + 1 verbs) ---------------------------------------
   /**
@@ -429,10 +433,10 @@ var ACNClient = class {
    *
    * Discriminate on `auto_resolved` to dispatch.
    */
-  async subnetInvitationSend(subnetId, agentId, options) {
+  async subnetInvitationSend(slug, agentId, options) {
     const body = { agent_id: agentId };
     if (options?.note !== void 0) body.note = options.note;
-    return this.post(`/api/v1/subnets/${subnetId}/invitations`, body);
+    return this.post(`/api/v1/subnets/${slug}/invitations`, body);
   }
   /**
    * Invitee accepts a pending invitation (CAS pending → approved).
@@ -442,9 +446,9 @@ var ACNClient = class {
    * gains the back-reference, and `subnet.invitation_accepted`
    * webhook fires.
    */
-  async subnetInvitationAccept(subnetId, requestId, options) {
+  async subnetInvitationAccept(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/invitations/${requestId}/accept`,
+      `/api/v1/subnets/${slug}/invitations/${requestId}/accept`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -454,9 +458,9 @@ var ACNClient = class {
    * No membership change. `subnet.invitation_rejected` webhook
    * fires.
    */
-  async subnetInvitationReject(subnetId, requestId, options) {
+  async subnetInvitationReject(slug, requestId, options) {
     return this.post(
-      `/api/v1/subnets/${subnetId}/invitations/${requestId}/reject`,
+      `/api/v1/subnets/${slug}/invitations/${requestId}/reject`,
       options?.note !== void 0 ? { note: options.note } : void 0
     );
   }
@@ -467,26 +471,26 @@ var ACNClient = class {
    * `withdrawn` (not `rejected`) — distinct audit token so
    * consumers can tell "owner gave up" from "invitee said no".
    */
-  async subnetInvitationCancel(subnetId, requestId, options) {
+  async subnetInvitationCancel(slug, requestId, options) {
     return this.request(
       "DELETE",
-      `/api/v1/subnets/${subnetId}/invitations/${requestId}`,
+      `/api/v1/subnets/${slug}/invitations/${requestId}`,
       options?.note !== void 0 ? { body: { note: options.note } } : void 0
     );
   }
   /**
-   * Owner lists invitation rows for `subnetId`.
+   * Owner lists invitation rows for `slug`.
    *
    * Owner-only — invitees use `agentSubnetInvitations` for their
    * own cross-subnet view.
    */
-  async subnetInvitationList(subnetId, options) {
+  async subnetInvitationList(slug, options) {
     const params = {
       limit: options?.limit ?? 100,
       offset: options?.offset ?? 0
     };
     if (options?.status !== void 0) params.status = options.status;
-    return this.get(`/api/v1/subnets/${subnetId}/invitations`, params);
+    return this.get(`/api/v1/subnets/${slug}/invitations`, params);
   }
   /**
    * Invitee's cross-subnet pending-invitation list (self only).
@@ -551,6 +555,31 @@ var ACNClient = class {
     if (options?.consume) params.ack = true;
     return this.get(`/api/v1/communication/history/${agentId}`, params);
   }
+  /**
+   * Precisely acknowledge (remove) specific messages from the inbox.
+   *
+   * Unlike `getMessageHistory({ consume: true })` which clears the entire inbox,
+   * this method removes only the messages whose `route_id` values are listed.
+   *
+   * @param agentId   Must match the authenticated agent's ID.
+   * @param routeIds  List of `route_id` values to remove (up to 500).
+   * @returns         Number of messages actually removed.
+   */
+  async ackInbox(agentId, routeIds) {
+    return this.post(`/api/v1/communication/history/${agentId}/ack`, { route_ids: routeIds });
+  }
+  /**
+   * Update the lifecycle status of a specific inbox message.
+   *
+   * @param agentId  Must match the authenticated agent's ID.
+   * @param routeId  `route_id` of the target message (from inbox listing).
+   * @param status   New status: `"unread"` | `"read"` | `"processed"`.
+   * @returns        Object with `agent_id`, `route_id`, and `status`.
+   * @throws         404 (`inbox_message_not_found`) if route_id is absent from inbox.
+   */
+  async updateInboxMessageStatus(agentId, routeId, status) {
+    return this.patch(`/api/v1/communication/history/${agentId}/${routeId}`, { status });
+  }
   // ============================================
   // Manifest Queue (Phase 2/3)
   // ============================================
@@ -1127,8 +1156,8 @@ var ACNClient = class {
    * Register (or clear) an org-harness webhook URL for a subnet.
    * Pass `harnessUrl: null` to deregister.
    */
-  async registerSubnetHarness(subnetId, harnessUrl, harnessSecret) {
-    await this.request("PATCH", `/api/v1/subnets/${subnetId}/harness`, {
+  async registerSubnetHarness(slug, harnessUrl, harnessSecret) {
+    await this.request("PATCH", `/api/v1/subnets/${slug}/harness`, {
       body: {
         harness_url: harnessUrl,
         harness_secret: harnessSecret ?? null
@@ -1363,11 +1392,17 @@ var KNOWN_PAYMENT_TASK_STATUSES = [
   "payment_failed",
   "refunded"
 ];
+var KNOWN_INBOX_MESSAGE_STATUSES = [
+  "unread",
+  "read",
+  "processed"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACNClient,
   ACNError,
   ACNRealtime,
+  KNOWN_INBOX_MESSAGE_STATUSES,
   KNOWN_PAYMENT_TASK_STATUSES,
   subscribeToACN
 });