@treeseed/sdk 0.12.62 → 0.13.0-rc.10

package/dist/governance/groups/contracts.js

@@ -0,0 +1,6 @@
+const GROUP_CONTRACT = "treeseed.group/v1";
+const GROUP_EDGE_CONTRACT = "treeseed.group-edge/v1";
+export {
+  GROUP_CONTRACT,
+  GROUP_EDGE_CONTRACT
+};

package/dist/graph/context-query-contracts.d.ts

@@ -1,15 +1,28 @@
-import type { SdkContextPack, SdkContextPackRequest, SdkGraphQueryStage, SdkGraphQueryView } from '../sdk-types.js';
+import type { SdkContextPack, SdkContextPackRequest, SdkGraphDslRelation, SdkGraphQueryStage, SdkGraphQueryView } from '../entrypoints/models/sdk-types.js';
 export type DeclarativeContextQueryPurpose = 'plan' | 'research' | 'generate' | 'optimize' | 'implement' | 'review' | 'release' | string;
 export type DeclarativeContextQueryFormat = 'summary' | 'full' | 'sources' | 'list' | 'brief' | 'map' | string;
 export interface DeclarativeContextQuery {
     id: string;
+    revision?: number;
+    maturity?: 'draft' | 'validated' | 'simulated' | 'proven';
     purpose: DeclarativeContextQueryPurpose;
     query: string;
+    target?: {
+        kind: 'content' | 'graph' | 'code' | 'mixed';
+        models?: string[];
+        paths?: string[];
+    };
     scope?: string;
     codeScopes?: string[];
     relations?: string[];
     depth?: number;
     budget?: number;
+    resultLimit?: number;
+    contextBudget?: {
+        maxItems: number;
+        maxCharacters?: number;
+    };
+    tokenBudget?: number;
     format?: DeclarativeContextQueryFormat;
     filters?: Record<string, unknown>;
     required?: boolean;
@@ -41,6 +54,11 @@ export interface ResolvedHandlerContextPack {
     pack: SdkContextPack;
     warnings: string[];
 }
+export declare const VALID_RELATIONS: readonly SdkGraphDslRelation[];
+export declare const PURPOSE_TO_STAGE: Partial<Record<string, SdkGraphQueryStage>>;
+export declare const FORMAT_TO_VIEW: Partial<Record<string, SdkGraphQueryView>>;
+export declare function asPositiveInteger(value: unknown): boolean;
+export declare function normalizeString(value: string): string;
 export declare function declarativeContextPurposeToGraphStage(purpose: string): SdkGraphQueryStage;
 export declare function declarativeContextFormatToGraphView(format: string | undefined): SdkGraphQueryView;
 export declare function compileDeclarativeContextQuery(query: DeclarativeContextQuery, options?: {

package/dist/graph/context-query-contracts.js

@@ -22,6 +22,14 @@ const FORMAT_TO_VIEW = {
   list: "list",
   map: "map"
 };
+const FORMAT_TO_CONTEXT_MODE = {
+  summary: "brief",
+  brief: "brief",
+  full: "detailed",
+  sources: "citations",
+  list: "citations",
+  map: "mixed"
+};
 function asPositiveInteger(value) {
   return typeof value === "number" && Number.isInteger(value) && value > 0;
 }
@@ -58,6 +66,8 @@ function compileDeclarativeContextQuery(query, options = {}) {
   if (query.budget !== void 0 && !asPositiveInteger(query.budget)) {
     errors.push(`Context query "${id || "<unknown>"}" budget must be a positive integer.`);
   }
+  if (query.resultLimit !== void 0 && !asPositiveInteger(query.resultLimit)) errors.push(`Context query "${id || "<unknown>"}" resultLimit must be a positive integer.`);
+  if (query.tokenBudget !== void 0 && !asPositiveInteger(query.tokenBudget)) errors.push(`Context query "${id || "<unknown>"}" tokenBudget must be a positive integer.`);
   const scope = query.scope === void 0 ? void 0 : normalizeString(query.scope);
   if (scope !== void 0 && (!scope || !scope.startsWith("/"))) {
     errors.push(`Context query "${id || "<unknown>"}" scope must start with "/".`);
@@ -66,6 +76,28 @@ function compileDeclarativeContextQuery(query, options = {}) {
   if (query.codeScopes !== void 0 && (!Array.isArray(query.codeScopes) || codeScopes.length === 0)) {
     errors.push(`Context query "${id || "<unknown>"}" codeScopes must be a non-empty array of strings.`);
   }
+  const targetPaths = [...new Set((query.target?.paths ?? []).map((entry) => entry.trim()).filter(Boolean))];
+  if (targetPaths.some((entry) => !entry.startsWith("/"))) {
+    errors.push(`Context query "${id || "<unknown>"}" target paths must start with "/".`);
+  }
+  const targetModels = [...new Set((query.target?.models ?? []).map((entry) => entry.trim()).filter(Boolean))];
+  const filterFields = /* @__PURE__ */ new Set(["type", "model", "status", "audience", "directGroupId", "effectiveGroupId", "domain"]);
+  const where = Object.entries(query.filters ?? {}).flatMap(([field, value]) => {
+    if (!filterFields.has(field)) {
+      errors.push(`Context query "${id || "<unknown>"}" filter "${field}" is not supported by TreeDX graph queries.`);
+      return [];
+    }
+    const values = Array.isArray(value) ? value : [value];
+    if (!values.length || values.some((entry) => typeof entry !== "string" || !entry.trim())) {
+      errors.push(`Context query "${id || "<unknown>"}" filter "${field}" must be a string or non-empty string array.`);
+      return [];
+    }
+    const normalized = values.map((entry) => String(entry).trim());
+    return [{ field, op: normalized.length === 1 ? "eq" : "in", value: normalized.length === 1 ? normalized[0] : normalized }];
+  });
+  if (targetModels.length && !Object.hasOwn(query.filters ?? {}, "model")) {
+    where.unshift({ field: "model", op: targetModels.length === 1 ? "eq" : "in", value: targetModels.length === 1 ? targetModels[0] : targetModels });
+  }
   const relations = (query.relations ?? ["related", "references"]).map((entry) => entry.trim().toLowerCase());
   const invalidRelations = relations.filter((relation) => !VALID_RELATIONS.includes(relation));
   if (invalidRelations.length > 0) {
@@ -88,21 +120,25 @@ function compileDeclarativeContextQuery(query, options = {}) {
   }
   const request = {
     query: textQuery,
+    ...targetPaths.length ? { seeds: targetPaths.map((path, index) => ({ id: `target-path-${index + 1}`, kind: "path", value: path, scope: "files" })) } : {},
+    scope: targetModels.length || query.target?.kind === "content" ? "files" : void 0,
     stage,
     relations: uniqueRelations,
     view,
+    mode: FORMAT_TO_CONTEXT_MODE[(query.format ?? "summary").trim().toLowerCase()] ?? "brief",
     options: {
       depth,
-      limit: defaultLimit,
-      maxNodes: defaultLimit
+      limit: query.resultLimit ?? defaultLimit,
+      maxNodes: query.contextBudget?.maxItems ?? query.resultLimit ?? defaultLimit
     }
   };
-  if (scope) {
-    request.scopePaths = [scope];
-  }
-  if (query.budget !== void 0) {
+  const scopePaths = [.../* @__PURE__ */ new Set([...scope ? [scope] : [], ...targetPaths])];
+  if (scopePaths.length) request.scopePaths = scopePaths;
+  if (where.length) request.where = where;
+  if (query.tokenBudget !== void 0 || query.budget !== void 0 || query.contextBudget?.maxItems !== void 0 || query.resultLimit !== void 0) {
     request.budget = {
-      maxTokens: query.budget
+      ...query.tokenBudget !== void 0 || query.budget !== void 0 ? { maxTokens: query.tokenBudget ?? query.budget } : {},
+      maxNodes: query.contextBudget?.maxItems ?? query.resultLimit ?? defaultLimit
     };
   }
   return {
@@ -125,7 +161,12 @@ function compileDeclarativeContextQuery(query, options = {}) {
   };
 }
 export {
+  FORMAT_TO_VIEW,
+  PURPOSE_TO_STAGE,
+  VALID_RELATIONS,
+  asPositiveInteger,
   compileDeclarativeContextQuery,
   declarativeContextFormatToGraphView,
-  declarativeContextPurposeToGraphStage
+  declarativeContextPurposeToGraphStage,
+  normalizeString
 };

package/dist/knowledge/contracts.d.ts

@@ -0,0 +1,173 @@
+export declare const BOOK_SCHEMA_VERSION: "treeseed.book/v2";
+export declare const KNOWLEDGE_PAGE_SCHEMA_VERSION: "treeseed.knowledge-page/v1";
+export declare const BOOK_COLLECTION_SCHEMA_VERSION: "treeseed.book-collection/v1";
+export declare const KNOWLEDGE_PACK_SCHEMA_VERSION: "treeseed.knowledge-pack/v2";
+export declare const EDITORIAL_CONTEXT_SCHEMA_VERSION: "treeseed.editorial-context/v1";
+export declare const KNOWLEDGE_VISIBILITIES: readonly ["public", "authenticated", "team", "project", "admin"];
+export declare const KNOWLEDGE_STATUSES: readonly ["draft", "review", "published", "archived"];
+export type KnowledgeVisibility = (typeof KNOWLEDGE_VISIBILITIES)[number];
+export type KnowledgeStatus = (typeof KNOWLEDGE_STATUSES)[number];
+export type SanitizedKnowledgeHtml = string & {
+    readonly __sanitizedKnowledgeHtml: unique symbol;
+};
+export interface BookDefinition {
+    schemaVersion: typeof BOOK_SCHEMA_VERSION;
+    id: string;
+    slug: string;
+    title: string;
+    summary: string;
+    description: string;
+    status: KnowledgeStatus;
+    visibility: KnowledgeVisibility;
+    order: number;
+    groupIds: string[];
+    audience: string[];
+    relatedBookIds: string[];
+    packPolicy: 'allowed' | 'restricted' | 'disabled';
+    editorialCoreNoteId?: string;
+    cover?: {
+        image?: string;
+        alt?: string;
+    };
+}
+export interface KnowledgeAudienceDeclaration {
+    primary: string[];
+    secondary: string[];
+    excluded: string[];
+}
+export interface KnowledgeContextBindings {
+    capabilityIds: string[];
+    routePatterns: string[];
+    resourceTypes: string[];
+    actionIds: string[];
+    keywords: string[];
+    documentationUrls: string[];
+}
+export interface KnowledgePageDefinition {
+    schemaVersion: typeof KNOWLEDGE_PAGE_SCHEMA_VERSION;
+    id: string;
+    bookId: string;
+    slug: string;
+    title: string;
+    summary: string;
+    status: KnowledgeStatus;
+    visibility: KnowledgeVisibility;
+    order: number;
+    parentId?: string;
+    groupIds: string[];
+    contributors: string[];
+    relatedBookIds: string[];
+    relatedKnowledgeIds: string[];
+    relatedNoteIds: string[];
+    relatedQuestionIds: string[];
+    relatedObjectiveIds: string[];
+    relatedProposalIds: string[];
+    relatedDecisionIds: string[];
+    guaranteeIds: string[];
+    audiences: KnowledgeAudienceDeclaration;
+    context: KnowledgeContextBindings;
+    bodyMarkdown: string;
+    bodyHtml: SanitizedKnowledgeHtml;
+    updatedAt?: string;
+    revision: string;
+    sourcePackage?: string;
+}
+export interface KnowledgePageSummary {
+    id: string;
+    bookId: string;
+    slug: string;
+    title: string;
+    summary: string;
+    visibility: KnowledgeVisibility;
+    status: KnowledgeStatus;
+    audiences: KnowledgeAudienceDeclaration;
+    updatedAt?: string;
+    canonicalPath?: string;
+}
+export interface KnowledgeNavigationEntry extends KnowledgePageSummary {
+    order: number;
+    parentId?: string;
+    revision: string;
+}
+export interface KnowledgeReaderResponse {
+    book: BookDefinition;
+    navigation: KnowledgeNavigationEntry[];
+    page: KnowledgePageDefinition | null;
+    revision: string;
+}
+export interface KnowledgeContextRequest {
+    pageId?: string;
+    capabilityId?: string;
+    routePattern?: string;
+    resourceType?: string;
+    locale?: string;
+    teamId?: string;
+    projectId?: string;
+}
+export interface KnowledgeContextResponse {
+    page: KnowledgePageDefinition;
+    relatedPages: KnowledgePageSummary[];
+    searchScope: KnowledgeVisibility | 'global';
+    revision: string;
+}
+export interface BookCollectionDefinition {
+    schemaVersion: typeof BOOK_COLLECTION_SCHEMA_VERSION;
+    id: string;
+    teamId: string;
+    name: string;
+    summary?: string;
+    bookIds: string[];
+    createdByUserId: string;
+    managed?: boolean;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export type KnowledgePackBuildStatus = 'queued' | 'building' | 'completed' | 'failed' | 'cancelled' | 'expired';
+export interface KnowledgePackArtifact {
+    fileName: string;
+    digest: string;
+    byteSize: number;
+    manifest: KnowledgePackManifest;
+}
+export interface KnowledgePackBuild {
+    id: string;
+    teamId: string;
+    collectionId?: string;
+    requestedByUserId: string;
+    bookIds: string[];
+    sourceClosure?: string;
+    publicationRevision: string;
+    status: KnowledgePackBuildStatus;
+    artifact?: KnowledgePackArtifact;
+    error?: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+}
+export interface KnowledgePackMember {
+    teamId: string;
+    projectId: string;
+    repositoryId: string;
+    commitSha: string;
+    bookId: string;
+    pageIds: string[];
+    digest: string;
+}
+export interface KnowledgePackManifest {
+    schemaVersion: typeof KNOWLEDGE_PACK_SCHEMA_VERSION;
+    id: string;
+    teamId: string;
+    createdAt: string;
+    sourceClosure: string;
+    publicationRevision: string;
+    publicationSourceClosure: string;
+    visibility: KnowledgeVisibility;
+    members: KnowledgePackMember[];
+    files: Array<{
+        path: string;
+        sha256: string;
+        mediaType: string;
+    }>;
+}

package/dist/knowledge/contracts.js

@@ -0,0 +1,16 @@
+const BOOK_SCHEMA_VERSION = "treeseed.book/v2";
+const KNOWLEDGE_PAGE_SCHEMA_VERSION = "treeseed.knowledge-page/v1";
+const BOOK_COLLECTION_SCHEMA_VERSION = "treeseed.book-collection/v1";
+const KNOWLEDGE_PACK_SCHEMA_VERSION = "treeseed.knowledge-pack/v2";
+const EDITORIAL_CONTEXT_SCHEMA_VERSION = "treeseed.editorial-context/v1";
+const KNOWLEDGE_VISIBILITIES = ["public", "authenticated", "team", "project", "admin"];
+const KNOWLEDGE_STATUSES = ["draft", "review", "published", "archived"];
+export {
+  BOOK_COLLECTION_SCHEMA_VERSION,
+  BOOK_SCHEMA_VERSION,
+  EDITORIAL_CONTEXT_SCHEMA_VERSION,
+  KNOWLEDGE_PACK_SCHEMA_VERSION,
+  KNOWLEDGE_PAGE_SCHEMA_VERSION,
+  KNOWLEDGE_STATUSES,
+  KNOWLEDGE_VISIBILITIES
+};

package/dist/knowledge/index.d.ts

@@ -0,0 +1 @@
+export * from './contracts.js';

package/dist/knowledge/index.js

@@ -0,0 +1 @@
+export * from "./contracts.js";

package/dist/model-registry/agent-operational-models.d.ts

@@ -0,0 +1,4 @@
+import type { SdkBuiltinModelName, SdkModelDefinition } from '../entrypoints/models/sdk-types.js';
+type OperationalModelName = Extract<SdkBuiltinModelName, 'agent_context_query' | 'agent_context_query_set' | 'agent_instruction_template' | 'discussion_topic' | 'assignment_plan' | 'assignment_status' | 'assignment_summary' | 'agent_evaluation'>;
+export declare function buildAgentOperationalModelRegistry(repoRoot?: string): Record<OperationalModelName, SdkModelDefinition>;
+export {};

package/dist/model-registry/agent-operational-models.js

@@ -0,0 +1,38 @@
+import path from "node:path";
+import { contentRoot, deriveFieldLists, field, graph } from "./content-root.js";
+function model(input) {
+  return {
+    name: input.name,
+    aliases: input.aliases,
+    storage: "content",
+    operations: ["get", "read", "search", "follow", "pick", "create", "update"],
+    graph: graph({ entityType: input.entityType, titleField: "title", enableSections: true, referenceFields: input.references ?? [] }),
+    fields: input.fields,
+    ...deriveFieldLists(input.fields),
+    pickField: input.fields.updated_at ? "updated_at" : "title",
+    contentCollection: input.collection,
+    contentDir: path.join(contentRoot(input.repoRoot), input.collection)
+  };
+}
+const title = () => field("title", { filterable: true, sortable: true, contentKeys: ["title"], writeContentKey: "title" });
+const id = () => field("id", { filterable: true, contentKeys: ["id"], writeContentKey: "id" });
+const ref = (key, alias) => field(key, { aliases: [alias], filterable: true, contentKeys: [key, alias], writeContentKey: alias });
+const refs = (key, alias) => field(key, { aliases: [alias], filterable: true, comparableAs: "string_array", contentKeys: [key, alias], writeContentKey: alias });
+const updated = () => field("updated_at", { aliases: ["updatedAt"], filterable: true, sortable: true, comparableAs: "date", contentKeys: ["updated_at", "updatedAt"], writeContentKey: "updatedAt" });
+const data = (key, alias = key) => field(key, { aliases: alias === key ? [] : [alias], contentKeys: [key, alias], writeContentKey: alias });
+function buildAgentOperationalModelRegistry(repoRoot) {
+  const lifecycle = { id: id(), title: title(), status: field("status", { filterable: true, contentKeys: ["status"], writeContentKey: "status" }), team_id: ref("team_id", "teamId"), project_id: ref("project_id", "projectId"), workday_id: ref("workday_id", "workdayId"), assignment_id: ref("assignment_id", "assignmentId"), updated_at: updated() };
+  return {
+    agent_context_query: model({ name: "agent_context_query", aliases: ["agent_context_queries"], collection: "agent-context-queries", entityType: "AgentContextQuery", repoRoot, fields: { id: id(), title: title(), description: data("description"), revision: data("revision"), maturity: data("maturity"), purpose: data("purpose"), query: data("query"), target: data("target"), scope: data("scope"), code_scopes: data("code_scopes", "codeScopes"), relations: refs("relations", "relations"), depth: data("depth"), result_limit: data("result_limit", "resultLimit"), context_budget: data("context_budget", "contextBudget"), token_budget: data("token_budget", "tokenBudget"), format: data("format"), filters: data("filters"), required: data("required") } }),
+    agent_context_query_set: model({ name: "agent_context_query_set", aliases: ["agent_context_query_sets"], collection: "agent-context-query-sets", entityType: "AgentContextQuerySet", repoRoot, fields: { id: id(), title: title(), description: data("description"), revision: data("revision"), query_refs: refs("query_refs", "queryRefs"), merge_policy: data("merge_policy", "mergePolicy") }, references: [{ field: "query_refs", edgeType: "REFERENCES", targetModels: ["agent_context_query"], multiple: true }] }),
+    agent_instruction_template: model({ name: "agent_instruction_template", aliases: ["agent_instruction_templates"], collection: "agent-instruction-templates", entityType: "AgentInstructionTemplate", repoRoot, fields: { id: id(), title: title(), description: data("description"), revision: data("revision"), kind: data("kind"), instructions: data("instructions"), output_skeleton: data("output_skeleton", "outputSkeleton"), variables: refs("variables", "variables"), applies_to_profiles: refs("applies_to_profiles", "appliesToProfiles") } }),
+    discussion_topic: model({ name: "discussion_topic", aliases: ["discussion_topics"], collection: "discussion-topics", entityType: "DiscussionTopic", repoRoot, fields: { id: id(), title: title(), description: data("description"), slug: field("slug", { filterable: true, contentKeys: ["slug"], writeContentKey: "slug" }), group_ids: refs("group_ids", "groupIds"), parent_topic_id: ref("parent_topic_id", "parentTopicId"), status: field("status", { filterable: true, contentKeys: ["status"], writeContentKey: "status" }) }, references: [{ field: "parent_topic_id", edgeType: "PARENT_OF", targetModels: ["discussion_topic"] }] }),
+    assignment_plan: model({ name: "assignment_plan", aliases: ["assignment_plans"], collection: "assignment-plans", entityType: "AssignmentPlan", repoRoot, fields: { ...lifecycle, description: data("description"), created_at: data("created_at", "createdAt"), revision: data("revision"), objective: data("objective"), completed: data("completed"), remaining: data("remaining"), risks: data("risks"), resume_state: data("resume_state", "resumeState"), decision_id: ref("decision_id", "decisionId"), capacity_plan_id: ref("capacity_plan_id", "capacityPlanId") } }),
+    assignment_status: model({ name: "assignment_status", aliases: ["assignment_statuses"], collection: "assignment-statuses", entityType: "AssignmentStatus", repoRoot, fields: { ...lifecycle, description: data("description"), created_at: data("created_at", "createdAt"), sequence: data("sequence"), previous_status_ref: data("previous_status_ref", "previousStatusRef"), phase: field("phase", { filterable: true, contentKeys: ["phase"], writeContentKey: "phase" }), reason: data("reason"), progress: data("progress") } }),
+    assignment_summary: model({ name: "assignment_summary", aliases: ["assignment_summaries"], collection: "assignment-summaries", entityType: "AssignmentSummary", repoRoot, fields: { ...lifecycle, description: data("description"), created_at: data("created_at", "createdAt"), summary: data("summary"), lessons: data("lessons"), performance: data("performance"), blockers: data("blockers"), resume_state: data("resume_state", "resumeState"), artifact_refs: refs("artifact_refs", "artifactRefs"), verification_refs: refs("verification_refs", "verificationRefs") } }),
+    agent_evaluation: model({ name: "agent_evaluation", aliases: ["agent_evaluations"], collection: "agent-evaluations", entityType: "AgentEvaluation", repoRoot, fields: { ...lifecycle, description: data("description"), created_at: data("created_at", "createdAt"), agent_id: ref("agent_id", "agentId"), agent_definition_ref: data("agent_definition_ref", "agentDefinitionRef"), activity_profile: data("activity_profile", "activityProfile"), context_query_refs: data("context_query_refs", "contextQueryRefs"), context_query_set_refs: data("context_query_set_refs", "contextQuerySetRefs"), instruction_template_refs: data("instruction_template_refs", "instructionTemplateRefs"), evaluator_id: ref("evaluator_id", "evaluatorId"), outcome: field("outcome", { filterable: true, contentKeys: ["outcome"], writeContentKey: "outcome" }), score: data("score"), criteria: data("criteria") }, references: [{ field: "agent_id", edgeType: "REFERENCES", targetModels: ["agent"] }] })
+  };
+}
+export {
+  buildAgentOperationalModelRegistry
+};

package/dist/model-registry/build-builtin-model-registry.d.ts

@@ -0,0 +1,2 @@
+import type { SdkBuiltinModelName, SdkModelDefinition } from '../entrypoints/models/sdk-types.js';
+export declare function buildBuiltinModelRegistry(repoRoot?: string): Record<SdkBuiltinModelName, SdkModelDefinition>;