@pantheon-systems/css-client 0.16.0-canary-20260911222513 → 0.16.0

package/dist/auth.d.ts

@@ -1,8 +1,25 @@
 /**
  * P1 Client Authentication Utilities
  *
- * Functions for creating authentication providers.
+ * Functions for creating authentication providers, and role/permission types.
  */
+export type RoleName = 'ADMIN' | 'EDITOR' | 'VIEWER' | 'NO_ACCESS';
+export interface RolePermissions {
+    canView: boolean;
+    canEdit: boolean;
+    canCreateBranch: boolean;
+    canEditDocuments: boolean;
+    canCreateCheckpoint: boolean;
+    canProposeMerge: boolean;
+    canMerge: boolean;
+    canMergeToMain: boolean;
+    canManageGrants: boolean;
+    canManageTemplates: boolean;
+}
+export interface ViewerRole {
+    roleName: RoleName;
+    permissions: RolePermissions;
+}
 /**
  * Authentication provider function type.
  * Returns the authorization header value.

package/dist/client.d.ts

@@ -4,9 +4,9 @@
  * Main client class for interacting with Pantheon's P1 content platform API.
  */
 import type { AuthProvider } from './auth.js';
-import type { Principal } from './types.js';
+import type { Principal } from './types/index.js';
 import type { SdkIdentity } from './telemetry-headers.js';
-import { BaseEndpoint, SitesEndpoint, BranchesEndpoint, DocumentsEndpoint, VersionsEndpoint, CheckpointsEndpoint, PresenceEndpoint, AgentRegistryEndpoint, AgentEditEndpoint, MergeEndpoint, TemplatesEndpoint, MigrationConflictsEndpoint, QueriesEndpoint, TranslationsEndpoint, RelationsEndpoint } from './endpoints/index.js';
+import { BaseEndpoint, AuthEndpoint, SitesEndpoint, BranchesEndpoint, DocumentsEndpoint, VersionsEndpoint, CheckpointsEndpoint, PresenceEndpoint, AgentRegistryEndpoint, AgentEditEndpoint, MergeEndpoint, TemplatesEndpoint, MigrationConflictsEndpoint, QueriesEndpoint, TranslationsEndpoint, RelationsEndpoint, ThreadsEndpoint } from './endpoints/index.js';
 /**
  * Configuration options for P1Client.
  */
@@ -150,6 +150,12 @@ export declare class P1Client {
      * Relation edges: upstream drift for localization and template derivation.
      */
     readonly relations: RelationsEndpoint;
+    /** Advisory endpoint: resolves the calling user's role on a branch. */
+    readonly auth: AuthEndpoint;
+    /**
+     * Comment threads anchored to blocks, pages, sites and workstreams.
+     */
+    readonly threads: ThreadsEndpoint;
     constructor(config: P1ClientConfig | InternalConfig);
     /**
      * Create a new client instance with a different principal.

package/dist/client.js

@@ -1,4 +1,4 @@
-import { BaseEndpoint, SitesEndpoint, BranchesEndpoint, DocumentsEndpoint, VersionsEndpoint, CheckpointsEndpoint, PresenceEndpoint, AgentRegistryEndpoint, AgentEditEndpoint, MergeEndpoint, TemplatesEndpoint, MigrationConflictsEndpoint, QueriesEndpoint, TranslationsEndpoint, RelationsEndpoint, } from './endpoints/index.js';
+import { BaseEndpoint, AuthEndpoint, SitesEndpoint, BranchesEndpoint, DocumentsEndpoint, VersionsEndpoint, CheckpointsEndpoint, PresenceEndpoint, AgentRegistryEndpoint, AgentEditEndpoint, MergeEndpoint, TemplatesEndpoint, MigrationConflictsEndpoint, QueriesEndpoint, TranslationsEndpoint, RelationsEndpoint, ThreadsEndpoint, } from './endpoints/index.js';
 export class P1Client {
     baseEndpoint;
     sites;
@@ -15,6 +15,8 @@ export class P1Client {
     queries;
     translations;
     relations;
+    auth;
+    threads;
     constructor(config) {
         if ('baseEndpoint' in config) {
             this.baseEndpoint = config.baseEndpoint;
@@ -45,6 +47,8 @@ export class P1Client {
         this.queries = new QueriesEndpoint(this.baseEndpoint);
         this.translations = new TranslationsEndpoint(this.baseEndpoint);
         this.relations = new RelationsEndpoint(this.baseEndpoint);
+        this.auth = new AuthEndpoint(this.baseEndpoint);
+        this.threads = new ThreadsEndpoint(this.baseEndpoint);
     }
     withPrincipal(principal) {
         const newBaseEndpoint = this.baseEndpoint.withPrincipal(principal);

package/dist/endpoints/agent-edit.d.ts

@@ -3,7 +3,7 @@
  *
  * API endpoints for the agent edit workflow (politeness protocol).
  */
-import type { AgentEditContext, AgentEditPermission, AgentEditSession, AgentEditCompleteResult, AgentEditAbortResult, AgentStopResult } from '../types.js';
+import type { AgentEditContext, AgentEditPermission, AgentEditSession, AgentEditCompleteResult, AgentEditAbortResult, AgentStopResult } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 /**
  * Agent edit endpoint for managing agent edit sessions.
@@ -63,16 +63,20 @@ export declare class AgentEditEndpoint {
      */
     abortEdit(siteId: string, branchId: string, documentPath: string, agentId: string, checkpointId: string): Promise<AgentEditAbortResult>;
     /**
-     * Stop an agent's edit session (human-initiated).
-     *
-     * Server looks up the agent's active session and rolls back
-     * to the checkpoint created at edit-start. This allows humans
-     * to stop an agent without knowing the session/checkpoint IDs.
+     * Stop an agent that is editing a document.
      *
      * @param siteId - Site ID
      * @param branchId - Branch ID
      * @param documentPath - Document path
-     * @param agentId - Agent ID to stop
+     * @param target - The agent to stop, or the specific turn to stop; at least one of
+     *   the two is required. Pass a turn when you know it: a turn between edits holds no
+     *   session to find it by.
      */
-    stopAgent(siteId: string, branchId: string, documentPath: string, agentId: string): Promise<AgentStopResult>;
+    stopAgent(siteId: string, branchId: string, documentPath: string, target: string | {
+        agentId: string;
+        turnId?: string;
+    } | {
+        agentId?: string;
+        turnId: string;
+    }): Promise<AgentStopResult>;
 }

package/dist/endpoints/agent-edit.js

@@ -48,11 +48,12 @@ export class AgentEditEndpoint {
             body: JSON.stringify({ agentId, checkpointId }),
         });
     }
-    async stopAgent(siteId, branchId, documentPath, agentId) {
+    async stopAgent(siteId, branchId, documentPath, target) {
         const encodedPath = this.encodeDocumentPath(documentPath);
+        const body = typeof target === 'string' ? { agentId: target } : target;
         return this.base.request(`/api/sites/${siteId}/branches/${branchId}/documents/${encodedPath}/agent-stop`, {
             method: 'POST',
-            body: JSON.stringify({ agentId }),
+            body: JSON.stringify(body),
         });
     }
 }

package/dist/endpoints/agent-registry.d.ts

@@ -3,7 +3,7 @@
  *
  * API endpoints for managing registered agents in an organization.
  */
-import type { RegisteredAgent, CreateAgentParams, UpdateAgentParams, ListAgentsOptions, AgentStatus } from '../types.js';
+import type { RegisteredAgent, CreateAgentParams, UpdateAgentParams, ListAgentsOptions, AgentStatus } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 /**
  * Agent registry endpoint for managing organization agents.

package/dist/endpoints/auth.d.ts

@@ -0,0 +1,7 @@
+import type { ViewerRole } from '../auth.js';
+import type { BaseEndpoint } from './base.js';
+export declare class AuthEndpoint {
+    private readonly base;
+    constructor(base: BaseEndpoint);
+    getRole(siteId: string, branchId: string): Promise<ViewerRole>;
+}

package/dist/endpoints/auth.js

@@ -0,0 +1,11 @@
+import { requirePathParams } from '../utils.js';
+export class AuthEndpoint {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async getRole(siteId, branchId) {
+        requirePathParams({ siteId, branchId }, 'auth.getRole');
+        return this.base.request(`/api/sites/${encodeURIComponent(siteId)}/branches/${encodeURIComponent(branchId)}/auth/role`, { method: 'GET' });
+    }
+}

package/dist/endpoints/base.d.ts

@@ -4,7 +4,7 @@
  * Shared HTTP request logic for all endpoints.
  */
 import type { AuthProvider } from '../auth.js';
-import type { Principal } from '../types.js';
+import type { Principal } from '../types/index.js';
 import { type SdkIdentity } from '../telemetry-headers.js';
 export interface BaseEndpointConfig {
     baseUrl: string;

package/dist/endpoints/branches.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for branches.
  */
-import type { Branch, CreateBranchParams, PaginationOptions } from '../types.js';
+import type { Branch, CreateBranchParams, PaginationOptions } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class BranchesEndpoint {
     private readonly base;

package/dist/endpoints/checkpoints.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for checkpoints.
  */
-import type { Checkpoint, CheckpointDocument, CreateCheckpointParams, PaginationOptions } from '../types.js';
+import type { Checkpoint, CheckpointDocument, CreateCheckpointParams, PaginationOptions } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class CheckpointsEndpoint {
     private readonly base;

package/dist/endpoints/documents.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for documents.
  */
-import type { Document, CreateDocumentParams, ListDocumentsOptions, PublishDocumentResult } from '../types.js';
+import type { Document, CreateDocumentParams, ListDocumentsOptions, PublishDocumentResult } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class DocumentsEndpoint {
     private readonly base;

package/dist/endpoints/index.d.ts

@@ -2,6 +2,7 @@
  * Endpoints barrel export.
  */
 export { BaseEndpoint } from './base.js';
+export { AuthEndpoint } from './auth.js';
 export type { BaseEndpointConfig, RequestOptions } from './base.js';
 export { SitesEndpoint } from './sites.js';
 export { BranchesEndpoint } from './branches.js';
@@ -17,3 +18,4 @@ export { MigrationConflictsEndpoint } from './migration-conflicts.js';
 export { QueriesEndpoint } from './queries.js';
 export { TranslationsEndpoint } from './translations.js';
 export { RelationsEndpoint } from './relations.js';
+export { ThreadsEndpoint } from './threads.js';

package/dist/endpoints/index.js

@@ -1,4 +1,5 @@
 export { BaseEndpoint } from './base.js';
+export { AuthEndpoint } from './auth.js';
 export { SitesEndpoint } from './sites.js';
 export { BranchesEndpoint } from './branches.js';
 export { DocumentsEndpoint } from './documents.js';
@@ -13,3 +14,4 @@ export { MigrationConflictsEndpoint } from './migration-conflicts.js';
 export { QueriesEndpoint } from './queries.js';
 export { TranslationsEndpoint } from './translations.js';
 export { RelationsEndpoint } from './relations.js';
+export { ThreadsEndpoint } from './threads.js';

package/dist/endpoints/merge.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for merge checks, previews, execution, and merge requests.
  */
-import type { MergeabilityResult, MergePreview, MergeExecuteParams, MergeExecuteResult, MergeJob, MergeRequest, CreateMergeRequestParams, UpdateMergeRequestParams, ListMergeRequestsOptions, ExecuteMergeRequestOptions } from '../types.js';
+import type { MergeabilityResult, MergePreview, MergeExecuteParams, MergeExecuteResult, MergeJob, MergeRequest, CreateMergeRequestParams, UpdateMergeRequestParams, ListMergeRequestsOptions, ExecuteMergeRequestOptions } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class MergeEndpoint {
     private readonly base;

package/dist/endpoints/merge.js

@@ -1,4 +1,4 @@
-import { TERMINAL_MERGE_JOB_STATUSES } from '../types.js';
+import { TERMINAL_MERGE_JOB_STATUSES } from '../types/index.js';
 import { requirePathParams } from '../utils.js';
 export class MergeEndpoint {
     base;

package/dist/endpoints/migration-conflicts.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for reviewing and resolving template migration conflicts.
  */
-import type { MigrationConflict } from '../types.js';
+import type { MigrationConflict } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class MigrationConflictsEndpoint {
     private readonly base;

package/dist/endpoints/presence.d.ts

@@ -3,7 +3,7 @@
  *
  * API endpoints for querying presence data at site, branch, and agent levels.
  */
-import type { SitePresence, BranchPresence, AgentGlobalPresence, UpdateFocusRegionsResponse } from '../types.js';
+import type { SitePresence, BranchPresence, AgentGlobalPresence, UpdateFocusRegionsResponse } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 /**
  * Presence endpoint for querying actor presence data.

package/dist/endpoints/queries.d.ts

@@ -1,4 +1,4 @@
-import type { Query, QueryResults, QueryResultsParams } from '../types.js';
+import type { Query, QueryResults, QueryResultsParams } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class QueriesEndpoint {
     private readonly base;

package/dist/endpoints/relations.d.ts

@@ -1,11 +1,12 @@
 /**
  * Relations Endpoint
  *
- * Read operations over the derivation edges of a document (localization and
- * template). The upstream-diff endpoint classifies how the document has drifted
- * from its upstream source so an author can reconcile.
+ * Operations over the derivation edges of a document (localization and template).
+ * The upstream-diff endpoint classifies how the document has drifted from its
+ * upstream source so an author can reconcile, and the resolution endpoints record
+ * which props have been dealt with so a change is not reported forever.
  */
-import type { ChangeSummary } from '../types.js';
+import type { ChangeSummary, UpstreamResolutions, UpstreamResolutionTarget } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class RelationsEndpoint {
     private readonly base;
@@ -15,5 +16,27 @@ export declare class RelationsEndpoint {
      * `documentId` is the derived side of the relation edge (the current page). Rejects
      * with NotFoundError when no edge of that type exists.
      */
-    getUpstreamDiff(siteId: string, branchId: string, documentId: string, relationType: 'localization' | 'template'): Promise<ChangeSummary>;
+    getUpstreamDiff(siteId: string, branchId: string, documentId: string, relationType: 'localization' | 'template', includeResolved?: boolean): Promise<ChangeSummary>;
+    /**
+     * Which of a translation's reported changes have been reconciled against their
+     * canonical, and at what canonical version. Rejects with NotFoundError when the
+     * document is not a translation.
+     */
+    getUpstreamResolutions(siteId: string, branchId: string, documentId: string): Promise<UpstreamResolutions>;
+    /**
+     * Records that reported changes have been reconciled, so they stop being
+     * reported. Taking the canonical value, writing your own translation of it, and
+     * deciding the translation keeps what it has all count as reconciling.
+     *
+     * `upstreamVersionId` is the `toVersionId` of the summary the changes were read
+     * from, so what gets settled is the state that was shown; a change the canonical
+     * made after that stays outstanding. Rejects a version that does not belong to
+     * the canonical, and a slot it no longer holds.
+     *
+     * Recorded per branch, so reconciling on one branch leaves the others as they
+     * were.
+     */
+    setUpstreamResolutions(siteId: string, branchId: string, documentId: string, targets: UpstreamResolutionTarget[], upstreamVersionId: string): Promise<UpstreamResolutions>;
+    /** Clears the changes' resolutions, returning them to the outstanding list. */
+    clearUpstreamResolutions(siteId: string, branchId: string, documentId: string, targets: UpstreamResolutionTarget[]): Promise<UpstreamResolutions>;
 }

package/dist/endpoints/relations.js

@@ -3,7 +3,20 @@ export class RelationsEndpoint {
     constructor(base) {
         this.base = base;
     }
-    async getUpstreamDiff(siteId, branchId, documentId, relationType) {
-        return this.base.request(`/api/sites/${siteId}/branches/${branchId}/documents/${documentId}/upstream-diff?relationType=${relationType}`, { method: 'GET' });
+    async getUpstreamDiff(siteId, branchId, documentId, relationType, includeResolved = false) {
+        const query = new URLSearchParams({ relationType });
+        if (includeResolved) {
+            query.set('includeResolved', 'true');
+        }
+        return this.base.request(`/api/sites/${siteId}/branches/${branchId}/documents/${documentId}/upstream-diff?${query.toString()}`, { method: 'GET' });
+    }
+    async getUpstreamResolutions(siteId, branchId, documentId) {
+        return this.base.request(`/api/sites/${siteId}/branches/${branchId}/documents/${documentId}/upstream-resolutions`, { method: 'GET' });
+    }
+    async setUpstreamResolutions(siteId, branchId, documentId, targets, upstreamVersionId) {
+        return this.base.request(`/api/sites/${siteId}/branches/${branchId}/documents/${documentId}/upstream-resolutions`, { method: 'PUT', body: JSON.stringify({ targets, upstreamVersionId }) });
+    }
+    async clearUpstreamResolutions(siteId, branchId, documentId, targets) {
+        return this.base.request(`/api/sites/${siteId}/branches/${branchId}/documents/${documentId}/upstream-resolutions`, { method: 'DELETE', body: JSON.stringify({ targets }) });
     }
 }

package/dist/endpoints/sites.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for sites.
  */
-import type { Site, PaginationOptions, SiteSettingsResult } from '../types.js';
+import type { Site, PaginationOptions, SiteMembers, SiteSettingsResult } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class SitesEndpoint {
     private readonly base;
@@ -16,6 +16,11 @@ export declare class SitesEndpoint {
      * Get a site's settings, including the locales it publishes in.
      */
     getSettings(siteId: string): Promise<SiteSettingsResult>;
+    /**
+     * The people and agents on a site, for pickers. Anyone who can view the site
+     * can read its roster.
+     */
+    members(siteId: string): Promise<SiteMembers>;
     /**
      * List all sites.
      */

package/dist/endpoints/sites.js

@@ -16,6 +16,12 @@ export class SitesEndpoint {
             method: 'GET',
         });
     }
+    async members(siteId) {
+        requirePathParams({ siteId }, 'sites.members');
+        return this.base.request(`/api/sites/${siteId}/members`, {
+            method: 'GET',
+        });
+    }
     async list(options) {
         const params = new URLSearchParams();
         if (options?.limit !== undefined) {

package/dist/endpoints/templates.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for content type templates.
  */
-import type { Template, TemplateSummary, CreateTemplateParams, UpdateTemplateParams, MigrationJob, MigrationPreview } from '../types.js';
+import type { Template, TemplateSummary, CreateTemplateParams, UpdateTemplateParams, MigrationJob, MigrationPreview } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class TemplatesEndpoint {
     private readonly base;

package/dist/endpoints/threads.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Threads Endpoint
+ *
+ * Comment threads anchored to a block, page, site or workstream. Threads are
+ * site-scoped: a block thread follows its block across branches.
+ */
+import type { CommentContent, ThreadContextRef, ListThreadsOptions, PostCommentResult, PostThreadParams, ProposalDecision, ThreadListPage, ThreadOverview, ThreadStatus, ThreadWithComments } from '../types/threads/index.js';
+import type { BaseEndpoint } from './base.js';
+export declare class ThreadsEndpoint {
+    private readonly base;
+    constructor(base: BaseEndpoint);
+    /**
+     * List threads on a site, newest activity first. Pass `documentId` to get
+     * that page's threads: one overview per context, the open thread when there
+     * is one, otherwise the latest resolved one.
+     */
+    listThreads(siteId: string, options?: ListThreadsOptions): Promise<ThreadListPage>;
+    /**
+     * Every thread ever opened on one context, open and resolved alike.
+     */
+    listContextThreads(siteId: string, context: ThreadContextRef): Promise<ThreadOverview[]>;
+    /**
+     * One thread with its comments, oldest first.
+     */
+    getThread(siteId: string, threadId: string): Promise<ThreadWithComments>;
+    /**
+     * Open a thread on a context with its first comment. Posting to a context
+     * that already has an open thread appends to it instead.
+     */
+    postThread(siteId: string, params: PostThreadParams): Promise<PostCommentResult>;
+    /**
+     * Reply to an existing thread. Replying to a resolved thread reopens it. A
+     * plain string posts a message; an agent passes the full content to leave
+     * a working line or a proposal.
+     */
+    postComment(siteId: string, threadId: string, content: string | CommentContent): Promise<PostCommentResult>;
+    /**
+     * Replace one of the caller's own comments, kind and state included. This is
+     * how an agent turns its working line into its answer.
+     */
+    updateComment(siteId: string, threadId: string, commentId: string, content: CommentContent): Promise<PostCommentResult>;
+    /**
+     * Accept or dismiss an agent's proposal. Only a proposal still waiting can be
+     * decided. Accepting applies the proposed operations to the document as the
+     * deciding user before the decision is recorded, so the change reaches every
+     * open editor over realtime; a refusal leaves the proposal undecided.
+     */
+    decideProposal(siteId: string, threadId: string, commentId: string, decision: ProposalDecision): Promise<PostCommentResult>;
+    /**
+     * Resolve or reopen a thread. Setting the status it already has is a no-op.
+     */
+    setThreadStatus(siteId: string, threadId: string, status: ThreadStatus): Promise<ThreadOverview>;
+    /**
+     * Record that a mentioned agent never replied, so the share of mentions that go
+     * unanswered can be measured rather than guessed at. Takes the id of the comment
+     * that did the mentioning and how long the reader waited. Nothing is stored
+     * against the thread, and viewing the thread is enough permission to report.
+     */
+    reportUnansweredMention(siteId: string, threadId: string, report: {
+        commentId: string;
+        agentId: string;
+        elapsedMs: number;
+    }): Promise<void>;
+}

package/dist/endpoints/threads.js

@@ -0,0 +1,70 @@
+import { requirePathParams } from '../utils.js';
+export class ThreadsEndpoint {
+    base;
+    constructor(base) {
+        this.base = base;
+    }
+    async listThreads(siteId, options) {
+        requirePathParams({ siteId }, 'threads.listThreads');
+        const params = new URLSearchParams();
+        if (options?.documentId !== undefined)
+            params.set('documentId', options.documentId);
+        if (options?.status !== undefined)
+            params.set('status', options.status);
+        if (options?.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options?.cursor !== undefined)
+            params.set('cursor', options.cursor);
+        const query = params.toString();
+        const path = query
+            ? `/api/sites/${siteId}/threads?${query}`
+            : `/api/sites/${siteId}/threads`;
+        return this.base.request(path, { method: 'GET' });
+    }
+    async listContextThreads(siteId, context) {
+        requirePathParams({ siteId, contextId: context.id }, 'threads.listContextThreads');
+        const response = await this.base.request(`/api/sites/${siteId}/contexts/${context.type}/${encodeURIComponent(context.id)}/threads`, { method: 'GET' });
+        return response.threads;
+    }
+    async getThread(siteId, threadId) {
+        requirePathParams({ siteId, threadId }, 'threads.getThread');
+        return this.base.request(`/api/sites/${siteId}/threads/${threadId}`, {
+            method: 'GET',
+        });
+    }
+    async postThread(siteId, params) {
+        requirePathParams({ siteId }, 'threads.postThread');
+        return this.base.request(`/api/sites/${siteId}/threads`, {
+            method: 'POST',
+            body: JSON.stringify(params),
+        });
+    }
+    async postComment(siteId, threadId, content) {
+        requirePathParams({ siteId, threadId }, 'threads.postComment');
+        return this.base.request(`/api/sites/${siteId}/threads/${threadId}/comments`, {
+            method: 'POST',
+            body: JSON.stringify(typeof content === 'string' ? { body: content } : content),
+        });
+    }
+    async updateComment(siteId, threadId, commentId, content) {
+        requirePathParams({ siteId, threadId, commentId }, 'threads.updateComment');
+        return this.base.request(`/api/sites/${siteId}/threads/${threadId}/comments/${commentId}`, { method: 'PUT', body: JSON.stringify(content) });
+    }
+    async decideProposal(siteId, threadId, commentId, decision) {
+        requirePathParams({ siteId, threadId, commentId }, 'threads.decideProposal');
+        return this.base.request(`/api/sites/${siteId}/threads/${threadId}/comments/${commentId}/decision`, { method: 'PUT', body: JSON.stringify({ decision }) });
+    }
+    async setThreadStatus(siteId, threadId, status) {
+        requirePathParams({ siteId, threadId }, 'threads.setThreadStatus');
+        const response = await this.base.request(`/api/sites/${siteId}/threads/${threadId}/status`, { method: 'PUT', body: JSON.stringify({ status }) });
+        return response.thread;
+    }
+    async reportUnansweredMention(siteId, threadId, report) {
+        requirePathParams({ siteId, threadId }, 'threads.reportUnansweredMention');
+        await this.base.request(`/api/sites/${siteId}/threads/${threadId}/unanswered-mentions`, {
+            method: 'POST',
+            body: JSON.stringify(report),
+            keepalive: true,
+        });
+    }
+}

package/dist/endpoints/translations.d.ts

@@ -4,7 +4,7 @@
  * API operations for localization: creating and listing translation variants
  * of a canonical document.
  */
-import type { AuthorityOverridesResult, CreateTranslationParams, CreateTranslationResult, ListTranslationsResult, PropAuthority } from '../types.js';
+import type { AuthorityOverridesResult, CreateTranslationParams, CreateTranslationResult, ListTranslationsResult, PropAuthority } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class TranslationsEndpoint {
     private readonly base;

package/dist/endpoints/versions.d.ts

@@ -3,7 +3,7 @@
  *
  * API operations for document versions.
  */
-import type { DocumentVersion, CreateDocumentVersionParams, PaginationOptions } from '../types.js';
+import type { DocumentVersion, CreateDocumentVersionParams, PaginationOptions } from '../types/index.js';
 import type { BaseEndpoint } from './base.js';
 export declare class VersionsEndpoint {
     private readonly base;

package/dist/index.d.ts

@@ -6,9 +6,11 @@
 export { P1Client } from './client.js';
 export type { P1ClientConfig } from './client.js';
 export { PRODUCTION_BASE_URL } from './constants.js';
-export type { Site, Branch, BranchStatus, Document, DocumentVersion, DocumentVersionSource, Checkpoint, CheckpointType, CheckpointStatus, CheckpointDocument, WorkflowSettings, PuckData, PuckComponentData, PuckRootData, Principal, PaginationOptions, CreateBranchParams, CreateDocumentParams, CreateDocumentVersionParams, CreateCheckpointParams, PublishDocumentResult, ListDocumentsOptions, ActorState, ActorRole, ActorPresence, DocumentPresenceSummary, BranchPresenceSummary, BranchPresence, SitePresence, AgentPresenceLocation, AgentGlobalPresence, AgentStatus, AgentSettings, RegisteredAgent, CreateAgentParams, UpdateAgentParams, ListAgentsOptions, AgentTrigger, AgentEditDenialReason, AgentEditContext, AgentEditPermission, AgentEditSession, AgentEditCompleteResult, AgentEditAbortResult, AgentStopResult, UpdateFocusRegionsResponse, PublishResult, ConflictResolutionStrategy, MergeRequestStatus, DocumentConflictType, DocumentConflict, ConflictDetails, MergeabilityResult, DocumentDiff, MergePreview, MergeExecuteParams, MergeExecuteResult, MergeRequest, CreateMergeRequestParams, UpdateMergeRequestParams, ListMergeRequestsOptions, ExecuteMergeRequestOptions, Template, TemplateSummary, TemplateMetadata, TemplateContentItem, TemplateRootProps, CreateTemplateParams, UpdateTemplateParams, MigrationJob, MigrationConflict, MigrationPreview, MigrationPreviewDocument, TriggerMigrationParams, Datasource, QuerySortField, Query, QueryResultItem, QueryResultsMeta, QueryResults, QueryResultsParams, LocalePolicy, SiteLocales, SiteSettings, SiteSettingsResult, TranslationMode, LocalizationRelation, CreateTranslationParams, CreateTranslationResult, TranslationVariant, ListTranslationsResult, PropAuthority, AuthorityOverridesMap, AuthorityOverridesResult, ChangeClassification, ChangeSummaryEntry, ChangeSummary, } from './types.js';
+export type { Site, Branch, BranchStatus, Document, DocumentVersion, DocumentVersionSource, Checkpoint, CheckpointType, CheckpointStatus, CheckpointDocument, WorkflowSettings, PuckData, PuckComponentData, PuckRootData, Principal, PaginationOptions, CreateBranchParams, CreateDocumentParams, CreateDocumentVersionParams, CreateCheckpointParams, PublishDocumentResult, ListDocumentsOptions, ActorState, ActorRole, ActorPresence, DocumentPresenceSummary, BranchPresenceSummary, BranchPresence, SitePresence, AgentPresenceLocation, AgentGlobalPresence, AgentStatus, AgentSettings, RegisteredAgent, CreateAgentParams, UpdateAgentParams, ListAgentsOptions, AgentTrigger, AgentEditDenialReason, AgentEditContext, AgentEditPermission, AgentEditSession, AgentEditCompleteResult, AgentEditAbortResult, AgentStopResult, UpdateFocusRegionsResponse, PublishResult, ConflictResolutionStrategy, MergeRequestStatus, DocumentConflictType, DocumentConflict, ConflictDetails, MergeabilityResult, DocumentDiff, MergePreview, MergeExecuteParams, MergeExecuteResult, MergeRequest, CreateMergeRequestParams, UpdateMergeRequestParams, ListMergeRequestsOptions, ExecuteMergeRequestOptions, Template, TemplateSummary, TemplateMetadata, TemplateContentItem, TemplateRootProps, CreateTemplateParams, UpdateTemplateParams, MigrationJob, MigrationConflict, MigrationPreview, MigrationPreviewDocument, TriggerMigrationParams, Datasource, QuerySortField, Query, QueryResultItem, QueryResultsMeta, QueryResults, QueryResultsParams, LocalePolicy, SiteLocales, SiteSettings, SiteSettingsResult, TranslationMode, LocalizationRelation, CreateTranslationParams, CreateTranslationResult, TranslationVariant, ListTranslationsResult, PropAuthority, AuthorityOverridesMap, AuthorityOverridesResult, ChangeClassification, ChangeSummaryEntry, ChangeSummary, UpstreamResolutions, UpstreamResolutionTarget, SiteMemberRole, AgentSiteRole, SiteMemberUser, SiteMemberAgent, SiteMembers, } from './types/index.js';
+export type * from './types/threads/index.js';
+export { isAgentProposal, isAgentWorking } from './types/threads/index.js';
 export { createApiKeyAuth, createTokenAuth, InMemoryTokenStorage, LocalStorageTokenStorage, } from './auth.js';
-export type { AuthProvider, TokenStorage } from './auth.js';
+export type { AuthProvider, TokenStorage, RoleName, RolePermissions, ViewerRole } from './auth.js';
 export { createOAuthAuthProvider, validateToken, loginMockUser, } from './oauth.js';
 export type { OAuthUserInfo, OAuthSession, AuthMeResponse, } from './oauth.js';
 export { createBrokerAuth, brokerLogout, hasPendingBrokerLogin, redeemPendingBrokerLogin } from './broker.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { P1Client } from './client.js';
 export { PRODUCTION_BASE_URL } from './constants.js';
+export { isAgentProposal, isAgentWorking } from './types/threads/index.js';
 export { createApiKeyAuth, createTokenAuth, InMemoryTokenStorage, LocalStorageTokenStorage, } from './auth.js';
 export { createOAuthAuthProvider, validateToken, loginMockUser, } from './oauth.js';
 export { createBrokerAuth, brokerLogout, hasPendingBrokerLogin, redeemPendingBrokerLogin } from './broker.js';

package/dist/realtime.d.ts

@@ -6,7 +6,7 @@
  * Uses ReconnectingWebSocket from partysocket for automatic reconnection with exponential backoff.
  */
 import * as Y from 'yjs';
-import type { ActorPresence, ActorState, PublishResult } from './types';
+import type { ActorPresence, ActorState, ThreadEvent, PublishResult } from './types/index.js';
 /**
  * Configuration for reconnection behavior
  */
@@ -101,6 +101,10 @@ export interface RealtimeClientConfig {
      * Use this to notify users that the document is being refreshed.
      */
     onServerReload?: () => void;
+    /**
+     * Called when a comment or thread on this document changes, from any editor.
+     */
+    onThreadEvent?: (event: ThreadEvent) => void;
     /**
      * Called when the server reports this client's Yjs history has diverged from
      * the document's current state (close code 4002). The caller must discard this

package/dist/realtime.js

@@ -435,6 +435,9 @@ export class RealtimeClient {
                     }
                     break;
                 }
+                case 'thread_event':
+                    this.config.onThreadEvent?.(message.event);
+                    break;
                 case 'presence_error':
                     if (message.code === 'RATE_LIMITED') {
                         this.config.onRateLimited?.();

package/dist/sdk-version.d.ts

@@ -7,4 +7,4 @@
 /** Name half of `x-p1-sdk`. */
 export declare const SDK_NAME = "css-client";
 /** Version half of `x-p1-sdk`, matching the published release. */
-export declare const SDK_VERSION = "0.16.0-canary-20260911222513";
+export declare const SDK_VERSION = "0.16.0";

package/dist/sdk-version.js

@@ -1,2 +1,2 @@
 export const SDK_NAME = 'css-client';
-export const SDK_VERSION = '0.16.0-canary-20260911222513';
+export const SDK_VERSION = '0.16.0';

package/dist/{types.d.ts → types/index.d.ts}

@@ -3,6 +3,7 @@
  *
  * TypeScript types matching Pantheon's P1 content platform API.
  */
+import type { ThreadEvent } from './threads/index.js';
 /**
  * Workflow settings for a site.
  */
@@ -119,6 +120,22 @@ export interface Document {
  * Document version source types.
  */
 export type DocumentVersionSource = 'edit' | 'merge' | 'revert' | 'initial';
+/**
+ * Who a version's change really came from when an agent's accepted proposal was
+ * applied by a person: the agent that proposed it, the person it was applied for,
+ * and the agent's summary of the change.
+ */
+export interface VersionAttribution {
+    agent: {
+        id: string;
+        name: string;
+    };
+    onBehalfOf: {
+        id: string;
+        name: string;
+    };
+    description: string;
+}
 /**
  * A version of a document on a specific branch.
  */
@@ -140,6 +157,8 @@ export interface DocumentVersion {
     actionType?: string;
     /** Action metadata including puckActions array when structural */
     actionMetadata?: Record<string, unknown>;
+    /** Present when an agent's accepted proposal made this version. */
+    attribution?: VersionAttribution;
 }
 /**
  * Checkpoint types.
@@ -375,6 +394,12 @@ export interface ChangeSummaryEntry {
     authority?: PropAuthority;
     translatable?: boolean;
     structuralKind?: 'added' | 'removed' | 'moved';
+    /**
+     * The upstream version this change was reconciled at. Present only while that
+     * resolution still covers it: a change the upstream source makes again reads as
+     * outstanding once more.
+     */
+    resolvedAtVersion?: number;
 }
 /**
  * Classified summary of how a document has drifted from what it derives from,
@@ -399,8 +424,30 @@ export interface ChangeSummary {
     toVersionId: string;
     /** Id-keyed structural delta */
     slotDelta: unknown;
+    /** Outstanding changes, plus the reconciled ones when they were asked for. */
     changes: ChangeSummaryEntry[];
+    /** Per-classification tally over `changes`. */
     counts: Record<ChangeClassification, number>;
+    /**
+     * How many changes a resolution covers, whether or not they are listed. Absent
+     * from a backend that predates per-change resolutions.
+     */
+    resolvedCount?: number;
+}
+/**
+ * The upstream version each reported change was last reconciled at on this branch,
+ * keyed by slot id then the pointer the change was reported at. A change with no
+ * entry has never been reconciled there.
+ */
+export interface UpstreamResolutions {
+    upstreamResolutions: Record<string, Record<string, number>>;
+}
+/** The reported change a resolution applies to. */
+export interface UpstreamResolutionTarget {
+    /** Slot id of the component the change is on, or '__root__' for a page prop. */
+    slotId: string;
+    /** The change's `propPath`, so settling one change leaves its siblings listed. */
+    propPath: string;
 }
 /**
  * Parameters for creating a document version.
@@ -457,6 +504,8 @@ export interface ActorPresence {
     requestedById?: string;
     /** Display name of the human who triggered this agent session (human_requested sessions only) */
     requestedByName?: string;
+    /** The turn this agent is working on, when it named one. Names what a stop would end. */
+    turnId?: string;
     lastActivityAt: string;
     joinedAt: string;
 }
@@ -632,11 +681,15 @@ export interface AgentEditAbortResult {
 }
 /**
  * Result of stopping an agent (human-initiated).
- * Server looks up the agent's session and performs rollback if needed.
+ * The stop bars the turn from writing again, and rolls back its edit session if it had one.
  */
 export interface AgentStopResult {
     success: boolean;
+    /** The turn that was barred, when the stop named or found one. */
+    stoppedTurnId?: string;
     rolledBack: boolean;
+    /** Why nothing was stopped: 'no_active_turn' when no agent was running. */
+    reason?: string;
     message?: string;
 }
 /**
@@ -773,10 +826,19 @@ export interface WsSyncBaselineMessage {
     serverStateVector: string;
     timestamp: number;
 }
+/**
+ * A comment or thread on this document changed. Carries the thread as it now
+ * stands and the comment involved, so caches can be updated without a refetch.
+ */
+export interface WsThreadEventMessage {
+    type: 'thread_event';
+    event: ThreadEvent;
+    timestamp: number;
+}
 /**
  * Union of all server-to-client WebSocket messages.
  */
-export type WsServerMessage = WsPresenceUpdateMessage | WsFocusRegionBroadcastMessage | WsFocusRegionAckMessage | WsPresenceErrorMessage | WsDeliveryAckMessage | WsPublishResultMessage | WsSyncBaselineMessage;
+export type WsServerMessage = WsPresenceUpdateMessage | WsFocusRegionBroadcastMessage | WsFocusRegionAckMessage | WsPresenceErrorMessage | WsDeliveryAckMessage | WsPublishResultMessage | WsSyncBaselineMessage | WsThreadEventMessage;
 /**
  * Merge conflict resolution strategies (matches backend).
  */
@@ -1199,3 +1261,5 @@ export interface QueryResultsParams {
     includeMetadata?: boolean;
     includeSnapshot?: boolean;
 }
+export type * from './threads/index.js';
+export * from './site-members.js';

package/dist/{types.js → types/index.js}

@@ -6,3 +6,4 @@ export const TERMINAL_MERGE_JOB_STATUSES = [
     'failed',
     'cancelled',
 ];
+export * from './site-members.js';

package/dist/types/site-members.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Site members: the people and agents who can be mentioned on a site.
+ */
+export type SiteMemberRole = 'owner' | 'admin' | 'developer' | 'team_member' | 'author' | 'editor';
+export type AgentSiteRole = 'viewer' | 'editor' | 'admin';
+export interface SiteMemberUser {
+    id: string;
+    /** Null for someone granted access who has never signed in. */
+    name: string | null;
+    email: string | null;
+    role: SiteMemberRole;
+    avatar: string | null;
+}
+export interface SiteMemberAgent {
+    id: string;
+    name: string;
+    role: AgentSiteRole;
+    /** Agents carry no stored image; derive one from the id. */
+    avatar: null;
+    /** True when the agent reaches every site rather than being granted this one. */
+    isGlobal: boolean;
+}
+export interface SiteMembers {
+    members: SiteMemberUser[];
+    agents: SiteMemberAgent[];
+}

package/dist/types/site-members.js

@@ -0,0 +1 @@
+export {};

package/dist/types/threads/agent.d.ts

@@ -0,0 +1,36 @@
+import type { Comment, CommentAuthor } from './comment.js';
+export type ActivityStatus = 'working' | 'done' | 'failed';
+/** `applying` is held while an accept puts the edits into the page; the card still offers the buttons, and the service refuses a second accept while the first is at work. */
+export type ProposalStatus = 'proposed' | 'applying' | 'accepted' | 'dismissed';
+/** What a reader can do to a proposal that is still waiting. */
+export type ProposalDecision = Extract<ProposalStatus, 'accepted' | 'dismissed'>;
+/**
+ * One change to the document, addressed by a dot path into its data
+ * (`content.2.props.title`). `from` is the source path of a `move`.
+ */
+export interface ProposedOperation {
+    op: 'add' | 'remove' | 'replace' | 'move';
+    path: string;
+    value?: unknown;
+    from?: string;
+}
+export interface AgentActivityMetadata {
+    status: ActivityStatus;
+}
+export interface AgentProposalMetadata {
+    status: ProposalStatus;
+    /** One line saying what the operations do, for the card. */
+    summary: string;
+    operations: ProposedOperation[];
+    /** Who accepted or dismissed it, once someone has. */
+    decidedBy?: CommentAuthor;
+    decidedAt?: string;
+    /** When an accept began applying it; gone once it is decided. */
+    claimedAt?: string;
+}
+export type AgentProposalComment = Comment & {
+    kind: 'agent_proposal';
+    metadata: AgentProposalMetadata;
+};
+export declare function isAgentProposal(comment: Comment): comment is AgentProposalComment;
+export declare function isAgentWorking(comment: Comment): boolean;

package/dist/types/threads/agent.js

@@ -0,0 +1,7 @@
+export function isAgentProposal(comment) {
+    return comment.kind === 'agent_proposal' && comment.metadata !== null && 'operations' in comment.metadata;
+}
+export function isAgentWorking(comment) {
+    return comment.kind === 'agent_activity' && comment.metadata !== null && 'status' in comment.metadata
+        && comment.metadata.status === 'working';
+}

package/dist/types/threads/api.d.ts

@@ -0,0 +1,29 @@
+import type { Comment } from './comment.js';
+import type { ThreadContextRef } from './context.js';
+import type { ThreadOverview, ThreadStatus } from './thread.js';
+export interface PostThreadParams {
+    context: ThreadContextRef;
+    /** Required for block and page threads, not allowed on site and workstream threads. */
+    documentId?: string;
+    branchId?: string;
+    body: string;
+}
+export interface PostCommentResult {
+    thread: ThreadOverview;
+    comment: Comment;
+}
+export interface ThreadWithComments {
+    thread: ThreadOverview;
+    comments: Comment[];
+}
+export interface ListThreadsOptions {
+    /** Narrow to one page's threads: one overview per context on that page. */
+    documentId?: string;
+    status?: ThreadStatus | 'all';
+    limit?: number;
+    cursor?: string;
+}
+export interface ThreadListPage {
+    threads: ThreadOverview[];
+    nextCursor: string | null;
+}

package/dist/types/threads/api.js

@@ -0,0 +1 @@
+export {};

package/dist/types/threads/comment.d.ts

@@ -0,0 +1,57 @@
+import type { Principal } from '../index.js';
+import type { AgentActivityMetadata, AgentProposalMetadata } from './agent.js';
+export type CommentAuthorType = Principal['type'];
+/**
+ * Who wrote a comment. Fields match the site members roster so one component
+ * renders both.
+ */
+export interface CommentAuthor {
+    type: CommentAuthorType;
+    id: string;
+    name: string | null;
+    avatar: string | null;
+    /** Present when an agent posted on a user's behalf. */
+    requestedBy?: {
+        id: string;
+        name: string | null;
+    };
+}
+export interface CommentMention {
+    type: CommentAuthorType;
+    id: string;
+    /** Null when the mentioned member has since left the site. */
+    name: string | null;
+}
+/**
+ * What a comment is. A `message` is what a person (or an agent) said; the
+ * agent kinds carry the state of a piece of work in `metadata`.
+ */
+export type CommentKind = 'message' | 'agent_activity' | 'agent_proposal';
+export type CommentMetadata = AgentActivityMetadata | AgentProposalMetadata;
+export interface Comment {
+    id: string;
+    threadId: string;
+    kind: CommentKind;
+    /** Plain text with inline `${mention|user:uuid}` tokens. */
+    body: string;
+    /** Null on a `message`; the work's state on the agent kinds. */
+    metadata: CommentMetadata | null;
+    author: CommentAuthor;
+    mentions: CommentMention[];
+    createdAt: string;
+    editedAt: string | null;
+}
+/** A comment as written or rewritten: its kind decides which metadata it carries. */
+export type CommentContent = {
+    kind: 'message';
+    body: string;
+    metadata?: null;
+} | {
+    kind: 'agent_activity';
+    body: string;
+    metadata: AgentActivityMetadata;
+} | {
+    kind: 'agent_proposal';
+    body: string;
+    metadata: AgentProposalMetadata;
+};

package/dist/types/threads/comment.js

@@ -0,0 +1 @@
+export {};

package/dist/types/threads/context.d.ts

@@ -0,0 +1,9 @@
+/**
+ * What a thread is anchored to. Block and page threads belong to a document;
+ * site and workstream threads do not.
+ */
+export type ThreadContextType = 'block' | 'page' | 'site' | 'workstream';
+export interface ThreadContextRef {
+    type: ThreadContextType;
+    id: string;
+}

package/dist/types/threads/context.js

@@ -0,0 +1 @@
+export {};

package/dist/types/threads/event.d.ts

@@ -0,0 +1,23 @@
+import type { Comment, CommentAuthor } from './comment.js';
+import type { ThreadOverview } from './thread.js';
+/**
+ * Announced by the service after every thread write. The realtime
+ * channel delivers these to other editors; a client applies its own writes
+ * through the same shape.
+ */
+export type ThreadEvent = {
+    type: 'comment_posted';
+    siteId: string;
+    thread: ThreadOverview;
+    comment: Comment;
+} | {
+    type: 'comment_updated';
+    siteId: string;
+    thread: ThreadOverview;
+    comment: Comment;
+} | {
+    type: 'thread_status_changed';
+    siteId: string;
+    thread: ThreadOverview;
+    actor: CommentAuthor;
+};

package/dist/types/threads/event.js

@@ -0,0 +1 @@
+export {};

package/dist/types/threads/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Threads: threads anchored to blocks, pages, sites and workstreams, and the
+ * comments in them.
+ */
+export type * from './api.js';
+export type * from './comment.js';
+export type * from './agent.js';
+export { isAgentProposal, isAgentWorking } from './agent.js';
+export type * from './context.js';
+export type * from './event.js';
+export type * from './thread.js';

package/dist/types/threads/index.js

@@ -0,0 +1 @@
+export { isAgentProposal, isAgentWorking } from './agent.js';

package/dist/types/threads/thread.d.ts

@@ -0,0 +1,22 @@
+import type { CommentAuthor } from './comment.js';
+import type { ThreadContextRef } from './context.js';
+export type ThreadStatus = 'open' | 'resolved';
+/**
+ * A thread without its comments: enough to draw a trigger's count and
+ * resolved state.
+ */
+export interface ThreadOverview {
+    id: string;
+    siteId: string;
+    context: ThreadContextRef;
+    documentId: string | null;
+    /** The branch the thread was opened on, when it has a document. */
+    branchId: string | null;
+    status: ThreadStatus;
+    commentCount: number;
+    lastCommentAt: string;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt: string | null;
+    resolvedBy: CommentAuthor | null;
+}

package/dist/types/threads/thread.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pantheon-systems/css-client",
-  "version": "0.16.0-canary-20260911222513",
+  "version": "0.16.0",
   "description": "TypeScript API client for Pantheon's P1 content platform",
   "publishConfig": {
     "access": "public",