acn-client 0.12.0 → 0.13.0

package/README.md

@@ -104,6 +104,9 @@ Options:
 | `unregisterAgent(agentId)` | Unregister an agent |
 | `heartbeat(agentId)` | Send heartbeat |
 | `getSkills()` | List all available skills |
+| `rotateApiKey(agentId)` | Rotate API key — old key invalidated immediately, new key returned once |
+| `getPolicy(agentId)` | Get own inbound communication policy |
+| `updatePolicy(agentId, mode, options?)` | Update inbound policy (`open`/`manifest`/`allowlist`/`closed`) |
 
 #### Subnet Methods
 
@@ -111,11 +114,39 @@ Options:
 |--------|-------------|
 | `listSubnets()` | List all subnets |
 | `getSubnet(subnetId)` | Get subnet by ID |
-| `createSubnet(request)` | Create a new subnet (you become the owner) |
+| `createSubnet(request)` | Create a new subnet (you become the owner); accepts `join_policy`, `parent_subnet_id`, `lifecycle`, `linked_task_id` |
 | `deleteSubnet(subnetId)` | Delete a subnet you own |
 | `getSubnetAgents(subnetId)` | Get agents in subnet |
-| `joinSubnet(agentId, subnetId)` | Join agent to subnet |
+| `joinSubnet(agentId, subnetId)` | Join agent to subnet (dispatches admission flow when `join_policy=approval`) |
 | `leaveSubnet(agentId, subnetId)` | Remove agent from subnet |
+| `listChildren(parentSubnetId)` | List immediate child subnets |
+| `promoteSubnet(subnetId)` | Promote `task_scoped` child to `persistent` (idempotent) |
+
+#### Subnet Admission Methods
+
+Only active on `join_policy=approval` subnets.
+
+| Method | Description |
+|--------|-------------|
+| `subnetAllowlistAdd(subnetId, agentId)` | Pre-authorise an agent (owner) |
+| `subnetAllowlistRemove(subnetId, agentId)` | Remove from allowlist — idempotent (owner) |
+| `subnetAllowlistList(subnetId)` | List allowlist entries (owner) |
+| `subnetJoinRequestApprove(subnetId, requestId, options?)` | Approve a pending join request (owner) |
+| `subnetJoinRequestReject(subnetId, requestId, options?)` | Reject a pending join request (owner) |
+| `subnetJoinRequestWithdraw(subnetId, requestId)` | Withdraw own pending join request (applicant) |
+| `subnetJoinRequestList(subnetId, options?)` | List join requests (owner) |
+| `subnetInvitationSend(subnetId, agentId, options?)` | Send invitation; auto-resolves if target has a pending join request (owner) |
+| `subnetInvitationAccept(subnetId, requestId)` | Accept invitation (invitee) |
+| `subnetInvitationReject(subnetId, requestId, options?)` | Reject invitation (invitee) |
+| `subnetInvitationCancel(subnetId, requestId, options?)` | Cancel invitation (owner) |
+| `subnetInvitationList(subnetId)` | List invitations (owner) |
+| `subnetInvitationsPending()` | Cross-subnet pending invitations (invitee) |
+
+#### Task Methods
+
+| Method | Description |
+|--------|-------------|
+| `getAgentTaskHistory(agentId, limit?)` | Agent's full task history — submissions, review notes, resubmit counts |
 
 #### Communication Methods
 
@@ -223,7 +254,7 @@ import type {
   AgentSearchOptions,
   PaymentCapability,
   WSMessage,
-} from '@acn/client';
+} from 'acn-client';
 ```
 
 ## Browser Support
@@ -241,35 +272,3 @@ MIT
 - [ACN GitHub](https://github.com/acnlabs/ACN)
 - [Documentation](https://github.com/acnlabs/ACN#readme)
 - [Issues](https://github.com/acnlabs/ACN/issues)
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/dist/index.d.mts

@@ -4,8 +4,20 @@
  * Type definitions synced with ACN API models.
  * @see https://github.com/ACNet-AI/ACN
  */
-/** Agent status */
-type AgentStatus = 'online' | 'offline' | 'busy';
+/**
+ * Agent status.
+ *
+ * The server emits exactly `'online'` or `'offline'`, derived from the
+ * Redis `acn:agents:{id}:alive` TTL key (the single source of truth
+ * since the 2026-05 alive-as-SSOT refactor — see ACN
+ * `docs/agent-registry-removal.md`).
+ *
+ * Historical note: this union used to include `'busy'`. The server has
+ * not emitted that value for some time; the literal was narrowed out
+ * in SDK 0.13 to match the on-wire contract. Code paths handling
+ * `'busy'` were unreachable.
+ */
+type AgentStatus = 'online' | 'offline';
 /** Agent list filter status (includes "all" for discovery) */
 type AgentSearchStatus = AgentStatus | 'all';
 /** Agent information */
@@ -107,18 +119,73 @@ interface AgentSearchOptions {
 }
 /** 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`.
+     */
     id: string;
+    /** Wire-side identifier (ADR-0003+ servers always emit this). */
+    subnet_id?: string;
     name: string;
     description?: string;
-    created_at: string;
-    agent_count: number;
+    created_at?: string;
+    agent_count?: number;
     metadata?: Record<string, unknown>;
+    owner?: string;
+    harness_url?: string;
+    harness_registered?: boolean;
+    /** ADR-0003 — parent subnet when this is a nested child. */
+    parent_subnet_id?: string | null;
+    /** ADR-0003 — defaults to `'persistent'` on the server. */
+    lifecycle?: SubnetLifecycle;
+    /** ADR-0003 — bound task when `lifecycle === 'task_scoped'`. */
+    linked_task_id?: string | null;
+    [key: string]: unknown;
+}
+/** Response from `GET /api/v1/subnets/{id}/children` (ADR-0003). */
+interface SubnetChildrenListResponse {
+    count: number;
+    subnets: SubnetInfo[];
 }
+/**
+ * Subnet lifecycle (ADR-0003). `'persistent'` is the legacy default —
+ * the subnet survives until manually deleted. `'task_scoped'` binds
+ * the subnet to a task: the server auto-dissolves it when that task
+ * reaches a terminal state. Only valid together with `linked_task_id`.
+ */
+type SubnetLifecycle = 'persistent' | 'task_scoped';
 /** Subnet creation request */
 interface SubnetCreateRequest {
     name: string;
     description?: string;
     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
+     * must be top-level. Immutable after creation.
+     */
+    parent_subnet_id?: string;
+    /**
+     * ADR-0003 lifecycle. Defaults to `'persistent'` when omitted.
+     * `'task_scoped'` requires `linked_task_id` and the subnet
+     * auto-dissolves when that task terminates.
+     */
+    lifecycle?: SubnetLifecycle;
+    /**
+     * ADR-0003 task binding. Required when `lifecycle === 'task_scoped'`,
+     * ignored otherwise.
+     */
+    linked_task_id?: string;
+    /**
+     * ADR-0004 admission policy. When omitted the server defaults to
+     * `'open'` (legacy unrestricted self-join). `'approval'` opts the
+     * subnet into the admission state machine — joins are gated by
+     * allowlist / join_request / invitation.
+     *
+     * Immutable post-creation.
+     */
+    join_policy?: SubnetJoinPolicy;
 }
 /** Subnet creation response */
 interface SubnetCreateResponse {
@@ -126,6 +193,96 @@ interface SubnetCreateResponse {
     subnet_id: string;
     message: string;
 }
+/** Subnet join-policy values. Immutable post-creation. */
+type SubnetJoinPolicy = 'open' | 'approval';
+/** Single allowlist entry (returned by `subnetAllowlistAdd`). */
+interface SubnetAllowlistEntry {
+    agent_id: string;
+    added_by: string;
+    added_at: string;
+    [key: string]: unknown;
+}
+/** Response envelope for `subnetAllowlistList` (owner only). */
+interface SubnetAllowlistListResponse {
+    subnet_id: string;
+    entries: SubnetAllowlistEntry[];
+    [key: string]: unknown;
+}
+/**
+ * Audit row covering the three ADR-0004 row kinds. The same shape
+ * is returned for join_request approve/reject/withdraw,
+ * invitation accept/reject/cancel, and the allowlist_auto rows
+ * synthesised on allowlist-hit joins. `agent_id` is the applicant
+ * for join_requests / allowlist_auto and the invitee for
+ * invitations.
+ */
+interface SubnetJoinRequestRow {
+    request_id: string;
+    subnet_id: string;
+    kind: 'join_request' | 'allowlist_auto' | 'invitation';
+    status: 'pending' | 'approved' | 'rejected' | 'withdrawn';
+    initiated_by: string;
+    agent_id: string;
+    decided_by?: string | null;
+    decided_at?: string | null;
+    note?: string | null;
+    created_at: string;
+    [key: string]: unknown;
+}
+/** Response envelope for `subnetJoinRequestList` (owner only). */
+interface SubnetJoinRequestListResponse {
+    subnet_id: string;
+    items: SubnetJoinRequestRow[];
+    [key: string]: unknown;
+}
+/** Response envelope for `subnetInvitationList` (owner only). */
+interface SubnetInvitationListResponse {
+    subnet_id: string;
+    items: SubnetJoinRequestRow[];
+    [key: string]: unknown;
+}
+/** Response envelope for `agentSubnetInvitations` (self only). */
+interface AgentSubnetInvitationsResponse {
+    agent_id: string;
+    items: SubnetJoinRequestRow[];
+    [key: string]: unknown;
+}
+/**
+ * Discriminated union for `subnetInvitationSend`. The server
+ * returns 202 + the normal-path shape when the target has no
+ * pending join_request, and 200 + the merge-path shape when an
+ * existing pending join_request is auto-approved by the invite.
+ *
+ * Discriminate on `auto_resolved` (absent | true) to dispatch.
+ */
+type SubnetInvitationSendResponse = {
+    invitation_id: string;
+    status: 'pending';
+    auto_resolved?: undefined;
+    [key: string]: unknown;
+} | {
+    auto_resolved: true;
+    resolved_kind: 'join_request';
+    request_id: string;
+    [key: string]: unknown;
+};
+/** Pagination + filter options for the two list endpoints. */
+interface SubnetJoinRequestListOptions {
+    /**
+     * Defaults to `'join_request'` server-side. Pass `'allowlist_auto'`
+     * to inspect synthesised audit rows. `'invitation'` is rejected
+     * with 400 INVALID_KIND_FILTER — use `subnetInvitationList`.
+     */
+    kind?: 'join_request' | 'allowlist_auto';
+    status?: 'pending' | 'approved' | 'rejected' | 'withdrawn';
+    limit?: number;
+    offset?: number;
+}
+interface SubnetInvitationListOptions {
+    status?: 'pending' | 'approved' | 'rejected' | 'withdrawn';
+    limit?: number;
+    offset?: number;
+}
 /** Message types */
 type MessageType = 'text' | 'data' | 'notification' | 'task' | 'result';
 /** A2A Message */
@@ -294,11 +451,23 @@ interface ManifestSendRequest {
 /**
  * Public read-only summary of an agent's communication policy.
  * Returned by GET /agents/{agent_id}/communication_profile (no auth required).
+ *
+ * `unread_manifest_count` surfaces queue buildup so platform tooling
+ * and senders can detect agents in `manifest` / `allowlist` mode that
+ * have stopped polling. Current ACN releases always populate it.
  */
 interface CommunicationProfile {
     agent_id: string;
     mode: 'open' | 'manifest' | 'allowlist' | 'closed';
     attention_fee_required: boolean;
+    /**
+     * Number of pending manifest entries that have not yet been
+     * acked by this agent. A non-zero (or growing) value signals
+     * that the agent is keeping mail in escrow but not actively
+     * polling — senders should treat them as effectively
+     * unreachable in `manifest` / `allowlist` mode.
+     */
+    unread_manifest_count: number;
 }
 /** Session status values */
 type SessionStatus = 'pending' | 'accepted' | 'rejected' | 'closed';
@@ -651,6 +820,17 @@ interface CommunicationPolicyResponse {
         mode: CommunicationPolicyMode;
         reject_reason?: string;
     };
+    /**
+     * Conditionally present when the post-update `mode` is
+     * `'manifest'` or `'allowlist'`. Carries a human-readable
+     * reminder that messages from non-trusted senders divert to
+     * the manifest queue and require the agent to actively poll
+     * `GET /communication/manifest/{id}` — otherwise those
+     * messages expire after the configured TTL (default 7 days).
+     * Surface this in agent CLIs / dashboards so operators don't
+     * silently lock themselves out.
+     */
+    warning?: string;
 }
 /** Result of an allowlist add/remove action */
 interface AllowlistActionResponse {
@@ -809,6 +989,22 @@ declare class ACNClient {
     }>;
     /** Get subnet by ID */
     getSubnet(subnetId: string): Promise<SubnetInfo>;
+    /**
+     * List immediate children of a subnet (ADR-0003).
+     *
+     * Wraps `GET /api/v1/subnets/{parentSubnetId}/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[]>;
+    /**
+     * 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>;
     /** Delete a subnet you own (requires Agent API Key — only the owning agent can delete) */
     deleteSubnet(subnetId: string): Promise<{
         success: boolean;
@@ -829,6 +1025,138 @@ declare class ACNClient {
     getAgentSubnets(agentId: string): Promise<{
         subnets: string[];
     }>;
+    /**
+     * Pre-authorise `agentId` on `subnetId`'s allowlist (owner only).
+     *
+     * Allowlisted agents skip the approval queue: their next
+     * `joinSubnet` lands in branch 4 (allowlist hit) and becomes an
+     * immediate member with an `allowlist_auto` audit row.
+     *
+     * Server returns 201 with the persisted entry; duplicate adds
+     * return 409 ALREADY_ON_ALLOWLIST (raised as an error, never
+     * silently no-op'd).
+     */
+    subnetAllowlistAdd(subnetId: string, agentId: string): Promise<SubnetAllowlistEntry>;
+    /**
+     * Remove `agentId` from `subnetId`'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>;
+    /**
+     * List `subnetId`'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?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<SubnetAllowlistListResponse>;
+    /**
+     * Owner approves a pending join_request (CAS pending → approved).
+     *
+     * Side effects: applicant added to `subnet.member_agent_ids` and
+     * the `subnet.join_approved` webhook fires. The applicant is
+     * still expected to call `joinSubnet` to register the
+     * `agent.subnet_ids` back-reference (per ADR-0004 §"State
+     * machine edges").
+     *
+     * Optional `note` (≤500 chars) is recorded on the audit row.
+     */
+    subnetJoinRequestApprove(subnetId: string, requestId: string, options?: {
+        note?: string;
+    }): Promise<SubnetJoinRequestRow>;
+    /**
+     * Owner rejects a pending join_request (CAS pending → rejected).
+     *
+     * No membership change. `subnet.join_rejected` webhook fires.
+     */
+    subnetJoinRequestReject(subnetId: string, requestId: string, options?: {
+        note?: string;
+    }): Promise<SubnetJoinRequestRow>;
+    /**
+     * Applicant withdraws their own pending join_request.
+     *
+     * Self-only — caller must be the agent who originally created
+     * the request. `subnet.join_withdrawn` webhook fires.
+     */
+    subnetJoinRequestWithdraw(subnetId: string, requestId: string, options?: {
+        note?: string;
+    }): Promise<SubnetJoinRequestRow>;
+    /**
+     * Owner lists join_request / allowlist_auto rows for `subnetId`.
+     *
+     * `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>;
+    /**
+     * Owner sends an invitation to `agentId` (or merges into a
+     * pending join_request from the same target).
+     *
+     * Two response shapes per ADR-0004 §"Invitation merge path":
+     *
+     *   - **Normal path** (server returns 202): `{ invitation_id, status: 'pending' }`.
+     *   - **Merge path**  (server returns 200, request auto-approved):
+     *     `{ auto_resolved: true, resolved_kind: 'join_request', request_id }`.
+     *
+     * Discriminate on `auto_resolved` to dispatch.
+     */
+    subnetInvitationSend(subnetId: string, agentId: string, options?: {
+        note?: string;
+    }): Promise<SubnetInvitationSendResponse>;
+    /**
+     * Invitee accepts a pending invitation (CAS pending → approved).
+     *
+     * Self-only against the row's `agent_id`. Side effects: invitee
+     * added to `subnet.member_agent_ids`, the agent's `subnet_ids`
+     * gains the back-reference, and `subnet.invitation_accepted`
+     * webhook fires.
+     */
+    subnetInvitationAccept(subnetId: string, requestId: string, options?: {
+        note?: string;
+    }): Promise<SubnetJoinRequestRow>;
+    /**
+     * Invitee rejects a pending invitation (CAS pending → rejected).
+     *
+     * No membership change. `subnet.invitation_rejected` webhook
+     * fires.
+     */
+    subnetInvitationReject(subnetId: string, requestId: string, options?: {
+        note?: string;
+    }): Promise<SubnetJoinRequestRow>;
+    /**
+     * Owner cancels a pending invitation (CAS pending → withdrawn).
+     *
+     * Owner-only counterpart to applicant withdraw. The row goes to
+     * `withdrawn` (not `rejected`) — distinct audit token so
+     * consumers can tell "owner gave up" from "invitee said no".
+     */
+    subnetInvitationCancel(subnetId: string, requestId: string, options?: {
+        note?: string;
+    }): Promise<SubnetJoinRequestRow>;
+    /**
+     * Owner lists invitation rows for `subnetId`.
+     *
+     * Owner-only — invitees use `agentSubnetInvitations` for their
+     * own cross-subnet view.
+     */
+    subnetInvitationList(subnetId: string, options?: SubnetInvitationListOptions): Promise<SubnetInvitationListResponse>;
+    /**
+     * Invitee's cross-subnet pending-invitation list (self only).
+     *
+     * Returns only `status='pending'` rows. Historical decisions
+     * are queryable per-subnet through the owner-only
+     * `subnetInvitationList`.
+     */
+    agentSubnetInvitations(agentId: string): Promise<AgentSubnetInvitationsResponse>;
     /** Send message to an agent */
     sendMessage(request: SendMessageRequest): Promise<SendMessageResponse>;
     /** Broadcast message to multiple agents in a subnet */
@@ -1387,4 +1715,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 AgentStatus, 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 ComponentHealth, type DashboardData, type FollowActionResponse, type FollowCheckResponse, KNOWN_PAYMENT_TASK_STATUSES, type ManifestContentResponse, type ManifestEntry, type ManifestListResponse, 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 SendMessageRequest, type SendMessageResponse, type SubnetCreateRequest, type SubnetCreateResponse, type SubnetHarnessRequest, type SubnetInfo, 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_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 };