@treeseed/sdk 0.13.0-rc.12 → 0.13.0-rc.121

package/README.md

@@ -1,5 +1,7 @@
 # `@treeseed/sdk`
 
+The operator catalog includes versioned `inbox.*` operations for unified team inbox queries, ordered events, private drafts, routed question creation, and exact-version governance actions.
+
 `@treeseed/sdk` is TreeSeed's portable contract and remote API package. It gives API, CLI, Agent, browser, and external integrations one versioned description of the control plane and typed conduits to remote TreeSeed and TreeDX services.
 
 The SDK does not own control-plane persistence, scheduling, repository mutation, content publication, deployment, provider runtimes, or server-side business workflows. Those implementations belong to the API or their dedicated runtime packages.
@@ -19,32 +21,44 @@ import {
   ControlPlaneClient,
   defaultLocalControlPlaneServer,
 } from '@treeseed/sdk/control-plane-client';
+import { CONTROL_PLANE_OPERATIONS } from '@treeseed/sdk/operator-contracts';
 
 const client = new ControlPlaneClient({
   profile: defaultLocalControlPlaneServer(),
   accessToken: process.env.TREESEED_ACCESS_TOKEN,
 });
 
-const health = await client.call({ method: 'GET', path: '/v1/health' });
+const health = await client.invoke(CONTROL_PLANE_OPERATIONS.health.readiness, {
+  path: {},
+  query: {},
+  body: undefined,
+});
 ```
 
-The client provides typed operation dispatch, RFC 9457 problem handling, OAuth device and refresh flows, server-profile normalization, idempotency keys, optimistic-concurrency headers, and request cancellation. Generated operation bindings come from the versioned operation catalog; the generic `call` method accepts only the public REST path shape. Token and profile persistence belong to the consuming CLI, application, or host credential store.
+The client provides typed operation dispatch, RFC 9457 problem handling, OAuth device and refresh flows, server-profile normalization, idempotency keys, optimistic-concurrency headers, and request cancellation. Operation bindings come from the versioned operation catalog; callers do not construct control-plane paths. Token and profile persistence belong to the consuming CLI, application, or host credential store.
+
+Communication contracts treat discussion topics as team-wide coordination scopes. Qualified `@project/agent` addresses select one agent, while unqualified `@agent` addresses expand to every matching chat-enabled agent across active team projects. The API maintains a project-local TreeDX discussion stream for each addressed project and aggregates their invocations under one send identity.
 
 ## TreeDX API
 
 ```ts
-import { TreeDxClient } from '@treeseed/sdk/treedx/client';
+import { ControlPlaneClient } from '@treeseed/sdk/control-plane-client';
+import { TreeSeedTreeDxClient } from '@treeseed/sdk/treedx';
 
-const treeDx = new TreeDxClient({
-  baseUrl: 'http://127.0.0.1:4000',
-  token: process.env.TREEDX_TOKEN,
-  repoId: 'repo_123',
+const controlPlane = new ControlPlaneClient({
+  profile: defaultLocalControlPlaneServer(),
+  accessToken: process.env.TREESEED_ACCESS_TOKEN,
 });
+const treeDx = new TreeSeedTreeDxClient(controlPlane);
 
-const result = await treeDx.searchRepositoryFiles({ query: 'release' });
+const result = await treeDx.proxy.repositories.searchFiles({
+  path: { projectId: 'project_123', repositoryId: 'repository_123' },
+  query: { query: 'release' },
+  body: undefined,
+});
 ```
 
-TreeDX remains a remote service. Its client and transport types are retained here so consumers do not duplicate protocol code.
+TreeDX remains an independently released remote service. This package imports its authoritative payload types but exposes only the project-scoped TreeSeed proxy facade. Direct TreeDX transport, endpoints, topology, and credentials remain confined to trusted control-plane infrastructure.
 
 ## Public boundaries
 

package/dist/.treeseed-build-complete.json

@@ -0,0 +1 @@
+{"completedAt":"2026-09-19T18:29:15.010Z"}

package/dist/accounts/account-contracts.d.ts

@@ -83,11 +83,15 @@ export interface AccountIdentity {
         linkedAt: string;
         canUnlink: boolean;
     }>;
+    /** Exact account revision supplied as If-Match for concurrent identity mutations. */
+    updatedAt?: string;
 }
 export interface AccountPreferences {
     timeZone: string;
     realTimeUpdates: boolean;
     realTimePollingIntervalSeconds: 2 | 5 | 15 | 30;
+    /** Exact preference revision supplied as If-Match for concurrent preference mutations. */
+    updatedAt?: string;
 }
 export type AccountPreferencesUpdate = Partial<AccountPreferences>;
 export interface AccountWebSession {
@@ -130,6 +134,8 @@ export interface NotificationPreferences {
     emailCadence: NotificationEmailCadence;
     globalContentTypes: string[];
     projectOverrides: NotificationProjectOverride[];
+    /** Exact notification-preference revision supplied as If-Match for concurrent updates. */
+    updatedAt?: string;
 }
 export interface AccountNotification {
     id: string;

package/dist/agent-capacity/allocation.d.ts

@@ -181,6 +181,3 @@ export interface CapacityAdmissionCounterClaim {
 }
 export { validateCapacityAllocationSetV2, validateCapacityGrantV2 } from './validation/allocation.js';
 export type { CapacityAllocationDiagnostic, CapacityAllocationValidation } from './validation/allocation.js';
-export declare function timestamp(value: string | null | undefined): number | null;
-export declare function firstReason(reasons: CapacityAdmissionReasonCode[]): CapacityAdmissionReasonCode;
-export declare function evaluateCapacityAdmission(input: CapacityAdmissionInput): CapacityAdmissionDecision;

package/dist/agent-capacity/allocation.js

@@ -1,226 +1,5 @@
 import { validateCapacityAllocationSetV2, validateCapacityGrantV2 } from "./validation/allocation.js";
-function timestamp(value) {
-  const parsed = value ? Date.parse(value) : Number.NaN;
-  return Number.isFinite(parsed) ? parsed : null;
-}
-function firstReason(reasons) {
-  return reasons[0] ?? "allowed";
-}
-function evaluateCapacityAdmission(input) {
-  const reasons = [];
-  const explanation = [];
-  let remaining = Number.POSITIVE_INFINITY;
-  let requiresApproval = false;
-  let allocationCalculations = {};
-  let allocationPriorityBand = "overflow";
-  let allocationPriorityScore = 0;
-  const counterClaims = [];
-  const deny = (gate, code, detail) => {
-    reasons.push(code);
-    explanation.push({ gate, allowed: false, detail });
-  };
-  const allow = (gate, gateRemaining, detail) => {
-    if (gateRemaining !== void 0) remaining = Math.min(remaining, Math.max(0, gateRemaining));
-    explanation.push({ gate, allowed: true, remaining: gateRemaining, detail });
-  };
-  const now = timestamp(input.now) ?? Date.now();
-  const request = input.request;
-  const requestedTokens = Number(request.budget?.tokens.hardLimitTokens ?? 0);
-  const requestedCost = Number(request.budget?.cost?.hardLimitAmount ?? 0);
-  const requestedNative = (request.budget?.native ?? []).filter((entry) => entry.cap != null).map((entry) => ({ unit: entry.unit, amount: Number(entry.cap) }));
-  if (!Number.isFinite(request.requestedSeconds) || request.requestedSeconds <= 0) deny("request", "requested_seconds_invalid");
-  if (requestedTokens < 0 || requestedCost < 0 || requestedNative.some((entry) => !entry.unit || !Number.isFinite(entry.amount) || entry.amount < 0)) deny("request-budget", "requested_budget_invalid");
-  if (input.membership.status !== "approved") deny("membership", input.membership.status === "suspended" ? "membership_suspended" : input.membership.status === "revoked" ? "membership_revoked" : "membership_not_approved");
-  else allow("membership");
-  if (input.membership.id !== request.membershipId) deny("membership-id", "membership_id_mismatch");
-  else allow("membership-id");
-  if (input.membership.teamId !== request.teamId) deny("membership-team", "membership_team_mismatch");
-  else allow("membership-team");
-  if (input.membership.providerId !== request.providerId) deny("membership-provider", "membership_provider_mismatch");
-  else allow("membership-provider");
-  if (input.availability.status !== "open") deny("availability", "availability_session_not_open");
-  else if ((timestamp(input.availability.availableFrom) ?? Number.POSITIVE_INFINITY) > now || input.availability.availableUntil && (timestamp(input.availability.availableUntil) ?? 0) <= now) deny("availability", "outside_availability_window");
-  else allow("availability");
-  const grant = input.grant;
-  if (!grant || grant.status !== "active") deny("grant", "missing_active_grant");
-  else {
-    if (grant.membershipId !== request.membershipId) deny("grant-membership", "grant_membership_mismatch");
-    else allow("grant-membership");
-    if (grant.teamId !== request.teamId) deny("grant-team", "grant_team_mismatch");
-    else allow("grant-team");
-    if (grant.providerId !== request.providerId) deny("grant-provider", "grant_provider_mismatch");
-    else allow("grant-provider");
-    if (grant.expiresAt && (timestamp(grant.expiresAt) ?? 0) <= now) deny("grant-expiry", "grant_expired");
-    else allow("grant-expiry");
-    if (grant.projectId !== request.projectId) deny("grant-project", "grant_project_mismatch");
-    else allow("grant-project");
-    if (grant.environment !== request.environment) deny("grant-environment", "grant_environment_mismatch");
-    else allow("grant-environment");
-    if (!grant.allowedModes.includes(request.mode)) deny("grant-mode", "grant_mode_denied");
-    else allow("grant-mode");
-    const missing = request.requiredCapabilities.filter((capability) => !grant.capabilities.includes(capability));
-    if (missing.length) deny("grant-capabilities", "grant_capability_missing", missing.join(", "));
-    else allow("grant-capabilities");
-    if (request.executionProviderId && grant.executionProviderIds.length && !grant.executionProviderIds.includes(request.executionProviderId)) deny("grant-execution-provider", "grant_execution_provider_denied");
-    else allow("grant-execution-provider");
-    if (request.laneId && grant.laneIds.length && !grant.laneIds.includes(request.laneId)) deny("grant-lane", "grant_lane_denied");
-    else allow("grant-lane");
-    if (!grant.unmetered && grant.dailyAgentSecondsLimit == null && grant.monthlyAgentSecondsLimit == null) deny("grant-time", "grant_time_exhausted", "Grant must declare agent-time limits or explicit unmetered capacity.");
-    if (grant.dailyAgentSecondsLimit != null) {
-      const available = grant.dailyAgentSecondsLimit - input.grantCommitted.dailyAgentSeconds;
-      if (available <= 0) deny("grant-daily", "grant_time_exhausted");
-      else allow("grant-daily", available);
-      counterClaims.push({ id: `grant-daily:${grant.id}:${input.now.slice(0, 10)}`, scope: "grant-daily", scopeId: grant.id, periodKey: input.now.slice(0, 10), hardLimit: grant.dailyAgentSecondsLimit, amount: request.requestedSeconds, release: "settlement-difference" });
-    }
-    if (grant.monthlyAgentSecondsLimit != null) {
-      const available = grant.monthlyAgentSecondsLimit - input.grantCommitted.monthlyAgentSeconds;
-      if (available <= 0) deny("grant-monthly", "grant_time_exhausted");
-      else allow("grant-monthly", available);
-      counterClaims.push({ id: `grant-monthly:${grant.id}:${input.now.slice(0, 7)}`, scope: "grant-monthly", scopeId: grant.id, periodKey: input.now.slice(0, 7), hardLimit: grant.monthlyAgentSecondsLimit, amount: request.requestedSeconds, release: "settlement-difference" });
-    }
-    if (grant.maxConcurrentAssignments != null) {
-      const available = grant.maxConcurrentAssignments - input.grantCommitted.activeAssignments;
-      if (available < 1) deny("grant-concurrency", "grant_concurrency_exhausted");
-      else allow("grant-concurrency");
-      counterClaims.push({ id: `grant-concurrency:${grant.id}:active`, scope: "grant-concurrency", scopeId: grant.id, periodKey: "active", hardLimit: grant.maxConcurrentAssignments, amount: 1, release: "assignment-terminal", dimension: "concurrency" });
-    }
-    const tokenLimit = Number(grant.budgetLimits?.tokens ?? Number.NaN);
-    if (requestedTokens > 0 && Number.isFinite(tokenLimit)) {
-      const available = tokenLimit - Number(input.grantCommitted.tokens ?? 0);
-      if (available < requestedTokens) deny("grant-token", "grant_token_exhausted");
-      else allow("grant-token", available);
-      counterClaims.push({ id: `grant-token:${grant.id}:lifetime`, scope: "grant-token", scopeId: grant.id, periodKey: "lifetime", hardLimit: tokenLimit, amount: requestedTokens, release: "settlement-difference", dimension: "tokens" });
-    }
-    const costLimit = Number(grant.budgetLimits?.cost?.amount ?? Number.NaN);
-    if (requestedCost > 0 && Number.isFinite(costLimit)) {
-      const available = costLimit - Number(input.grantCommitted.cost ?? 0);
-      if (available < requestedCost) deny("grant-cost", "grant_cost_exhausted");
-      else allow("grant-cost", available);
-      counterClaims.push({ id: `grant-cost:${grant.id}:${grant.budgetLimits?.cost?.currency ?? "USD"}`, scope: "grant-cost", scopeId: grant.id, periodKey: grant.budgetLimits?.cost?.currency ?? "USD", hardLimit: costLimit, amount: requestedCost, release: "settlement-difference", dimension: "cost", unit: grant.budgetLimits?.cost?.currency ?? "USD" });
-    }
-    for (const native of requestedNative) {
-      const limit = grant.budgetLimits?.native?.find((entry) => entry.unit === native.unit)?.amount;
-      if (limit == null) continue;
-      const available = limit - Number(input.grantCommitted.native?.[native.unit] ?? 0);
-      if (available < native.amount) deny(`grant-native:${native.unit}`, "grant_native_exhausted");
-      else allow(`grant-native:${native.unit}`, available);
-      counterClaims.push({ id: `grant-native:${grant.id}:${native.unit}`, scope: "grant-native", scopeId: grant.id, periodKey: native.unit, hardLimit: limit, amount: native.amount, release: "settlement-difference", dimension: "native", unit: native.unit });
-    }
-  }
-  if (input.workday.status !== "active") deny("workday", "workday_not_active");
-  else {
-    const available = input.workday.totalSeconds - input.workday.committedSeconds;
-    if (available <= 0) deny("workday-budget", "workday_budget_exhausted");
-    else allow("workday-budget", available);
-    counterClaims.push({ id: `workday:${input.workday.id}:lifetime`, scope: "workday", scopeId: input.workday.id, periodKey: "lifetime", hardLimit: input.workday.totalSeconds, amount: request.requestedSeconds, release: "settlement-difference" });
-  }
-  const allocation = input.allocationSet;
-  if (!allocation || allocation.status !== "active") deny("allocation", "allocation_set_not_active");
-  else if (allocation.teamId !== request.teamId) deny("allocation", "allocation_team_mismatch");
-  else if ((timestamp(allocation.effectiveFrom) ?? Number.POSITIVE_INFINITY) > now || allocation.effectiveUntil && (timestamp(allocation.effectiveUntil) ?? 0) <= now) deny("allocation", "allocation_set_not_effective");
-  else {
-    allow("allocation");
-    const hierarchy = evaluateAllocationHierarchy({
-      allocation,
-      workdayId: input.workday.id,
-      totalSeconds: input.workday.totalSeconds,
-      requestedSeconds: request.requestedSeconds,
-      selectedSliceIds: input.allocationSliceIds,
-      committedBySlice: input.committedSecondsBySlice,
-      committedBorrowedByRule: input.committedBorrowedSecondsByRule,
-      reserveCommittedSeconds: input.reserveCommittedSeconds,
-      approvedBorrowingRuleIds: input.approvedBorrowingRuleIds
-    });
-    reasons.push(...hierarchy.reasons);
-    explanation.push(...hierarchy.explanation);
-    counterClaims.push(...hierarchy.counterClaims);
-    remaining = Math.min(remaining, hierarchy.maxReservableSeconds);
-    requiresApproval ||= hierarchy.requiresApproval;
-    allocationCalculations = hierarchy.calculations;
-    allocationPriorityBand = hierarchy.priorityBand;
-    allocationPriorityScore = hierarchy.priorityScore;
-  }
-  if (input.providerCapacity.availableConcurrentAssignments < 1 || input.providerCapacity.availableAgentSeconds <= 0) deny("provider-capacity", "provider_capacity_exhausted");
-  else {
-    allow("provider-capacity", input.providerCapacity.availableAgentSeconds);
-    const period = input.availability.availableFrom;
-    counterClaims.push(
-      { id: `provider-time:${request.providerId}:${period}`, scope: "provider-time", scopeId: request.providerId, periodKey: period, hardLimit: input.providerCapacity.availableAgentSeconds, amount: request.requestedSeconds, release: "settlement-difference", dimension: "time" },
-      { id: `provider-concurrency:${request.providerId}:${period}`, scope: "provider-concurrency", scopeId: request.providerId, periodKey: period, hardLimit: input.providerCapacity.availableConcurrentAssignments, amount: 1, release: "assignment-terminal", dimension: "concurrency" }
-    );
-  }
-  const advertisedCapabilities = input.providerCapacity.capabilities;
-  if (advertisedCapabilities) {
-    const missing = request.requiredCapabilities.filter((capability) => !advertisedCapabilities.includes(capability));
-    if (missing.length) deny("provider-capabilities", "provider_capability_missing", missing.join(", "));
-    else allow("provider-capabilities");
-  }
-  if (input.providerLocalLimits.availableConcurrentAssignments < 1 || input.providerLocalLimits.availableAgentSeconds <= 0) deny("provider-local", "provider_local_limit_exhausted");
-  else {
-    allow("provider-local", input.providerLocalLimits.availableAgentSeconds);
-    const period = input.availability.availableFrom;
-    counterClaims.push(
-      { id: `provider-local-time:${request.providerId}:${period}`, scope: "provider-local-time", scopeId: request.providerId, periodKey: period, hardLimit: input.providerLocalLimits.availableAgentSeconds, amount: request.requestedSeconds, release: "settlement-difference", dimension: "time" },
-      { id: `provider-local-concurrency:${request.providerId}:${period}`, scope: "provider-local-concurrency", scopeId: request.providerId, periodKey: period, hardLimit: input.providerLocalLimits.availableConcurrentAssignments, amount: 1, release: "assignment-terminal", dimension: "concurrency" }
-    );
-  }
-  for (const [scope, available] of [["provider-token", input.providerCapacity.availableTokens], ["provider-local-token", input.providerLocalLimits.availableTokens]]) if (requestedTokens > 0 && available != null) {
-    if (available < requestedTokens) deny(scope, "provider_budget_exhausted");
-    counterClaims.push({ id: `${scope}:${request.providerId}:${input.availability.availableFrom}`, scope, scopeId: request.providerId, periodKey: input.availability.availableFrom, hardLimit: available, amount: requestedTokens, release: "settlement-difference", dimension: "tokens" });
-  }
-  for (const [scope, available] of [["provider-cost", input.providerCapacity.availableCost], ["provider-local-cost", input.providerLocalLimits.availableCost]]) if (requestedCost > 0 && available != null) {
-    if (available < requestedCost) deny(scope, "provider_budget_exhausted");
-    counterClaims.push({ id: `${scope}:${request.providerId}:${input.availability.availableFrom}`, scope, scopeId: request.providerId, periodKey: input.availability.availableFrom, hardLimit: available, amount: requestedCost, release: "settlement-difference", dimension: "cost", unit: request.budget?.cost?.currency ?? "USD" });
-  }
-  for (const native of requestedNative) for (const [scope, available] of [["provider-native", input.providerCapacity.availableNative?.[native.unit]], ["provider-local-native", input.providerLocalLimits.availableNative?.[native.unit]]]) if (available != null) {
-    if (available < native.amount) deny(`${scope}:${native.unit}`, "provider_budget_exhausted");
-    counterClaims.push({ id: `${scope}:${request.providerId}:${input.availability.availableFrom}:${native.unit}`, scope, scopeId: request.providerId, periodKey: native.unit, hardLimit: available, amount: native.amount, release: "settlement-difference", dimension: "native", unit: native.unit });
-  }
-  if (request.mode === "acting") {
-    if (!input.acting?.decisionApproved) deny("acting-decision", "acting_decision_not_approved");
-    else allow("acting-decision");
-    if (!input.acting?.readinessReady) deny("acting-readiness", "acting_readiness_not_ready");
-    else allow("acting-readiness");
-    if (!input.acting?.capacityPlanAccepted) deny("acting-capacity-plan", "acting_capacity_plan_not_accepted");
-    else allow("acting-capacity-plan");
-  }
-  if (remaining <= 0 && !reasons.includes("grant_time_exhausted") && !reasons.includes("workday_budget_exhausted") && !reasons.includes("allocation_hard_cap_exhausted")) reasons.push("allocation_hard_cap_exhausted");
-  const maxReservableSeconds = Number.isFinite(remaining) ? Math.max(0, remaining) : 0;
-  const allowed = reasons.length === 0 && maxReservableSeconds >= request.requestedSeconds;
-  if (!allowed && reasons.length === 0) reasons.push("allocation_hard_cap_exhausted");
-  return {
-    allowed,
-    reasonCode: firstReason(reasons),
-    reasonCodes: reasons,
-    maxReservableSeconds,
-    requiresApproval,
-    allocationPriorityBand,
-    allocationPriorityScore,
-    grantId: grant?.id ?? null,
-    allocationSetId: allocation?.id ?? null,
-    allocationVersion: allocation?.version ?? null,
-    counterClaims,
-    policySnapshot: {
-      allocationSetId: allocation?.id ?? null,
-      allocationVersion: allocation?.version ?? null,
-      grantId: grant?.id ?? null,
-      allocationSliceIds: [...input.allocationSliceIds],
-      requestedSeconds: request.requestedSeconds,
-      budget: request.budget ?? null,
-      laneId: request.laneId ?? null,
-      counterClaims,
-      calculations: allocationCalculations,
-      allocationPriorityBand,
-      allocationPriorityScore
-    },
-    explanation
-  };
-}
-import { evaluateAllocationHierarchy } from "./policy/capacity/allocations/allocation-hierarchy.js";
 export {
-  evaluateCapacityAdmission,
-  firstReason,
-  timestamp,
   validateCapacityAllocationSetV2,
   validateCapacityGrantV2
 };

package/dist/agent-capacity/artifact-mutation-receipt.d.ts

@@ -1,7 +1,7 @@
 export declare const ARTIFACT_MUTATION_RECEIPT_SCHEMA: "treeseed.artifact-mutation-receipt/v1";
 export type ArtifactMutationKind = 'treedx-content' | 'source-checkpoint';
 export type ArtifactMutationPhase = 'provisional' | 'integrated';
-import type { AgentWorkExecutionMode, UpstreamMutationPolicy } from './contracts/support/execution-mode.js';
+import type { AgentWorkExecutionMode, UpstreamMutationPolicy } from './contracts/support/authority/execution-mode.js';
 export interface ArtifactMutationEvidence {
     ref: string;
     digest?: string | null;

package/dist/agent-capacity/artifacts.d.ts

@@ -1,6 +1,5 @@
 import type { ExecutionUsageActual } from '../types/agents.js';
 import type { ResearchCitation } from './contracts/support/research-citation.js';
-import type { ArtifactRef } from '../treedx/types.js';
 import { type ArtifactMutationReceipt } from './artifact-mutation-receipt.js';
 export interface AgentToolEventReference {
     id: string;
@@ -62,6 +61,23 @@ export interface AgentDiagnosticReference {
     retryable?: boolean | null;
     evidenceRef?: string | null;
 }
+export interface ArtifactRef {
+    contract: 'treeseed.artifact-ref/v1';
+    kind: 'treedx-content' | 'repository-file' | 'r2-object' | 'verification-evidence' | 'provider-input' | 'provider-output' | 'citation' | 'source-commit';
+    repositoryId?: string;
+    workspaceId?: string;
+    path?: string;
+    commitSha?: string | null;
+    objectKey?: string;
+    sha256: string | null;
+    byteLength?: number;
+    mediaType?: string;
+    visibility: 'private' | 'assignment' | 'project' | 'team' | 'public';
+    assignmentId?: string;
+    toolCallId?: string;
+    eventId?: string;
+    provenance?: Record<string, string>;
+}
 /** Portable, secret-free terminal evidence emitted by AgentKernel. */
 export interface AgentArtifactManifest {
     schemaVersion: 1;