@treeseed/sdk 0.13.0-rc.53 → 0.13.0-rc.55

package/dist/operator-contracts/catalog/communication-operations.d.ts

@@ -4,22 +4,25 @@ export declare function communicationOperations(): {
         channel: string;
     }, {}, {
         message: string;
-        projectId: string;
         timeoutSeconds?: number | undefined;
         recipients?: string[] | undefined;
     }, {
+        teamId: string;
+        sendId: string;
+        schemaVersion: "treeseed.communication-send-receipt/v4";
         status: "failed" | "running" | "partial" | "complete" | "queued";
-        schemaVersion: "treeseed.communication-send-receipt/v2";
+        createdAt: string;
         targets: {
+            invocationId: string | null;
             status: "failed" | "running" | "cancelled" | "queued" | "responded" | "abstained";
             projectId: string;
             completedAt: string | null;
             agentSlug: string;
             capacity: {
+                assignmentId: string | null;
                 status: string | null;
                 completedAt: string | null;
                 providerId: string | null;
-                assignmentId: string | null;
                 executionProviderId: string | null;
                 laneId: string | null;
                 lanePurpose: string | null;
@@ -28,6 +31,27 @@ export declare function communicationOperations(): {
                 returnedAt: string | null;
                 failedAt: string | null;
             };
+            diagnostics: {
+                resources: Record<string, unknown>;
+                reason: string | null;
+                provider: {
+                    providerId: string | null;
+                    executionProviderId: string | null;
+                    runtimeVersion: string | null;
+                };
+                selection: {
+                    parameters: Record<string, unknown>;
+                    capabilities: string[];
+                    model: string | null;
+                };
+                usage: Record<string, unknown>[];
+                availability: "available" | "unavailable" | "partial";
+                identityManifest: Record<string, unknown>;
+                contextManifest: Record<string, unknown>[];
+                timing: Record<string, unknown>;
+                traceEvents: Record<string, unknown>[];
+                fullPayload?: Record<string, unknown> | undefined;
+            };
             projectSlug: string;
             definitionRevision: string;
             revisions: {
@@ -36,7 +60,6 @@ export declare function communicationOperations(): {
                 agentDefinition: string;
                 chatProfile: string;
             };
-            invocationId: string | null;
             requirement: "required" | "optional";
             parentInvocationId: string | null;
             depth: number;
@@ -46,53 +69,77 @@ export declare function communicationOperations(): {
                 code: string;
                 message: string | null;
             } | null;
+            acknowledgedAt: string | null;
+            leaseAcceptedAt: string | null;
         }[];
-        createdAt: string;
         responses: {
+            invocationId: string;
+            assignmentId: string | null;
             status: "failed" | "cancelled" | "responded" | "abstained";
-            projectId: string;
             createdAt: string;
+            projectId: string;
             agentSlug: string;
-            assignmentId: string | null;
-            invocationId: string;
+            projectSlug: string;
             requirement: "required" | "optional";
             messageRef: string;
             markdown: string;
         }[];
-        teamId: string;
         channel: string;
-        updatedAt: string;
-        messageRef: string;
-        sendId: string;
         topic: {
             id: string;
             slug: string;
         };
-        projectStream: {
+        events: {
+            teamId: string;
+            topicId: string;
+            sendId: string | null;
+            invocationId: string | null;
+            assignmentId: string | null;
+            sequence: number;
+            type: "message.posted" | "mention.acknowledged" | "response_lease.accepted" | "agent.progress" | "agent.response" | "agent.abstained" | "agent.failed";
+            payload: Record<string, unknown>;
+            id: string;
+            actor: {
+                kind: "control-plane" | "provider" | "agent" | "user";
+                id: string;
+                handle: string | null;
+            };
+            summary: string;
+            channel: string;
+            occurredAt: string;
+        }[];
+        updatedAt: string;
+        projectStreams: {
             id: string;
             projectId: string;
             projectSlug: string;
-        };
-        discussionId: string;
-        sourceMessage: string;
+            messageRef: string;
+            discussionId: string;
+        }[];
         replayed: boolean;
     }>;
     sendStatus: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
         teamId: string;
         sendId: string;
-    }, {}, undefined, {
+    }, {
+        diagnostics?: "metadata" | "full" | undefined;
+    }, undefined, {
+        teamId: string;
+        sendId: string;
+        schemaVersion: "treeseed.communication-send-receipt/v4";
         status: "failed" | "running" | "partial" | "complete" | "queued";
-        schemaVersion: "treeseed.communication-send-receipt/v2";
+        createdAt: string;
         targets: {
+            invocationId: string | null;
             status: "failed" | "running" | "cancelled" | "queued" | "responded" | "abstained";
             projectId: string;
             completedAt: string | null;
             agentSlug: string;
             capacity: {
+                assignmentId: string | null;
                 status: string | null;
                 completedAt: string | null;
                 providerId: string | null;
-                assignmentId: string | null;
                 executionProviderId: string | null;
                 laneId: string | null;
                 lanePurpose: string | null;
@@ -101,6 +148,27 @@ export declare function communicationOperations(): {
                 returnedAt: string | null;
                 failedAt: string | null;
             };
+            diagnostics: {
+                resources: Record<string, unknown>;
+                reason: string | null;
+                provider: {
+                    providerId: string | null;
+                    executionProviderId: string | null;
+                    runtimeVersion: string | null;
+                };
+                selection: {
+                    parameters: Record<string, unknown>;
+                    capabilities: string[];
+                    model: string | null;
+                };
+                usage: Record<string, unknown>[];
+                availability: "available" | "unavailable" | "partial";
+                identityManifest: Record<string, unknown>;
+                contextManifest: Record<string, unknown>[];
+                timing: Record<string, unknown>;
+                traceEvents: Record<string, unknown>[];
+                fullPayload?: Record<string, unknown> | undefined;
+            };
             projectSlug: string;
             definitionRevision: string;
             revisions: {
@@ -109,7 +177,6 @@ export declare function communicationOperations(): {
                 agentDefinition: string;
                 chatProfile: string;
             };
-            invocationId: string | null;
             requirement: "required" | "optional";
             parentInvocationId: string | null;
             depth: number;
@@ -119,52 +186,252 @@ export declare function communicationOperations(): {
                 code: string;
                 message: string | null;
             } | null;
+            acknowledgedAt: string | null;
+            leaseAcceptedAt: string | null;
         }[];
-        createdAt: string;
         responses: {
+            invocationId: string;
+            assignmentId: string | null;
             status: "failed" | "cancelled" | "responded" | "abstained";
-            projectId: string;
             createdAt: string;
+            projectId: string;
             agentSlug: string;
-            assignmentId: string | null;
-            invocationId: string;
+            projectSlug: string;
             requirement: "required" | "optional";
             messageRef: string;
             markdown: string;
         }[];
+        channel: string;
+        topic: {
+            id: string;
+            slug: string;
+        };
+        events: {
+            teamId: string;
+            topicId: string;
+            sendId: string | null;
+            invocationId: string | null;
+            assignmentId: string | null;
+            sequence: number;
+            type: "message.posted" | "mention.acknowledged" | "response_lease.accepted" | "agent.progress" | "agent.response" | "agent.abstained" | "agent.failed";
+            payload: Record<string, unknown>;
+            id: string;
+            actor: {
+                kind: "control-plane" | "provider" | "agent" | "user";
+                id: string;
+                handle: string | null;
+            };
+            summary: string;
+            channel: string;
+            occurredAt: string;
+        }[];
+        updatedAt: string;
+        projectStreams: {
+            id: string;
+            projectId: string;
+            projectSlug: string;
+            messageRef: string;
+            discussionId: string;
+        }[];
+        replayed: boolean;
+    }>;
+    topicsList: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+    }, {
+        status?: "active" | "archived" | undefined;
+        cursor?: string | undefined;
+        limit?: number | undefined;
+    }, undefined, {
+        items: {
+            teamId: string;
+            status: "active" | "archived";
+            createdAt: string;
+            id: string;
+            updatedAt: string;
+            slug: string;
+            streams: {
+                id: string;
+                projectId: string;
+                projectSlug: string;
+                discussionId: string;
+            }[];
+            listeners: {
+                status: "active" | "removed";
+                projectId: string;
+                source: "operator" | "seed" | "mention";
+                agentSlug: string;
+                projectSlug: string;
+                updatedAt: string;
+                agentHandle: string;
+                subscribedAt: string;
+            }[];
+        }[];
+        cursor: string | null;
+    }>;
+    topicsShow: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
         teamId: string;
         channel: string;
+    }, {}, undefined, {
+        teamId: string;
+        status: "active" | "archived";
+        createdAt: string;
+        id: string;
         updatedAt: string;
-        messageRef: string;
-        sendId: string;
+        slug: string;
+        streams: {
+            id: string;
+            projectId: string;
+            projectSlug: string;
+            discussionId: string;
+        }[];
+        listeners: {
+            status: "active" | "removed";
+            projectId: string;
+            source: "operator" | "seed" | "mention";
+            agentSlug: string;
+            projectSlug: string;
+            updatedAt: string;
+            agentHandle: string;
+            subscribedAt: string;
+        }[];
+    }>;
+    topicsTimeline: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        channel: string;
+    }, {
+        limit?: number | undefined;
+        diagnostics?: "metadata" | "full" | undefined;
+        after?: string | undefined;
+        waitSeconds?: number | undefined;
+    }, undefined, {
+        cursor: string | null;
         topic: {
+            teamId: string;
+            status: "active" | "archived";
+            createdAt: string;
             id: string;
+            updatedAt: string;
             slug: string;
+            streams: {
+                id: string;
+                projectId: string;
+                projectSlug: string;
+                discussionId: string;
+            }[];
+            listeners: {
+                status: "active" | "removed";
+                projectId: string;
+                source: "operator" | "seed" | "mention";
+                agentSlug: string;
+                projectSlug: string;
+                updatedAt: string;
+                agentHandle: string;
+                subscribedAt: string;
+            }[];
         };
-        projectStream: {
+        events: {
+            teamId: string;
+            topicId: string;
+            sendId: string | null;
+            invocationId: string | null;
+            assignmentId: string | null;
+            sequence: number;
+            type: "message.posted" | "mention.acknowledged" | "response_lease.accepted" | "agent.progress" | "agent.response" | "agent.abstained" | "agent.failed";
+            payload: Record<string, unknown>;
             id: string;
+            actor: {
+                kind: "control-plane" | "provider" | "agent" | "user";
+                id: string;
+                handle: string | null;
+            };
+            summary: string;
+            channel: string;
+            occurredAt: string;
+        }[];
+    }>;
+    topicsSubscribe: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        channel: string;
+    }, {}, {
+        agent: string;
+    }, {
+        topicId: string;
+        replayed: boolean;
+        listener: {
+            status: "active" | "removed";
             projectId: string;
+            source: "operator" | "seed" | "mention";
+            agentSlug: string;
             projectSlug: string;
+            updatedAt: string;
+            agentHandle: string;
+            subscribedAt: string;
         };
-        discussionId: string;
-        sourceMessage: string;
+    }>;
+    topicsUnsubscribe: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        teamId: string;
+        channel: string;
+    }, {}, {
+        agent: string;
+    }, {
+        topicId: string;
         replayed: boolean;
+        listener: {
+            status: "active" | "removed";
+            projectId: string;
+            source: "operator" | "seed" | "mention";
+            agentSlug: string;
+            projectSlug: string;
+            updatedAt: string;
+            agentHandle: string;
+            subscribedAt: string;
+        };
     }>;
 };
 export declare function providerDiscussionResponseOperation(): import("../control-plane-operation.js").ControlPlaneOperationBinding<{
     assignmentId: string;
 }, {}, {
-    leaseToken: string;
     runnerId: string;
+    leaseToken: string;
     summary?: string | undefined;
     usage?: Record<string, unknown> | undefined;
     markdown?: string | undefined;
     outcome?: "responded" | "abstained" | undefined;
 }, {
-    status: "responded" | "abstained";
-    schemaVersion: "treeseed.provider-discussion-response-receipt/v1";
-    assignmentId: string;
     invocationId: string;
+    assignmentId: string;
+    schemaVersion: "treeseed.provider-discussion-response-receipt/v1";
+    status: "responded" | "abstained";
     messageRef: string;
     settledAt: string;
 }>;
+export declare function providerCommunicationLifecycleOperations(): {
+    notificationAcknowledge: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        assignmentId: string;
+    }, {}, {
+        providerId: string;
+        runnerId: string;
+        observedAt: string;
+    }, {
+        assignmentId: string;
+        acknowledgedAt: string;
+        replayed: boolean;
+    }>;
+    traceEvent: import("../control-plane-operation.js").ControlPlaneOperationBinding<{
+        assignmentId: string;
+    }, {}, {
+        sequence: number;
+        type: string;
+        payload: Record<string, unknown>;
+        summary: string;
+        occurredAt: string;
+        runnerId: string;
+        leaseToken: string;
+        protectedPayload?: Record<string, unknown> | undefined;
+    }, {
+        assignmentId: string;
+        sequence: number;
+        replayed: boolean;
+        acceptedAt: string;
+    }>;
+};

package/dist/operator-contracts/catalog/communication-operations.js

@@ -3,6 +3,13 @@ import { defineOperation } from "../operation-builder.js";
 import {
   communicationSendReceiptSchema,
   communicationSendRequestSchema,
+  communicationTopicPageSchema,
+  communicationTopicSchema,
+  communicationTopicSubscriptionReceiptSchema,
+  communicationTopicSubscriptionRequestSchema,
+  communicationTopicTimelineSchema,
+  providerCommunicationNotificationAcknowledgeRequestSchema,
+  providerCommunicationTraceEventRequestSchema,
   providerDiscussionResponseReceiptSchema,
   providerDiscussionResponseRequestSchema
 } from "../communication/contracts.js";
@@ -10,7 +17,7 @@ const empty = z.object({}).strict();
 const none = z.undefined();
 function communicationOperations() {
   return {
-    send: defineOperation({ operationId: "communications.send", description: "Post a team discussion-topic message and admit its addressed project agents to the communication lane.", rest: { method: "POST", path: "/v1/teams/{teamId}/discussion-topics/{channel}/messages" }, parameters: "treeseed.communications.send.parameters/v2", capability: "agents.execute", authentication: "oauth", oauthScopes: ["treeseed:execution"], kind: "mutation", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "cli", "mcp_tool"], cacheScope: "none", pagination: "none" }, {
+    send: defineOperation({ operationId: "communications.send", description: "Post a team discussion-topic message and admit every addressed team agent to its project communication stream.", rest: { method: "POST", path: "/v1/teams/{teamId}/discussion-topics/{channel}/messages" }, parameters: "treeseed.communications.send.parameters/v3", capability: "agents.execute", authentication: "oauth", oauthScopes: ["treeseed:execution"], kind: "mutation", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "cli", "mcp_tool"], cacheScope: "none", pagination: "none" }, {
       path: z.object({ teamId: z.string().min(1), channel: z.string().trim().min(1).max(120) }).strict(),
       query: empty,
       body: communicationSendRequestSchema,
@@ -18,9 +25,39 @@ function communicationOperations() {
     }),
     sendStatus: defineOperation({ operationId: "communications.sends.show", description: "Read a communication send and its durable agent responses.", rest: { method: "GET", path: "/v1/teams/{teamId}/communication-sends/{sendId}" }, parameters: "treeseed.communications.sends.show.parameters/v1", capability: "agents.read", authentication: "oauth", oauthScopes: ["treeseed:read"], kind: "read", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "mcp_tool", "mcp_resource"], cacheScope: "principal", pagination: "none" }, {
       path: z.object({ teamId: z.string().min(1), sendId: z.string().min(1) }).strict(),
-      query: empty,
+      query: z.object({ diagnostics: z.enum(["metadata", "full"]).optional() }).strict(),
       body: none,
       output: communicationSendReceiptSchema
+    }),
+    topicsList: defineOperation({ operationId: "communications.topics.list", description: "List team discussion topics and active listeners.", rest: { method: "GET", path: "/v1/teams/{teamId}/discussion-topics" }, parameters: "treeseed.communications.topics.list.parameters/v1", capability: "agents.read", authentication: "oauth", oauthScopes: ["treeseed:read"], kind: "read", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "cli", "mcp_tool", "mcp_resource"], cacheScope: "principal", pagination: "cursor" }, {
+      path: z.object({ teamId: z.string().min(1) }).strict(),
+      query: z.object({ status: z.enum(["active", "archived"]).optional(), limit: z.coerce.number().int().min(1).max(200).optional(), cursor: z.string().optional() }).strict(),
+      body: none,
+      output: communicationTopicPageSchema
+    }),
+    topicsShow: defineOperation({ operationId: "communications.topics.show", description: "Show one discussion topic, streams, and listeners.", rest: { method: "GET", path: "/v1/teams/{teamId}/discussion-topics/{channel}" }, parameters: "treeseed.communications.topics.show.parameters/v1", capability: "agents.read", authentication: "oauth", oauthScopes: ["treeseed:read"], kind: "read", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "cli", "mcp_tool", "mcp_resource"], cacheScope: "principal", pagination: "none" }, {
+      path: z.object({ teamId: z.string().min(1), channel: z.string().min(1) }).strict(),
+      query: empty,
+      body: none,
+      output: communicationTopicSchema
+    }),
+    topicsTimeline: defineOperation({ operationId: "communications.topics.timeline", description: "Read the ordered durable timeline for a discussion topic.", rest: { method: "GET", path: "/v1/teams/{teamId}/discussion-topics/{channel}/timeline" }, parameters: "treeseed.communications.topics.timeline.parameters/v1", capability: "agents.read", authentication: "oauth", oauthScopes: ["treeseed:read"], kind: "read", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "mcp_tool", "mcp_resource"], cacheScope: "principal", pagination: "cursor" }, {
+      path: z.object({ teamId: z.string().min(1), channel: z.string().min(1) }).strict(),
+      query: z.object({ after: z.string().optional(), waitSeconds: z.coerce.number().int().min(0).max(30).optional(), limit: z.coerce.number().int().min(1).max(500).optional(), diagnostics: z.enum(["metadata", "full"]).optional() }).strict(),
+      body: none,
+      output: communicationTopicTimelineSchema
+    }),
+    topicsSubscribe: defineOperation({ operationId: "communications.topics.subscriptions.put", description: "Subscribe an agent to a discussion topic.", rest: { method: "PUT", path: "/v1/teams/{teamId}/discussion-topics/{channel}/subscriptions" }, parameters: "treeseed.communications.topics.subscriptions.put.parameters/v1", capability: "agents.execute", authentication: "oauth", oauthScopes: ["treeseed:execution"], kind: "mutation", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "cli", "mcp_tool"], cacheScope: "none", pagination: "none" }, {
+      path: z.object({ teamId: z.string().min(1), channel: z.string().min(1) }).strict(),
+      query: empty,
+      body: communicationTopicSubscriptionRequestSchema,
+      output: communicationTopicSubscriptionReceiptSchema
+    }),
+    topicsUnsubscribe: defineOperation({ operationId: "communications.topics.subscriptions.delete", description: "Remove an agent subscription from a discussion topic.", rest: { method: "DELETE", path: "/v1/teams/{teamId}/discussion-topics/{channel}/subscriptions" }, parameters: "treeseed.communications.topics.subscriptions.delete.parameters/v1", capability: "agents.execute", authentication: "oauth", oauthScopes: ["treeseed:execution"], kind: "mutation", riskClass: "ordinary", confirmation: "never", surfaces: ["rest", "cli", "mcp_tool"], cacheScope: "none", pagination: "none" }, {
+      path: z.object({ teamId: z.string().min(1), channel: z.string().min(1) }).strict(),
+      query: empty,
+      body: communicationTopicSubscriptionRequestSchema,
+      output: communicationTopicSubscriptionReceiptSchema
     })
   };
 }
@@ -32,7 +69,24 @@ function providerDiscussionResponseOperation() {
     output: providerDiscussionResponseReceiptSchema
   });
 }
+function providerCommunicationLifecycleOperations() {
+  return {
+    notificationAcknowledge: defineOperation({ operationId: "providers.assignments.communication.acknowledge", description: "Acknowledge provider observation of an addressed communication mention.", rest: { method: "POST", path: "/v1/provider/assignments/{assignmentId}/communication-acknowledgement" }, parameters: "treeseed.providers.assignments.communication.acknowledge.parameters/v1", capability: "providers.execute", authentication: "provider", oauthScopes: [], kind: "mutation", riskClass: "ordinary", confirmation: "never", surfaces: ["rest"], cacheScope: "none", pagination: "none" }, {
+      path: z.object({ assignmentId: z.string().min(1) }).strict(),
+      query: empty,
+      body: providerCommunicationNotificationAcknowledgeRequestSchema,
+      output: z.object({ assignmentId: z.string(), acknowledgedAt: z.string().datetime(), replayed: z.boolean() }).strict()
+    }),
+    traceEvent: defineOperation({ operationId: "providers.assignments.communication.trace.create", description: "Append one provider-authored communication execution trace event.", rest: { method: "POST", path: "/v1/provider/assignments/{assignmentId}/communication-trace-events" }, parameters: "treeseed.providers.assignments.communication.trace.create.parameters/v1", capability: "providers.execute", authentication: "provider", oauthScopes: [], kind: "mutation", riskClass: "ordinary", confirmation: "never", surfaces: ["rest"], cacheScope: "none", pagination: "none" }, {
+      path: z.object({ assignmentId: z.string().min(1) }).strict(),
+      query: empty,
+      body: providerCommunicationTraceEventRequestSchema,
+      output: z.object({ assignmentId: z.string(), sequence: z.number().int().nonnegative(), acceptedAt: z.string().datetime(), replayed: z.boolean() }).strict()
+    })
+  };
+}
 export {
   communicationOperations,
+  providerCommunicationLifecycleOperations,
   providerDiscussionResponseOperation
 };