@xpert-ai/xpert-sdk 0.21.0 → 0.23.0

package/dist/artifact-presentation-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Transport-independent viewer envelope for one immutable published Artifact version.
+ * The supplying transport reauthorizes reads/queries; this payload is not a credential.
+ * Render the provider entry in an isolated viewer, never as trusted host application HTML.
+ */
+export interface ArtifactPresentation {
+    /** Envelope protocol version; independent of the published content's versionNumber. */
+    schemaVersion: 1;
+    /** Exact source Artifact/version pair. Never replace versionId with a latest-version lookup. */
+    target: {
+        artifactId: string;
+        versionId: string;
+    };
+    /** Display text only; not a resource identity or type discriminator. */
+    title: string;
+    /** Human-readable release sequence; target.versionId identifies the actual version. */
+    versionNumber: number;
+    /** Source editing is unavailable; authorized read-only interactions may still be exposed. */
+    readOnly: true;
+    /** Provider-supplied viewer document, subject to the host's sandbox and CSP. */
+    entry: {
+        html: string;
+    };
+    /** Client-safe provider state. The domain renderer validates it; generic hosts treat it as opaque. */
+    data: object;
+    /** Allowed read-only operation names; not Agent tools or a grant of upstream data access. */
+    operations: string[];
+    /** Optional ISO 8601 access deadline. Absence does not waive live authorization checks. */
+    expiresAt?: string | null;
+}
+/**
+ * Read-only viewer operation executed through the transport that supplied the presentation.
+ * The server checks the pinned target, operation allowlist and current caller's data permissions.
+ * This is not a request for the Agent's conversational resource_query tool.
+ */
+export interface ArtifactPresentationQuery {
+    /** Copy from the current authorized presentation, without changing its pinned version. */
+    target: ArtifactPresentation['target'];
+    /** Must be declared in that presentation's operations list. */
+    operation: string;
+    /** Domain-specific request body, validated by the provider; carries no identity overrides. */
+    input: object;
+}

package/dist/artifact-presentation-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=artifact-presentation-types.js.map

package/dist/artifact-presentation-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-presentation-types.js","sourceRoot":"","sources":["../src/artifact-presentation-types.ts"],"names":[],"mappings":""}

package/dist/artifact-presentation-types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=artifact-presentation-types.mjs.map

package/dist/artifact-presentation-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-presentation-types.mjs","sourceRoot":"","sources":["../src/artifact-presentation-types.ts"],"names":[],"mappings":""}

package/dist/conversation-resource-types.d.ts

@@ -0,0 +1,10 @@
+/** Stable locator in the current authorized conversation. IDs never carry permissions or change Project scope. */
+export type ConversationResourceTarget = {
+    kind: 'project-content';
+    id: string;
+} | {
+    kind: 'group-reference';
+    id: string;
+};
+/** Host-owned navigation through the target's native authorization adapter; no arbitrary URLs or source Project IDs. */
+export declare const WORKBENCH_RESOURCE_OPEN_COMMAND = "workbench.resource.open";

package/dist/conversation-resource-types.js

@@ -0,0 +1,3 @@
+/** Host-owned navigation through the target's native authorization adapter; no arbitrary URLs or source Project IDs. */
+export const WORKBENCH_RESOURCE_OPEN_COMMAND = 'workbench.resource.open';
+//# sourceMappingURL=conversation-resource-types.js.map

package/dist/conversation-resource-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-resource-types.js","sourceRoot":"","sources":["../src/conversation-resource-types.ts"],"names":[],"mappings":"AAKA,wHAAwH;AACxH,MAAM,CAAC,MAAM,+BAA+B,GAAG,yBAAyB,CAAC"}

package/dist/conversation-resource-types.mjs

@@ -0,0 +1,3 @@
+/** Host-owned navigation through the target's native authorization adapter; no arbitrary URLs or source Project IDs. */
+export const WORKBENCH_RESOURCE_OPEN_COMMAND = 'workbench.resource.open';
+//# sourceMappingURL=conversation-resource-types.mjs.map

package/dist/conversation-resource-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-resource-types.mjs","sourceRoot":"","sources":["../src/conversation-resource-types.ts"],"names":[],"mappings":"AAKA,wHAAwH;AACxH,MAAM,CAAC,MAAM,+BAA+B,GAAG,yBAAyB,CAAC"}

package/dist/group-artifact-types.d.ts

@@ -0,0 +1,95 @@
+import type { ArtifactPresentation, ArtifactPresentationQuery } from './artifact-presentation-types.js';
+import type { ResourceAnalysisPolicy } from './resource-analysis-types.js';
+/**
+ * Client-safe grant metadata for fixed published content and one receiving group/Project.
+ * Contains no credentials or source file access. Status and expiry are display hints;
+ * every operation must still be authorized by the server.
+ */
+export interface GroupArtifactGrant {
+    /** Grant identity, distinct from the reference created when the owner accepts it. */
+    id: string;
+    /** Original Artifact in the authoring Project; no copy is created in the group Project. */
+    artifactId: string;
+    /** Pinned published version ID, unrelated to a draft revision. */
+    versionId: string;
+    /** Project retaining source ownership and authoring permissions. */
+    ownerProjectId: string;
+    /** Receiving group's Project captured when the grant was offered. */
+    targetProjectId: string;
+    /** Receiving audience; another group in the same Project has no implied access. */
+    targetGroupId: string;
+    /** Read-only use of the resource, without automatic upstream data access. */
+    permission: 'read';
+    /** Proposed scope on an offer, accepted scope when active; absent/null means view-only. */
+    analysis?: ResourceAnalysisPolicy | null;
+    /** Lifecycle state; expiry or changed membership can also make a grant unusable. */
+    status: 'offered' | 'active' | 'revoked' | 'removed';
+    /** Grant concurrency token for acceptance; do not substitute a reference revision. */
+    revision: number;
+    /** ISO 8601 access deadline serialized by the host. */
+    expiresAt: string;
+    /** Display label, not an identity or permission discriminator. */
+    title: string;
+    /** Display sequence; versionId identifies the published version. */
+    versionNumber: number;
+}
+/**
+ * Accepted placement of a source Artifact's fixed version in one group's runtime Project.
+ * Keep ownerProjectId and runtimeProjectId separate; opening never switches to the source Project.
+ * The placement grants neither source membership nor access to other groups' references.
+ */
+export interface GroupArtifactReference {
+    /** Reference ID used for group read, query, remove and navigation operations. */
+    id: string;
+    /** Backing authorization, whose live status is checked on each operation. */
+    grantId: string;
+    /** Source Artifact identity, not a copied group Artifact. */
+    artifactId: string;
+    /** Fixed published version ID; source publication never silently advances this reference. */
+    versionId: string;
+    /** Project retaining authoring authority. */
+    ownerProjectId: string;
+    /** Receiving Project, which must still match the group's current binding. */
+    runtimeProjectId: string;
+    /** Group audience owning this placement. */
+    groupId: string;
+    /** Stored display title; never resolve resource identity from it. */
+    title: string;
+    /** Reference concurrency token for removal, independent of the grant revision. */
+    revision: number;
+    /** Human-readable release sequence; use versionId for identity. */
+    versionNumber: number;
+    /** Backing grant's ISO 8601 deadline; a cached reference can still be revoked earlier. */
+    expiresAt: string;
+    /** No source editing through this placement; permitted analysis is described separately. */
+    readOnly: true;
+    /** Effective analysis scope explicitly accepted by the owner; absent/null is view-only. */
+    analysis?: ResourceAnalysisPolicy | null;
+    /** Authenticated library-view URL, not a public share link or authorization bypass. */
+    url: string;
+}
+/** Compatibility name for presentations obtained through the group API. */
+export type GroupArtifactPresentation = ArtifactPresentation;
+/** Authorized viewer payload and revalidated placement for subsequent group-scoped requests. */
+export interface GroupArtifactView {
+    /** Placement reauthorized when this view was read; later operations must recheck access. */
+    reference: GroupArtifactReference;
+    /** Placement display title. */
+    title: string;
+    /** Placement revision, not a published version number or grant revision. */
+    revision: number;
+    /** Explicit content discriminator; render through the generic isolated presentation host. */
+    content: {
+        kind: 'presentation';
+        presentation: ArtifactPresentation;
+    };
+}
+/** Compatibility name for queries sent through the group API. */
+export type GroupArtifactQuery = ArtifactPresentationQuery;
+/** Server-paginated offers or references after audience/access filtering. */
+export interface GroupArtifactPage<T> {
+    /** Visible items in this page; an empty page alone does not imply pagination is complete. */
+    items: T[];
+    /** Pass as the next offset; null means no further page. Do not derive it from items.length. */
+    nextOffset: number | null;
+}

package/dist/group-artifact-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=group-artifact-types.js.map

package/dist/group-artifact-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-artifact-types.js","sourceRoot":"","sources":["../src/group-artifact-types.ts"],"names":[],"mappings":""}

package/dist/group-artifact-types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=group-artifact-types.mjs.map

package/dist/group-artifact-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-artifact-types.mjs","sourceRoot":"","sources":["../src/group-artifact-types.ts"],"names":[],"mappings":""}

package/dist/group-artifacts.d.ts

@@ -0,0 +1,42 @@
+import type { GroupTransport, GroupRequestOptions } from './groups.js';
+import type { GroupArtifactGrant, GroupArtifactPage, GroupArtifactReference, GroupArtifactView, GroupArtifactQuery } from './group-artifact-types.js';
+/**
+ * Receiving-group API exposed as client.groups.artifacts, using its existing auth/refresh transport.
+ * The server enforces owner-only acceptance/removal and live access on every read/query.
+ * Source-side offering and revocation require the separate authenticated authoring host.
+ */
+export declare class GroupArtifactsClient {
+    private readonly transport;
+    constructor(transport: GroupTransport);
+    private path;
+    /** List pending offers for owner review; an offer is not yet an accepted resource. */
+    offers(groupId: string, page?: {
+        offset?: number;
+        limit?: number;
+    }, options?: GroupRequestOptions): Promise<GroupArtifactPage<GroupArtifactGrant>>;
+    /** List accessible, accepted references for this group and its current Project. */
+    list(groupId: string, page?: {
+        offset?: number;
+        limit?: number;
+    }, options?: GroupRequestOptions): Promise<GroupArtifactPage<GroupArtifactReference>>;
+    /** Accept an offer as group owner, creating a fixed-version reference without changing ownership. */
+    accept(groupId: string, input: {
+        /** Identity returned by offers(), not an Artifact or reference ID. */
+        grantId: string;
+        /** Grant revision observed by the owner; stale acceptance must not overwrite newer consent. */
+        expectedRevision: number;
+        /** Explicitly accept the offered analysis scope. Omitted/false accepts viewing only. */
+        acceptAnalysis?: boolean;
+    }, options?: GroupRequestOptions): Promise<GroupArtifactReference>;
+    /** Reauthorize a reference and load its published presentation; this does not open a UI itself. */
+    read(groupId: string, referenceId: string, options?: GroupRequestOptions): Promise<GroupArtifactView>;
+    /** Execute an allowed viewer operation under the current caller; not the Agent analysis API. */
+    query(groupId: string, referenceId: string, input: GroupArtifactQuery, options?: GroupRequestOptions): Promise<object>;
+    /** Remove this group's placement as owner. Source content remains; reattachment needs a new grant. */
+    remove(groupId: string, referenceId: string, input: {
+        /** Reference revision returned by list/read, not the backing grant's revision. */
+        expectedRevision: number;
+    }, options?: GroupRequestOptions): Promise<{
+        removed: boolean;
+    }>;
+}

package/dist/group-artifacts.js

@@ -0,0 +1,43 @@
+/**
+ * Receiving-group API exposed as client.groups.artifacts, using its existing auth/refresh transport.
+ * The server enforces owner-only acceptance/removal and live access on every read/query.
+ * Source-side offering and revocation require the separate authenticated authoring host.
+ */
+export class GroupArtifactsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    path(groupId, suffix) {
+        return `/groups/${encodeURIComponent(groupId)}/artifacts/${suffix}`;
+    }
+    /** List pending offers for owner review; an offer is not yet an accepted resource. */
+    offers(groupId, page = {}, options) {
+        return this.transport.json(this.path(groupId, 'offers'), { ...options, params: page });
+    }
+    /** List accessible, accepted references for this group and its current Project. */
+    list(groupId, page = {}, options) {
+        return this.transport.json(this.path(groupId, 'references'), { ...options, params: page });
+    }
+    /** Accept an offer as group owner, creating a fixed-version reference without changing ownership. */
+    accept(groupId, input, options) {
+        return this.transport.json(this.path(groupId, 'references'), {
+            ...options,
+            method: 'POST',
+            json: input,
+        });
+    }
+    /** Reauthorize a reference and load its published presentation; this does not open a UI itself. */
+    read(groupId, referenceId, options) {
+        return this.transport.json(this.path(groupId, `references/${encodeURIComponent(referenceId)}`), options);
+    }
+    /** Execute an allowed viewer operation under the current caller; not the Agent analysis API. */
+    query(groupId, referenceId, input, options) {
+        return this.transport.json(this.path(groupId, `references/${encodeURIComponent(referenceId)}/query`), { ...options, method: 'POST', json: input });
+    }
+    /** Remove this group's placement as owner. Source content remains; reattachment needs a new grant. */
+    remove(groupId, referenceId, input, options) {
+        return this.transport.json(this.path(groupId, `references/${encodeURIComponent(referenceId)}/remove`), { ...options, method: 'POST', json: input });
+    }
+}
+//# sourceMappingURL=group-artifacts.js.map

package/dist/group-artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-artifacts.js","sourceRoot":"","sources":["../src/group-artifacts.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,SAAyB;QAAzB,cAAS,GAAT,SAAS,CAAgB;IAAG,CAAC;IAClD,IAAI,CAAC,OAAe,EAAE,MAAc;QAC1C,OAAO,WAAW,kBAAkB,CAAC,OAAO,CAAC,cAAc,MAAM,EAAE,CAAC;IACtE,CAAC;IACD,sFAAsF;IACtF,MAAM,CACJ,OAAe,EACf,OAA4C,EAAE,EAC9C,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,mFAAmF;IACnF,IAAI,CACF,OAAe,EACf,OAA4C,EAAE,EAC9C,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,qGAAqG;IACrG,MAAM,CACJ,OAAe,EACf,KAOC,EACD,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE;YAC3D,GAAG,OAAO;YACV,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IACD,mGAAmG;IACnG,IAAI,CACF,OAAe,EACf,WAAmB,EACnB,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CACxB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC,EACnE,OAAO,CACR,CAAC;IACJ,CAAC;IACD,gGAAgG;IAChG,KAAK,CACH,OAAe,EACf,WAAmB,EACnB,KAAyB,EACzB,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CACxB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,WAAW,CAAC,QAAQ,CAAC,EACzE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAC5C,CAAC;IACJ,CAAC;IACD,sGAAsG;IACtG,MAAM,CACJ,OAAe,EACf,WAAmB,EACnB,KAGC,EACD,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CACxB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,WAAW,CAAC,SAAS,CAAC,EAC1E,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAC5C,CAAC;IACJ,CAAC;CACF"}

package/dist/group-artifacts.mjs

@@ -0,0 +1,43 @@
+/**
+ * Receiving-group API exposed as client.groups.artifacts, using its existing auth/refresh transport.
+ * The server enforces owner-only acceptance/removal and live access on every read/query.
+ * Source-side offering and revocation require the separate authenticated authoring host.
+ */
+export class GroupArtifactsClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    path(groupId, suffix) {
+        return `/groups/${encodeURIComponent(groupId)}/artifacts/${suffix}`;
+    }
+    /** List pending offers for owner review; an offer is not yet an accepted resource. */
+    offers(groupId, page = {}, options) {
+        return this.transport.json(this.path(groupId, 'offers'), { ...options, params: page });
+    }
+    /** List accessible, accepted references for this group and its current Project. */
+    list(groupId, page = {}, options) {
+        return this.transport.json(this.path(groupId, 'references'), { ...options, params: page });
+    }
+    /** Accept an offer as group owner, creating a fixed-version reference without changing ownership. */
+    accept(groupId, input, options) {
+        return this.transport.json(this.path(groupId, 'references'), {
+            ...options,
+            method: 'POST',
+            json: input,
+        });
+    }
+    /** Reauthorize a reference and load its published presentation; this does not open a UI itself. */
+    read(groupId, referenceId, options) {
+        return this.transport.json(this.path(groupId, `references/${encodeURIComponent(referenceId)}`), options);
+    }
+    /** Execute an allowed viewer operation under the current caller; not the Agent analysis API. */
+    query(groupId, referenceId, input, options) {
+        return this.transport.json(this.path(groupId, `references/${encodeURIComponent(referenceId)}/query`), { ...options, method: 'POST', json: input });
+    }
+    /** Remove this group's placement as owner. Source content remains; reattachment needs a new grant. */
+    remove(groupId, referenceId, input, options) {
+        return this.transport.json(this.path(groupId, `references/${encodeURIComponent(referenceId)}/remove`), { ...options, method: 'POST', json: input });
+    }
+}
+//# sourceMappingURL=group-artifacts.mjs.map

package/dist/group-artifacts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-artifacts.mjs","sourceRoot":"","sources":["../src/group-artifacts.ts"],"names":[],"mappings":"AASA;;;;GAIG;AACH,MAAM,OAAO,oBAAoB;IACF;IAA7B,YAA6B,SAAyB;QAAzB,cAAS,GAAT,SAAS,CAAgB;IAAG,CAAC;IAClD,IAAI,CAAC,OAAe,EAAE,MAAc;QAC1C,OAAO,WAAW,kBAAkB,CAAC,OAAO,CAAC,cAAc,MAAM,EAAE,CAAC;IACtE,CAAC;IACD,sFAAsF;IACtF,MAAM,CACJ,OAAe,EACf,OAA4C,EAAE,EAC9C,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,mFAAmF;IACnF,IAAI,CACF,OAAe,EACf,OAA4C,EAAE,EAC9C,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7F,CAAC;IACD,qGAAqG;IACrG,MAAM,CACJ,OAAe,EACf,KAOC,EACD,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE;YAC3D,GAAG,OAAO;YACV,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;IACL,CAAC;IACD,mGAAmG;IACnG,IAAI,CACF,OAAe,EACf,WAAmB,EACnB,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CACxB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,WAAW,CAAC,EAAE,CAAC,EACnE,OAAO,CACR,CAAC;IACJ,CAAC;IACD,gGAAgG;IAChG,KAAK,CACH,OAAe,EACf,WAAmB,EACnB,KAAyB,EACzB,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CACxB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,WAAW,CAAC,QAAQ,CAAC,EACzE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAC5C,CAAC;IACJ,CAAC;IACD,sGAAsG;IACtG,MAAM,CACJ,OAAe,EACf,WAAmB,EACnB,KAGC,EACD,OAA6B;QAE7B,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CACxB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,kBAAkB,CAAC,WAAW,CAAC,SAAS,CAAC,EAC1E,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAC5C,CAAC;IACJ,CAAC;CACF"}

package/dist/group-resource-links.d.ts

@@ -0,0 +1,34 @@
+import type { ChatGroupEvent, ChatGroupMessage, ChatGroupResourceLink, ChatGroupResourceOpenRequest, ChatGroupSnapshot } from './group-types.js';
+type LegacyResourceLink = Pick<ChatGroupResourceLink, 'projectId' | 'title'> & ({
+    kind?: 'group-reference';
+    referenceId: string;
+} | {
+    kind: 'project-content';
+    contentId: string;
+});
+export type GroupResourceLinkWire = ChatGroupResourceLink | LegacyResourceLink;
+export type GroupMessageWire = Omit<ChatGroupMessage, 'communication'> & {
+    communication: Omit<ChatGroupMessage['communication'], 'resourceLinks'> & {
+        resourceLinks?: GroupResourceLinkWire[];
+    };
+};
+export type GroupSnapshotWire = Omit<ChatGroupSnapshot, 'messages'> & {
+    messages: GroupMessageWire[];
+};
+export type GroupEventWire = Exclude<ChatGroupEvent, {
+    type: 'snapshot' | 'resource_open';
+}> | {
+    type: 'snapshot';
+    snapshot: GroupSnapshotWire;
+} | {
+    type: 'resource_open';
+    request: GroupResourceLinkWire & Pick<ChatGroupResourceOpenRequest, 'requestId' | 'clientMessageId'>;
+};
+export declare function isResourceUuid(value: unknown): value is string;
+/** Reject ambiguous locators instead of choosing between old and new identities. */
+export declare function parseGroupResourceLink(value: unknown): ChatGroupResourceLink | null;
+export declare function isGroupResourceLinkWire(value: unknown): value is GroupResourceLinkWire;
+export declare function isCanonicalResourceLink(value: GroupResourceLinkWire): value is ChatGroupResourceLink;
+export declare function normalizeGroupMessage(message: GroupMessageWire): ChatGroupMessage;
+export declare function normalizeGroupSnapshot(snapshot: GroupSnapshotWire): ChatGroupSnapshot;
+export {};

package/dist/group-resource-links.js

@@ -0,0 +1,71 @@
+export function isResourceUuid(value) {
+    return (typeof value === 'string' &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value));
+}
+/** Reject ambiguous locators instead of choosing between old and new identities. */
+export function parseGroupResourceLink(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !('projectId' in value) ||
+        !isResourceUuid(value.projectId) ||
+        !('title' in value) ||
+        typeof value.title !== 'string' ||
+        value.title.length > 200)
+        return null;
+    const base = { projectId: value.projectId, title: value.title };
+    if ('resource' in value) {
+        if ('kind' in value || 'referenceId' in value || 'contentId' in value)
+            return null;
+        const resource = value.resource;
+        if (!resource ||
+            typeof resource !== 'object' ||
+            !('kind' in resource) ||
+            !('id' in resource) ||
+            !isResourceUuid(resource.id) ||
+            (resource.kind !== 'group-reference' && resource.kind !== 'project-content') ||
+            Object.keys(resource).some((key) => key !== 'kind' && key !== 'id'))
+            return null;
+        return { ...base, resource: { kind: resource.kind, id: resource.id } };
+    }
+    if ((!('kind' in value) || value.kind === 'group-reference') &&
+        'referenceId' in value &&
+        isResourceUuid(value.referenceId) &&
+        !('contentId' in value))
+        return { ...base, resource: { kind: 'group-reference', id: value.referenceId } };
+    if ('kind' in value &&
+        value.kind === 'project-content' &&
+        'contentId' in value &&
+        isResourceUuid(value.contentId) &&
+        !('referenceId' in value))
+        return { ...base, resource: { kind: 'project-content', id: value.contentId } };
+    return null;
+}
+export function isGroupResourceLinkWire(value) {
+    return parseGroupResourceLink(value) !== null;
+}
+export function isCanonicalResourceLink(value) {
+    return 'resource' in value;
+}
+export function normalizeGroupMessage(message) {
+    const { resourceLinks, ...communication } = message.communication;
+    if (resourceLinks === undefined)
+        return { ...message, communication };
+    if (!Array.isArray(resourceLinks))
+        throw new Error('Invalid group resource links');
+    return {
+        ...message,
+        communication: {
+            ...communication,
+            resourceLinks: resourceLinks.map((link) => {
+                const parsed = parseGroupResourceLink(link);
+                if (!parsed)
+                    throw new Error('Invalid group resource link');
+                return parsed;
+            }),
+        },
+    };
+}
+export function normalizeGroupSnapshot(snapshot) {
+    return { ...snapshot, messages: snapshot.messages.map(normalizeGroupMessage) };
+}
+//# sourceMappingURL=group-resource-links.js.map

package/dist/group-resource-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-resource-links.js","sourceRoot":"","sources":["../src/group-resource-links.ts"],"names":[],"mappings":"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"}

package/dist/group-resource-links.mjs

@@ -0,0 +1,71 @@
+export function isResourceUuid(value) {
+    return (typeof value === 'string' &&
+        /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value));
+}
+/** Reject ambiguous locators instead of choosing between old and new identities. */
+export function parseGroupResourceLink(value) {
+    if (!value ||
+        typeof value !== 'object' ||
+        !('projectId' in value) ||
+        !isResourceUuid(value.projectId) ||
+        !('title' in value) ||
+        typeof value.title !== 'string' ||
+        value.title.length > 200)
+        return null;
+    const base = { projectId: value.projectId, title: value.title };
+    if ('resource' in value) {
+        if ('kind' in value || 'referenceId' in value || 'contentId' in value)
+            return null;
+        const resource = value.resource;
+        if (!resource ||
+            typeof resource !== 'object' ||
+            !('kind' in resource) ||
+            !('id' in resource) ||
+            !isResourceUuid(resource.id) ||
+            (resource.kind !== 'group-reference' && resource.kind !== 'project-content') ||
+            Object.keys(resource).some((key) => key !== 'kind' && key !== 'id'))
+            return null;
+        return { ...base, resource: { kind: resource.kind, id: resource.id } };
+    }
+    if ((!('kind' in value) || value.kind === 'group-reference') &&
+        'referenceId' in value &&
+        isResourceUuid(value.referenceId) &&
+        !('contentId' in value))
+        return { ...base, resource: { kind: 'group-reference', id: value.referenceId } };
+    if ('kind' in value &&
+        value.kind === 'project-content' &&
+        'contentId' in value &&
+        isResourceUuid(value.contentId) &&
+        !('referenceId' in value))
+        return { ...base, resource: { kind: 'project-content', id: value.contentId } };
+    return null;
+}
+export function isGroupResourceLinkWire(value) {
+    return parseGroupResourceLink(value) !== null;
+}
+export function isCanonicalResourceLink(value) {
+    return 'resource' in value;
+}
+export function normalizeGroupMessage(message) {
+    const { resourceLinks, ...communication } = message.communication;
+    if (resourceLinks === undefined)
+        return { ...message, communication };
+    if (!Array.isArray(resourceLinks))
+        throw new Error('Invalid group resource links');
+    return {
+        ...message,
+        communication: {
+            ...communication,
+            resourceLinks: resourceLinks.map((link) => {
+                const parsed = parseGroupResourceLink(link);
+                if (!parsed)
+                    throw new Error('Invalid group resource link');
+                return parsed;
+            }),
+        },
+    };
+}
+export function normalizeGroupSnapshot(snapshot) {
+    return { ...snapshot, messages: snapshot.messages.map(normalizeGroupMessage) };
+}
+//# sourceMappingURL=group-resource-links.mjs.map

package/dist/group-resource-links.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-resource-links.mjs","sourceRoot":"","sources":["../src/group-resource-links.ts"],"names":[],"mappings":"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"}

package/dist/group-types.d.ts

@@ -1,9 +1,16 @@
+import type { ConversationResourceTarget } from './conversation-resource-types.js';
 import type { ChatMessage } from './schema.js';
 import type { XpertProjectTypeRef } from './schema.js';
 import type { RuntimeCapabilitiesSelection } from './schema.js';
 import type { RuntimeResourcesSelection } from './runtime-resources.js';
 /** Snapshots expose public messages; runtime details require workspace read access. */
 export type ChatGroupIntent = 'request' | 'reply' | 'message';
+/**
+ * Completion intent for one sender's answer to one request, independent of delivery/run status.
+ * Progress is a partial answer and does not wake the requester; final completes the answer only
+ * after successful publication. Neither stage accepts or completes a Project task.
+ */
+export type ChatGroupReplyStage = 'progress' | 'final';
 export type ChatGroupDeliveryStatus = 'pending' | 'starting' | 'steering' | 'consumed' | 'blocked' | 'canceled' | 'failed';
 export interface ChatGroupParticipant {
     id: string;
@@ -40,7 +47,42 @@ export interface ChatGroupComposerInput {
     runtimeResources?: RuntimeResourcesSelection;
     runtimeCapabilities?: RuntimeCapabilitiesSelection;
 }
+/**
+ * Server-authored clickable entry persisted in message history, not an open-on-load instruction.
+ * Clicking reauthorizes the resource through the current conversation's host adapter.
+ */
+export interface ChatGroupResourceLink {
+    /** Canonical locator shared with discovery and Workbench. Contains no access grant. */
+    resource: ConversationResourceTarget;
+    /** Receiving group's runtime Project; checked before opening, never a source Project override. */
+    projectId: string;
+    /** Display label only; never use it to infer resource identity or type. */
+    title: string;
+}
+/** Live, requester-addressed navigation event; consumers match the local send and deduplicate it. */
+export interface ChatGroupResourceOpenRequest extends ChatGroupResourceLink {
+    /** Server-generated deduplication ID; do not open the same request twice. */
+    requestId: string;
+    /** Initiating client message correlation ID, or server message ID fallback. */
+    clientMessageId: string;
+}
 export interface ChatGroupCommunication {
+    /** Inert resource entries, including during history playback; these alone never auto-open. */
+    resourceLinks?: ChatGroupResourceLink[];
+    /**
+     * Server-authored routing metadata used to derive a fresh, audience-scoped resource_open event.
+     * Renderers must not treat replayed communication metadata as a new navigation request.
+     */
+    resourceNavigation?: {
+        /** Navigation deduplication ID propagated to ChatGroupResourceOpenRequest. */
+        requestId: string;
+        /** Server emission time in Unix epoch milliseconds for freshness checks. */
+        issuedAt: number;
+        /** Initiating client message ID, with server message ID as fallback. */
+        clientMessageId: string;
+        /** Intended viewer's group membership ID, not an account or Assistant ID. */
+        participantId: string;
+    };
     /** Host-owned task context, unavailable in group send inputs. */
     projectTask?: {
         invocationId: string;
@@ -62,6 +104,12 @@ export interface ChatGroupCommunication {
     senderId: string;
     recipientIds: string[];
     replyToMessageId?: string;
+    /**
+     * Only valid on replies. Missing on legacy replies means final; new publications include it.
+     * A successfully published final tool reply suppresses the automatic final answer for the same
+     * request and sender. Progress, message and request publications do not suppress that answer.
+     */
+    replyStage?: ChatGroupReplyStage;
     causedByMessageId?: string;
     rootMessageId: string;
     rootUserId: string;
@@ -72,6 +120,19 @@ export interface ChatGroupMessage {
     clientMessageId: string;
     sequence: number;
     text: string;
+    /**
+     * Optional server-filtered result snapshots. May be present with empty text.
+     * IDs are stable within this public message; repeated snapshots replace rather than append blocks.
+     * Known forms use existing ChatKit `resource_card` or `component` (Widget / McpApp) payloads.
+     * Payloads stay opaque at this transport boundary: renderers must validate the concrete type,
+     * ignore unknown forms and never reconnect a copied MCP result to the originating App session.
+     * These blocks confer no resource permissions, do not wake recipients and do not complete replies.
+     */
+    display?: {
+        id: string;
+        type: 'component' | 'resource_card';
+        data: unknown;
+    }[];
     createdAt: string;
     communication: ChatGroupCommunication;
     runtimeParticipantIds?: string[];
@@ -153,6 +214,9 @@ export interface ChatGroupRun {
     status: 'busy' | 'pausing' | 'paused' | 'interrupted' | 'idle' | 'error';
 }
 export type ChatGroupEvent = {
+    type: 'resource_open';
+    request: ChatGroupResourceOpenRequest;
+} | {
     type: 'snapshot';
     snapshot: ChatGroupSnapshot;
 } | {