@treeseed/sdk 0.13.0-rc.11 → 0.13.0-rc.111

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

@@ -0,0 +1,188 @@
+import { z } from "zod";
+const communicationRecipientSchema = z.object({
+  projectId: z.string().min(1),
+  agentSlug: z.string().min(1)
+}).strict();
+const communicationSendRequestSchema = z.object({
+  message: z.string().trim().min(1).max(1e5),
+  recipients: z.array(z.string().trim().min(1)).max(100).optional(),
+  timeoutSeconds: z.number().int().min(1).max(3600).optional()
+}).strict();
+const communicationTopicEventTypeSchema = z.enum([
+  "message.posted",
+  "mention.acknowledged",
+  "response_lease.accepted",
+  "agent.progress",
+  "agent.response",
+  "agent.abstained",
+  "agent.failed"
+]);
+const communicationTopicEventSchema = z.object({
+  id: z.string().min(1),
+  sequence: z.number().int().positive(),
+  teamId: z.string().min(1),
+  topicId: z.string().min(1),
+  channel: z.string().min(1),
+  type: communicationTopicEventTypeSchema,
+  occurredAt: z.string().datetime(),
+  sendId: z.string().min(1).nullable(),
+  invocationId: z.string().min(1).nullable(),
+  assignmentId: z.string().min(1).nullable(),
+  actor: z.object({ kind: z.enum(["user", "agent", "provider", "control-plane"]), id: z.string().min(1), handle: z.string().min(1).nullable() }).strict(),
+  summary: z.string().min(1),
+  payload: z.record(z.unknown())
+}).strict();
+const communicationDiagnosticSchema = z.object({
+  availability: z.enum(["available", "partial", "unavailable"]),
+  reason: z.string().min(1).nullable(),
+  provider: z.object({ providerId: z.string().min(1).nullable(), executionProviderId: z.string().min(1).nullable(), runtimeVersion: z.string().min(1).nullable() }).strict(),
+  selection: z.object({ model: z.string().min(1).nullable(), capabilities: z.array(z.string()), parameters: z.record(z.unknown()) }).strict(),
+  identityManifest: z.record(z.unknown()),
+  contextManifest: z.array(z.record(z.unknown())),
+  usage: z.array(z.record(z.unknown())),
+  timing: z.record(z.unknown()),
+  resources: z.record(z.unknown()),
+  traceEvents: z.array(z.record(z.unknown())),
+  fullPayload: z.record(z.unknown()).optional()
+}).strict();
+const communicationTargetSchema = communicationRecipientSchema.extend({
+  projectSlug: z.string().min(1),
+  definitionRevision: z.string().min(1),
+  revisions: z.object({
+    project: z.string().min(1),
+    library: z.string().min(1),
+    agentDefinition: z.string().min(1),
+    chatProfile: z.string().min(1)
+  }).strict(),
+  invocationId: z.string().min(1).nullable(),
+  requirement: z.enum(["required", "optional"]),
+  parentInvocationId: z.string().min(1).nullable(),
+  depth: z.number().int().nonnegative(),
+  status: z.enum(["queued", "running", "responded", "abstained", "failed", "cancelled"]),
+  requestedAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  completedAt: z.string().datetime().nullable(),
+  failure: z.object({ code: z.string().min(1), message: z.string().nullable() }).strict().nullable(),
+  capacity: z.object({
+    assignmentId: z.string().min(1).nullable(),
+    providerId: z.string().min(1).nullable(),
+    executionProviderId: z.string().min(1).nullable(),
+    laneId: z.string().min(1).nullable(),
+    lanePurpose: z.string().min(1).nullable(),
+    status: z.string().min(1).nullable(),
+    assignedAt: z.string().datetime().nullable(),
+    claimedAt: z.string().datetime().nullable(),
+    completedAt: z.string().datetime().nullable(),
+    returnedAt: z.string().datetime().nullable(),
+    failedAt: z.string().datetime().nullable()
+  }).strict(),
+  acknowledgedAt: z.string().datetime().nullable(),
+  leaseAcceptedAt: z.string().datetime().nullable(),
+  diagnostics: communicationDiagnosticSchema
+});
+const communicationResponseSchema = communicationRecipientSchema.extend({
+  projectSlug: z.string().min(1),
+  invocationId: z.string().min(1),
+  assignmentId: z.string().min(1).nullable(),
+  messageRef: z.string().min(1),
+  markdown: z.string(),
+  requirement: z.enum(["required", "optional"]),
+  status: z.enum(["responded", "abstained", "failed", "cancelled"]),
+  createdAt: z.string().datetime()
+});
+const communicationSendReceiptSchema = z.object({
+  schemaVersion: z.literal("treeseed.communication-send-receipt/v4"),
+  sendId: z.string().min(1),
+  teamId: z.string().min(1),
+  channel: z.string().min(1),
+  topic: z.object({ id: z.string().min(1), slug: z.string().min(1) }).strict(),
+  projectStreams: z.array(z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    projectSlug: z.string().min(1),
+    discussionId: z.string().min(1),
+    messageRef: z.string().min(1)
+  }).strict()).min(1),
+  status: z.enum(["queued", "running", "complete", "partial", "failed"]),
+  targets: z.array(communicationTargetSchema),
+  responses: z.array(communicationResponseSchema),
+  events: z.array(communicationTopicEventSchema),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  replayed: z.boolean()
+}).strict();
+const communicationTopicListenerSchema = communicationRecipientSchema.extend({
+  projectSlug: z.string().min(1),
+  agentHandle: z.string().min(1),
+  status: z.enum(["active", "removed"]),
+  subscribedAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  source: z.enum(["mention", "operator", "seed"])
+}).strict();
+const communicationTopicSchema = z.object({
+  id: z.string().min(1),
+  teamId: z.string().min(1),
+  slug: z.string().min(1),
+  status: z.enum(["active", "archived"]),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+  streams: z.array(z.object({ id: z.string().min(1), projectId: z.string().min(1), projectSlug: z.string().min(1), discussionId: z.string().min(1) }).strict()),
+  listeners: z.array(communicationTopicListenerSchema)
+}).strict();
+const communicationTopicPageSchema = z.object({ items: z.array(communicationTopicSchema), cursor: z.string().nullable() }).strict();
+const communicationTopicTimelineSchema = z.object({ topic: communicationTopicSchema, events: z.array(communicationTopicEventSchema), cursor: z.string().nullable() }).strict();
+const communicationTopicSubscriptionRequestSchema = z.object({ agent: z.string().trim().min(2).max(180) }).strict();
+const communicationTopicSubscriptionReceiptSchema = z.object({ topicId: z.string().min(1), listener: communicationTopicListenerSchema, replayed: z.boolean() }).strict();
+const providerCommunicationNotificationAcknowledgeRequestSchema = z.object({
+  providerId: z.string().min(1),
+  runnerId: z.string().min(1),
+  observedAt: z.string().datetime()
+}).strict();
+const providerCommunicationTraceEventRequestSchema = z.object({
+  leaseToken: z.string().min(1),
+  runnerId: z.string().min(1),
+  sequence: z.number().int().nonnegative(),
+  type: z.string().min(1),
+  occurredAt: z.string().datetime(),
+  summary: z.string().min(1),
+  payload: z.record(z.unknown()),
+  protectedPayload: z.record(z.unknown()).optional()
+}).strict();
+const providerDiscussionResponseRequestSchema = z.object({
+  leaseToken: z.string().min(1),
+  runnerId: z.string().min(1),
+  outcome: z.enum(["responded", "abstained"]).default("responded"),
+  markdown: z.string().trim().min(1).max(1e5).optional(),
+  summary: z.string().trim().min(1).max(4e3).optional(),
+  usage: z.record(z.unknown()).optional()
+}).strict().superRefine((value, context) => {
+  if (value.outcome === "responded" && !value.markdown) context.addIssue({ code: z.ZodIssueCode.custom, path: ["markdown"], message: "A response requires Markdown." });
+});
+const providerDiscussionResponseReceiptSchema = z.object({
+  schemaVersion: z.literal("treeseed.provider-discussion-response-receipt/v1"),
+  assignmentId: z.string().min(1),
+  invocationId: z.string().min(1),
+  messageRef: z.string().min(1),
+  status: z.enum(["responded", "abstained"]),
+  settledAt: z.string().datetime()
+}).strict();
+export {
+  communicationDiagnosticSchema,
+  communicationRecipientSchema,
+  communicationResponseSchema,
+  communicationSendReceiptSchema,
+  communicationSendRequestSchema,
+  communicationTargetSchema,
+  communicationTopicEventSchema,
+  communicationTopicEventTypeSchema,
+  communicationTopicListenerSchema,
+  communicationTopicPageSchema,
+  communicationTopicSchema,
+  communicationTopicSubscriptionReceiptSchema,
+  communicationTopicSubscriptionRequestSchema,
+  communicationTopicTimelineSchema,
+  providerCommunicationNotificationAcknowledgeRequestSchema,
+  providerCommunicationTraceEventRequestSchema,
+  providerDiscussionResponseReceiptSchema,
+  providerDiscussionResponseRequestSchema
+};

package/dist/operator-contracts/control-plane-operation.d.ts

@@ -7,6 +7,7 @@ export type ControlPlaneConfirmationPolicy = 'never' | 'input_required';
 export type ControlPlaneOperationSurface = 'rest' | 'cli' | 'mcp_tool' | 'mcp_resource' | 'internal';
 export type ControlPlaneCacheScope = 'none' | 'principal' | 'team' | 'project' | 'public';
 export type ControlPlanePaginationKind = 'none' | 'cursor';
+export type ControlPlaneAuthenticationKind = 'anonymous' | 'oauth' | 'oauth_or_provider' | 'provider' | 'signed_request';
 export interface ControlPlaneRestBinding {
     method: ControlPlaneHttpMethod;
     path: `/v1/${string}`;
@@ -26,6 +27,12 @@ export interface ControlPlaneConcurrencyContract {
     readHeader: 'ETag';
     writeHeader: 'If-Match';
 }
+export interface ControlPlaneUpstreamBinding {
+    service: 'treedx' | 'treeai';
+    operationId: string;
+    contractVersion: string;
+    contractDigest: `sha256:${string}`;
+}
 export interface ControlPlaneOperationDescriptor {
     schemaVersion: typeof CONTROL_PLANE_OPERATION_SCHEMA_VERSION;
     operationId: `${string}.${string}`;
@@ -33,6 +40,7 @@ export interface ControlPlaneOperationDescriptor {
     rest?: ControlPlaneRestBinding;
     schemas: ControlPlaneSchemaBinding;
     capability: string;
+    authentication: ControlPlaneAuthenticationKind;
     oauthScopes: OAuthScope[];
     kind: ControlPlaneOperationKind;
     riskClass: ControlPlaneRiskClass;
@@ -45,6 +53,7 @@ export interface ControlPlaneOperationDescriptor {
     audited: boolean;
     receipt: boolean;
     redactedPaths: string[];
+    upstream?: ControlPlaneUpstreamBinding;
 }
 export interface ControlPlaneOperationInput<TPath = Record<string, never>, TQuery = Record<string, never>, TBody = undefined> {
     path: TPath;

package/dist/operator-contracts/control-plane-operation.js

@@ -44,11 +44,21 @@ function validateControlPlaneCatalog(catalog) {
     for (const scope of operation.oauthScopes) {
       if (!TREESEED_OAUTH_SCOPES.includes(scope)) diagnostics.push({ code: "oauth_scope_invalid", path: `${path}.oauthScopes`, message: `Unknown OAuth scope ${scope}.` });
     }
+    if (!["oauth", "oauth_or_provider"].includes(operation.authentication) && operation.oauthScopes.length > 0) {
+      diagnostics.push({ code: "oauth_scope_forbidden", path: `${path}.oauthScopes`, message: "Only OAuth-authenticated operations may declare OAuth scopes." });
+    }
+    if (operation.authentication === "provider" && operation.capability !== "providers.execute") {
+      diagnostics.push({ code: "provider_auth_capability_invalid", path: `${path}.capability`, message: "Provider-authenticated operations require providers.execute." });
+    }
     for (const duplicate of duplicates(operation.surfaces)) diagnostics.push({ code: "surface_duplicate", path: `${path}.surfaces`, message: `Duplicate operation surface ${duplicate}.` });
     for (const duplicate of duplicates(operation.oauthScopes)) diagnostics.push({ code: "oauth_scope_duplicate", path: `${path}.oauthScopes`, message: `Duplicate OAuth scope ${duplicate}.` });
+    if (operation.upstream && (!operation.upstream.operationId || !/^sha256:[0-9a-f]{64}$/u.test(operation.upstream.contractDigest))) {
+      diagnostics.push({ code: "upstream_binding_invalid", path: `${path}.upstream`, message: "Upstream bindings require an operation ID and exact SHA-256 contract digest." });
+    }
     const elevatedRisk = operation.riskClass !== "ordinary";
-    if (elevatedRisk !== (operation.confirmation === "input_required")) {
-      diagnostics.push({ code: "confirmation_policy_invalid", path: `${path}.confirmation`, message: "Elevated-risk operations require input_required; ordinary operations must not." });
+    const directCredential = operation.riskClass === "credential" && operation.confirmation === "never" && operation.authentication === "oauth" && operation.redactedPaths.includes("body.values");
+    if (!directCredential && elevatedRisk !== (operation.confirmation === "input_required")) {
+      diagnostics.push({ code: "confirmation_policy_invalid", path: `${path}.confirmation`, message: "Elevated-risk operations require input_required unless authenticated credential input is explicitly redacted; ordinary operations must not." });
     }
     if (operation.kind === "read" && (operation.idempotency.required || operation.concurrency.required || operation.receipt)) {
       diagnostics.push({ code: "read_mutation_contract_invalid", path, message: "Read operations cannot require mutation idempotency, write concurrency, or mutation receipts." });