@treeseed/sdk 0.13.0-rc.8 → 0.13.0-rc.80

package/README.md

@@ -1,88 +1,10 @@
 # `@treeseed/sdk`
 
-`@treeseed/sdk` is the main programmatic interface for Treeseed content, control-plane state, and graph-first AI context retrieval.
+The operator catalog includes versioned `inbox.*` operations for unified team inbox queries, ordered events, private drafts, routed question creation, and exact-version governance actions.
 
-For most consumers, the right entrypoint is `AgentSdk`.
+`@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.
 
-Use the SDK when you are writing automation, services, scripts, agents, or package internals that need Treeseed data, graph, workflow, config, reconciliation, hosting, package, or TreeDX integration primitives. Use the CLI when you want an operator command. Use Admin when you want a browser UI. Use API when you need the deployed backend service. Use UI when you need reusable components.
-
-## How SDK Fits With Treeseed
-
-The SDK is the shared platform substrate used by:
-
-- `@treeseed/core` for site runtime, content, plugin, and hosting integration
-- `@treeseed/admin` for admin contracts, view models, API facades, and platform primitives
-- `@treeseed/api` for backend contracts, reconciliation, operation state, and shared data models
-- `@treeseed/cli` for workflow, config, hosting, release, and reconciliation commands
-- `@treeseed/agent` for provider runtime consumption of shared contracts
-- root `@treeseed/market` for tenant config, content, and hosted workflow integration
-
-The SDK is not a UI package, admin portal, backend server, CLI parser, capacity-provider runtime, AgentKernel runtime, or ecommerce implementation. See the root [Package Ownership](../../docs/package-ownership.md) guide for the full system map.
-
-The `@treeseed/sdk/account-contracts` export is the canonical portable contract for auth availability, credential/provider results, account identity and sessions, notification capabilities/preferences, and private personal themes. `@treeseed/sdk/platform/plugin` owns the `TreeseedRouteCapability` registry vocabulary consumed by package route registries and generated UI inventories. These contracts contain no UI or backend implementation.
-
-## Which Surface Should I Use?
-
-Treeseed exposes three public SDK surfaces, but they are not peers:
-
-| Surface | Role | Use It For |
-| --- | --- | --- |
-| `AgentSdk` | Primary | application code, workers, scripts, API handlers, graph-first context retrieval |
-| `ScopedAgentSdk` | Operational | agent-runtime code that must enforce model permissions and inject actor identity |
-| `ContentGraphRuntime` | Advanced | low-level graph-only integrations that want the graph engine without the rest of the SDK |
-
-If you are unsure, use `AgentSdk`.
-
-## Major Capability Groups
-
-`AgentSdk` covers five main areas:
-
-- generic model reads and mutations across content-backed models and the static-hub D1 form store
-- operational runtime state such as messages, runs, cursors, and leases
-- control-plane orchestration for work days, tasks, task events, graph runs, and reports
-- provider-neutral capacity and assignment contracts for allocation sets, project agent classes, kernel policy/profile, capacity envelopes, provider sessions, assignments, mode runs, reservations, estimates, checkpoints, and usage actuals
-- hosting graph compilation, deployment readiness, live hosted-service checks, Treeseed runner smoke helpers, and verification cache support for Treeseed workflows
-- graph-first context retrieval through `parseGraphDsl()`, `resolveSeeds()`, `queryGraph()`, and `buildContextPack()`
-- agent scoping through `scopeForAgent()`
-
-## Workflow And Hosting Support
-
-The SDK owns the shared implementation behind the fail-fast `trsd` deployment workflow.
-It also owns the canonical reconciliation platform for desired-state infrastructure. See the root workspace `docs/reconciliation-platform.md` for the full contract.
-
-Current workflow-support exports include:
-
-```ts
-import {
-  collectTreeseedDeploymentReadiness,
-  collectTreeseedLiveHostedServiceChecks,
-  formatTreeseedReadinessReport,
-  runTreeseedOperationsRunnerSmoke,
-} from '@treeseed/sdk/workflow-support';
-```
-
-These helpers are used by:
-
-- `trsd ready <local|staging|prod>`
-- `trsd hosting plan|apply|verify --environment <env> --service <id>`
-- `trsd audit hosting --environment <env> --live`
-- `trsd doctor --live --hosted-services`
-- `trsd operations smoke --environment <env> --service operationsRunner`
-- `trsd stage --verify action|local|none`
-- `trsd release --verify-deployed-resources`
-
-`trsd stage` is branch/ref promotion. It merges `staging` down into the feature branch, runs local proof by default, promotes exact verified refs to staging, and leaves hosted CI/CD/provider repair to the staging release workflow. Hosted reconciliation and live deployed-resource verification remain owned by hosting, release, and explicit verification commands.
-
-For the API app, the expected hosted backend services are the API service, indexed Treeseed operations runner, PostgreSQL, and public TreeDX federation nodes owned by `packages/api`. The root web app remains a web UI and `/v1/*` proxy/client surface, with admin routes contributed by `@treeseed/admin` and visual primitives contributed by `@treeseed/ui`.
-
-Reconciliation guarantees:
-
-- command surfaces compile desired resources before provider mutation
-- cached state can locate resources but live observation proves readiness
-- hosted apply cannot report `ok: true` when live postconditions fail
-- adapter reports use `desiredGraph`, `observedGraph`, `stateGraph`, `diff`, `actions`, `postconditions`, `blockedDrift`, `providerLimitations`, `liveVerification`, and `ok`
-
-Agent capacity architecture is documented in the root workspace [Agent Capacity Implementation Roadmap](../../docs/agent-capacity-implementation-roadmap.md) and [Agent Capacity Domain Model](../../docs/agent-capacity-domain-model.md). SDK owns the portable contracts only; API owns durable coordination records and `@treeseed/agent` owns runtime execution.
+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.
 
 ## Install
 
@@ -90,313 +12,77 @@ Agent capacity architecture is documented in the root workspace [Agent Capacity
 npm install @treeseed/sdk
 ```
 
-Consumer contract:
-
-- Node `>=22`
-- ESM package
-- import from the package root or documented subpath exports
-
-## Quickstart
-
-```ts
-import { AgentSdk } from '@treeseed/sdk/sdk';
-
-const sdk = new AgentSdk({
-  repoRoot: '/absolute/path/to/your-site',
-});
-```
-
-Use `AgentSdk.createLocal()` when you want the local static-hub D1 form store:
-
-```ts
-import { AgentSdk } from '@treeseed/sdk/sdk';
-
-const sdk = AgentSdk.createLocal({
-  repoRoot: '/absolute/path/to/your-site',
-  databaseName: 'treeseed-local',
-  persistTo: '.wrangler/state/v3/d1',
-});
-```
-
-## TreeDX Content Repository
-
-TreeDX is the generic repository service used by Treeseed when TreeDX service configuration is available. The SDK is the Treeseed integration and client layer: it configures the TreeDX portfolio, maps Treeseed model registry behavior onto generic repository/ref/path/frontmatter/body/query requests, and keeps product semantics outside TreeDX. The API package may host public TreeDX federation nodes as part of backend reconciliation.
-
-Project site code and optional project repositories remain local filesystem/git
-workspace concerns by default. Use `contentRepository: { adapter: 'local' }` or
-`AgentSdk.createLocal()` for explicit local content behavior.
-
-See [TreeDX Content Repository](./docs/treedx-content-repository.md).
-
-## Preferred Graph Workflow
-
-The preferred graph API for new integrations is:
-
-1. `parseGraphDsl()`
-2. `queryGraph()`
-3. `buildContextPack()`
-
-Example:
-
-```ts
-import { AgentSdk } from '@treeseed/sdk/sdk';
-
-const sdk = new AgentSdk();
-const parsed = await sdk.parseGraphDsl(
-  'ctx "queue api" for implement in /knowledge via implements,references depth 1 budget 4000 as full',
-);
-
-if (!parsed.ok || !parsed.query) {
-  throw new Error(parsed.errors.join('; '));
-}
-
-const graph = await sdk.queryGraph(parsed.query);
-const pack = await sdk.buildContextPack(parsed.query);
-```
-
-The public `ctx` syntax is:
-
-```text
-ctx <target>
-  [for <focus>]
-  [in <scope>]
-  [via <relation[,relation...]>]
-  [depth <0-3>]
-  [where <filter-expression>]
-  [limit <n>]
-  [budget <tokens>]
-  [as <list|brief|full|map>]
-```
-
-The old `key=value` graph DSL is no longer supported.
+Requirements: Node.js 22 or newer and ESM.
 
-## TreeDX Remote Repository Mode
-
-TreeDX support is opt-in. Local SDK behavior remains the default.
-
-Use the low-level TreeDX client when you want direct repository, workspace, query, graph, registry, or context calls:
+## Control-plane API
 
 ```ts
-import { TreeDxClient } from '@treeseed/sdk/treedx';
+import {
+  ControlPlaneClient,
+  defaultLocalControlPlaneServer,
+} from '@treeseed/sdk/control-plane-client';
+import { CONTROL_PLANE_OPERATIONS } from '@treeseed/sdk/operator-contracts';
 
-const treeDx = new TreeDxClient({
-  baseUrl: 'http://localhost:4000',
-  token: process.env.TREEDX_TOKEN,
-  repoId: 'repo_123',
+const client = new ControlPlaneClient({
+  profile: defaultLocalControlPlaneServer(),
+  accessToken: process.env.TREESEED_ACCESS_TOKEN,
 });
 
-const whoami = await treeDx.whoami();
-const file = await treeDx.readRepositoryFile({
-  path: 'docs/readme.md',
-  parseFrontmatter: true,
+const health = await client.invoke(CONTROL_PLANE_OPERATIONS.health.readiness, {
+  path: {},
+  query: {},
+  body: undefined,
 });
 ```
 
-`AgentSdk` can delegate content-backed model and graph calls to TreeDX when configured explicitly:
+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.
 
-```ts
-import { AgentSdk, TreeDxClient } from '@treeseed/sdk';
-
-const treeDx = new TreeDxClient({
-  baseUrl: 'http://localhost:4000',
-  token: process.env.TREEDX_TOKEN,
-  repoId: 'repo_123',
-});
-
-const sdk = new AgentSdk({
-  repoRoot: process.cwd(),
-  treeDx: {
-    enabled: true,
-    client: treeDx,
-    repoId: 'repo_123',
-    defaultRef: 'refs/heads/main',
-  },
-});
-
-const docs = await sdk.search({
-  model: 'knowledge',
-  filters: [{ field: 'status', op: 'eq', value: 'published' }],
-});
-```
+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 mode keeps TreeSeed model semantics in the SDK model registry. TreeDX receives generic repository/ref/path/frontmatter/body/query requests and returns generic repository/file/query/graph results.
-
-TreeDX auth, policy, audit, and federation helpers are available on the same client:
+## TreeDX API
 
 ```ts
-const mode = await treeDx.authMode();
-const scope = await treeDx.effectiveScope({ repoId: 'repo_123' });
-
-await treeDx.putCapabilityGrant({
-  actorId: 'actor_agent',
-  tenantId: 'tenant_demo',
-  repoIds: ['repo_123'],
-  capabilities: ['files:read', 'files:search'],
-  refs: ['refs/heads/main'],
-  paths: ['docs/**'],
-});
+import { ControlPlaneClient } from '@treeseed/sdk/control-plane-client';
+import { TreeSeedTreeDxClient } from '@treeseed/sdk/treedx';
 
-const audit = await treeDx.listAuditEvents({
-  repoId: 'repo_123',
-  eventType: 'repo.query_executed',
-  limit: 25,
+const controlPlane = new ControlPlaneClient({
+  profile: defaultLocalControlPlaneServer(),
+  accessToken: process.env.TREESEED_ACCESS_TOKEN,
 });
+const treeDx = new TreeSeedTreeDxClient(controlPlane);
 
-const plan = await treeDx.planFederatedQuery({
-  repoIds: ['repo_123'],
-  capabilities: ['files:search'],
-  paths: { repo_123: ['docs/**'] },
-});
-
-const search = await treeDx.federatedSearch({
-  repoIds: ['repo_123'],
-  refs: { repo_123: 'refs/heads/main' },
-  paths: { repo_123: ['docs/**'] },
-  query: 'release',
-  includeErrors: true,
+const result = await treeDx.proxy.repositories.searchFiles({
+  path: { projectId: 'project_123', repositoryId: 'repository_123' },
+  query: { query: 'release' },
+  body: undefined,
 });
 ```
 
-Federation planning performs scope reduction before execution. The SDK delegates global execution to TreeDX instead of fanning out across every node and filtering locally.
-
-Snapshot, artifact, mirror sync, and migration helpers are also available on `TreeDxClient`:
-
-```ts
-const snapshot = await treeDx.buildSnapshot({
-  ref: 'refs/heads/main',
-  kind: 'repository_snapshot',
-  paths: ['docs/**'],
-  includeGraph: true,
-});
-
-const artifact = await treeDx.exportArtifact({
-  snapshotId: snapshot.snapshotId,
-});
+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.
 
-const download = await treeDx.downloadArtifact({
-  snapshotId: snapshot.snapshotId,
-});
+## Public boundaries
 
-await treeDx.syncMirror({
-  mirrorId: 'mirror_123',
-  remoteName: 'origin',
-});
+The package intentionally exposes only:
 
-await treeDx.createMigration({
-  targetNodeId: 'node_mirror',
-  mode: 'primary_transfer',
-  planOnly: true,
-  requireMirrorSynced: false,
-});
+- standards and semantic-compatibility contracts for TypeScript, OpenAPI, and MCP;
+- the control-plane operation catalog and human-centered command/workday contracts;
+- control-plane, TreeDX, and capacity-provider remote clients;
+- portable account, knowledge, feedback, content, agent, capacity, provider, secret-capability, and graph request contracts;
+- deterministic validation that belongs to those wire contracts.
 
-await treeDx.ready();
-await treeDx.deepHealth();
-await treeDx.metrics();
-```
+There is no root catch-all export. Import a documented subpath so ownership and compatibility remain explicit.
 
-`downloadArtifact()` returns an `ArrayBuffer` plus content type, filename, checksum, and snapshot headers. These APIs are generic TreeDX repository operations; TreeSeed package or release semantics are not encoded in TreeDX.
-
-Mocked end-to-end TreeDX contract tests prove the SDK can drive the TreeDX repository loop without an agent-side clone when `contentPathMap` is supplied:
+## Verification
 
 ```bash
-npx vitest run --config ./vitest.config.ts tests/contract/treedx/treedx-e2e-contract.test.ts
-```
-
-The optional live contract command reports `not configured` and exits
-successfully unless all of these are set:
-
-```text
-TREEDX_LIVE_URL
-TREEDX_LIVE_TOKEN
-TREEDX_LIVE_REPO_ID
-```
-
-## Capacity Scheduling Contracts
-
-The SDK owns the provider-neutral capacity runtime helpers used by the agent manager, workers, and market control plane. These helpers keep work estimation separate from provider cost by normalizing `taskSignature + executionProfileId` estimates, then routing against grants, provider lanes, quality requirements, quota/congestion pressure, attention/context saturation, utility, predictive reserve, and hybrid execution metadata.
-
-Capacity records remain metadata-compatible: advanced scheduling data lives in task payload JSON, routing decision candidates/scores, reservation metadata, capacity plan metadata, checkpoint artifacts, and usage actual metadata. Missing metadata is neutral, so older callers continue to use the credit-only behavior.
-
-## Shared Fixture Support
-
-SDK also owns the shared fixture support model used across the Treeseed workspace.
-
-That support layer is responsible for:
-
-- resolving the canonical shared fixture in `.fixtures/treeseed-fixtures`
-- preparing fixture-local package visibility for package-scoped verification
-- linking real workspace or installed packages into the fixture runtime when available
-- providing the canonical `contracts-only` Agent shim used by packages such as `core` during isolated verification
-
-The shared fixture is an integrated Treeseed project, but package verification remains package-scoped. SDK owns the tooling that lets other packages validate their own slice of that project without mutating the fixture itself.
-
-## Advanced Graph Methods
-
-The SDK also exposes lower-level graph primitives such as:
-
-- `searchFiles()`
-- `searchSections()`
-- `searchEntities()`
-- `getGraphNode()`
-- `getNeighbors()`
-- `followReferences()`
-- `getBacklinks()`
-- `getRelated()`
-- `getSubgraph()`
-- `refreshGraph()`
-
-These remain public, but they are considered advanced tools. Prefer the graph-first context workflow above unless you specifically need raw lexical search or raw traversal primitives.
-
-## `ScopedAgentSdk`
-
-Use `scopeForAgent()` when code must enforce an agent’s declared permissions:
-
-```ts
-const scoped = sdk.scopeForAgent({
-  slug: 'guide-agent',
-  permissions: [
-    { model: 'knowledge', operations: ['get', 'read', 'search'] },
-    { model: 'message', operations: ['create'] },
-  ],
-});
+npm test
+npm run verify:direct
 ```
 
-`ScopedAgentSdk` is intended for manager/worker and agent-runtime code. It is not the default application entrypoint.
-
-## `ContentGraphRuntime`
-
-`ContentGraphRuntime` is still exported, but it is an advanced graph runtime:
-
-- it powers the graph subsystem behind `AgentSdk`
-- it is useful when you want only graph behavior
-- it is not the recommended starting point for most applications
-
-## Reference Docs
-
-- [SDK Interface Reference](../../src/content/knowledge/sdk/interface-reference.mdx)
-- [Graph API Guide](../../src/content/knowledge/sdk/graph-api-guide.mdx)
-- [ctx Query Language](../../src/content/knowledge/sdk/ctx-query-language.mdx)
-- [How ctx Works](../../src/content/knowledge/sdk/ctx-query-engine.mdx)
-
-## Other Public Capabilities
-
-The package also exports:
+The release gate builds only the package export closure, verifies deterministic contract artifacts, checks the packed public boundary, and runs the focused contract/client suite. Removed implementation and lifecycle suites are not executed.
 
-- workflow helpers such as `TreeseedWorkflowSdk`
-- remote clients such as `RemoteTreeseedClient`
-- model registry, field, and filter utilities
-- plugin/runtime types and helpers
+## Versioning
 
-For package work:
+Contract removals, input or output narrowing, scope escalation, risk escalation, and incompatible REST or MCP surface changes are breaking. Compatible additions require a minor version; contract-preserving repairs require a patch. Prerelease consumers pin an exact immutable version.
 
-```bash
-npm install
-npm run build
-npm test
-```
-
-For fixture-specific work:
-
-```bash
-npm run fixtures:check
-```
+License: Apache-2.0.

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

@@ -0,0 +1 @@
+{"completedAt":"2026-09-02T09:32:30.488Z"}

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;
@@ -167,4 +173,4 @@ export interface PersonalTheme extends PersonalThemeDraft {
 export declare const PERSONAL_THEME_COMPILER_VERSION = 1;
 export declare function normalizeNotificationPreferences(input: Partial<NotificationPreferences> | null | undefined): NotificationPreferences;
 export declare function isValidPersonalThemeDraft(input: unknown): input is PersonalThemeDraft;
-import type { ApiPrincipal } from '../entrypoints/clients/remote.js';
+import type { ApiPrincipal } from '../operator-contracts/oauth.js';

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;

package/dist/agent-capacity/authority/agent-authority-presets.d.ts

@@ -8,6 +8,6 @@ export interface CompiledAgentAuthoritySnapshot {
     branchPolicy: AgentActivityProfile['branchPolicy'];
     diagnostics: string[];
 }
-export declare function defaultAgentAuthorityPresets(activityType: AgentActivityType): ("messaging" | "direction" | "influence" | "estimation" | "plan-contribution" | "source-execution" | "review-authority" | "reporting")[];
+export declare function defaultAgentAuthorityPresets(activityType: AgentActivityType): ("reporting" | "messaging" | "direction" | "influence" | "estimation" | "plan-contribution" | "source-execution" | "review-authority")[];
 export declare function compileAgentAuthoritySnapshot(activityType: AgentActivityType, profile: AgentActivityProfile): CompiledAgentAuthoritySnapshot;
 export declare function allowedSafetyModesForActivity(activityType: AgentActivityType): Array<'planning' | 'acting'>;

package/dist/agent-capacity/authority/agent-authority-presets.js

@@ -18,6 +18,7 @@ const CHAT_ALLOWED_TOOLS = /* @__PURE__ */ new Set([
   ...OPERATIONAL_TOOLS,
   ...MESSAGING_TOOLS,
   ...CONTENT_TOOLS,
+  ...SOURCE_READ_TOOLS,
   "treedx.build_context",
   "treedx.read_repository_files",
   "treedx.search_workspace",
@@ -32,7 +33,7 @@ const PROFILE_PRESETS = {
   acting: ["source-execution", "influence"],
   reviewing: ["review-authority", "plan-contribution"],
   reporting: ["messaging", "reporting"],
-  chat: ["influence"]
+  chat: ["review-authority"]
 };
 function toolsForPreset(preset) {
   if (preset === "messaging") return MESSAGING_TOOLS;