@treeseed/sdk 0.12.62 → 0.13.0-rc.10

package/dist/treedx/types.js

@@ -1,8 +1,7 @@
-function assertTreeDxOk(value, label = "TreeDX response") {
-  if (typeof value !== "object" || value === null || Array.isArray(value) || value.ok !== true) {
-    throw new Error(`${label} was not an ok TreeDX response.`);
-  }
-}
-export {
-  assertTreeDxOk
-};
+export * from "./types/tree-dx-actor.js";
+export * from "./types/tree-dx-artifact-list-response.js";
+export * from "./types/tree-dx-context-request.js";
+export * from "./types/tree-dx-changeset.js";
+export * from "./types/tree-dx-exec-result.js";
+export * from "./types/tree-dx-list-tree-request.js";
+export * from "./types/tree-dx-push-request.js";

package/dist/types/agents/agent-activity-profile.d.ts

@@ -0,0 +1,267 @@
+import { AgentActivityExecutionConfig, AgentActivityPermissions, AgentActivityPlanningIntent, AgentActivityPromptConfig, AgentActivityType, AgentBranchPolicy, AgentOutputContract, AgentQuestionPolicy, AgentSignalPolicy, AgentToolPolicy, EngineeringHandlerKind, ExecutionProviderKind, ExecutionProviderPressure, ExecutionProviderQuotaVisibility, ExecutionResourceNeedKind } from './agent-trigger-kinds.js';
+import type { AgentAuthorityPresetId } from '../../agent-capacity/authority/agent-authority-presets.js';
+export interface AgentContentRevisionRef {
+    id: string;
+    revision: number;
+}
+export interface AgentActivityProfile {
+    activityType?: AgentActivityType;
+    enabled: boolean;
+    handler: EngineeringHandlerKind;
+    prompt: AgentActivityPromptConfig;
+    branchPolicy: AgentBranchPolicy;
+    permissions?: AgentActivityPermissions;
+    authorityPresets?: AgentAuthorityPresetId[];
+    contextQueryRefs?: AgentContentRevisionRef[];
+    contextQuerySetRefs?: AgentContentRevisionRef[];
+    instructionTemplateRefs?: AgentContentRevisionRef[];
+    artifactTriggers?: Array<{
+        event: string;
+        artifactKind: string;
+        model?: string;
+        required?: boolean;
+    }>;
+    closeoutPolicy?: {
+        warningSeconds?: number;
+        summaryRequired?: boolean;
+        requiredArtifactKinds?: string[];
+        blockOnOpenQuestions?: boolean;
+    };
+    providerOverrides?: {
+        requiredCapabilities?: string[];
+        disallowedProviderIds?: string[];
+        promptRef?: string;
+        instructionTemplateRefs?: AgentContentRevisionRef[];
+        maxRuntimeSeconds?: number;
+        maxTotalTokens?: number;
+        maxCostAmount?: number;
+    };
+    tools: AgentToolPolicy;
+    signals?: AgentSignalPolicy;
+    outputs: AgentOutputContract;
+    planningIntent?: AgentActivityPlanningIntent;
+    questionPolicy?: AgentQuestionPolicy;
+    execution?: AgentActivityExecutionConfig;
+}
+export type AgentActivityProfilesConfiguration = Partial<Record<AgentActivityType, AgentActivityProfile>>;
+export interface AgentChatProfileConfiguration {
+    foundation: 'discussion-v1';
+    responseStyle?: string;
+    promptTask?: string;
+    requiredCapabilities?: string[];
+    maxRuntimeSeconds?: number;
+    maxTotalTokens?: number;
+    warningTokens?: number;
+    maxCostAmount?: number;
+    costCurrency?: string;
+    toolAdditions?: string[];
+    contextModels?: string[];
+}
+export interface AgentCapability {
+    id: string;
+    description?: string;
+    produces?: string[];
+    requires?: string[];
+    reviews?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface AgentDefinitionIdentity {
+    purpose: string;
+    responsibilities: string[];
+    durableInstructions: string;
+}
+export interface AgentDefinition {
+    slug: string;
+    title: string;
+    agentClass: string;
+    template?: string;
+    identity: AgentDefinitionIdentity;
+    capabilities: AgentCapability[];
+    activityProfiles: Partial<Record<AgentActivityType, AgentActivityProfile>>;
+    chatProfile?: AgentChatProfileConfiguration;
+}
+export interface AgentExecutionConfig {
+    provider?: string;
+    model?: string;
+    approvalPolicy?: 'never' | 'on_request' | 'always' | string;
+    sandboxMode?: 'read_only' | 'workspace_write' | string;
+    reasoningEffort?: 'low' | 'medium' | 'high' | string;
+    allowedPaths?: string[];
+    forbiddenPaths?: string[];
+    worktree?: {
+        enabled?: boolean;
+        root?: string;
+        branchPrefix?: string;
+    };
+    maxConcurrency: number;
+    timeoutSeconds: number;
+    cooldownSeconds: number;
+    leaseSeconds: number;
+    retryLimit: number;
+    branchPrefix: string;
+    providerProfile?: AgentProviderProfile;
+}
+export type AgentProviderFallbackPolicy = 'allow_substitution' | 'require_same_model_class' | 'fail_if_unavailable' | 'ask_for_approval';
+export interface AgentExecutionProviderPreference {
+    providerId?: string;
+    provider?: string;
+    model?: string;
+    modelClass?: string;
+    weight: number;
+    reason?: string;
+}
+export interface AgentProviderFallback {
+    providerId?: string;
+    provider?: string;
+    model?: string;
+    modelClass?: string;
+    maxQualityPenalty?: number;
+}
+export interface AgentProviderProfile {
+    requiredCapabilities: string[];
+    preferredExecutionProviders: AgentExecutionProviderPreference[];
+    acceptableFallbacks: AgentProviderFallback[];
+    disallowedProviders?: string[];
+    disallowedRegions?: string[];
+    fallbackPolicy: AgentProviderFallbackPolicy;
+}
+export interface ExecutionResourceNeed {
+    kind: ExecutionResourceNeedKind;
+    operations: string[];
+    paths?: string[];
+    required?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionCapabilityDemand {
+    required: string[];
+    preferred?: string[];
+    mode: 'planning' | 'acting';
+    resourceNeeds?: ExecutionResourceNeed[];
+    outputTypes?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionCapabilitySupply {
+    capacityProviderId: string;
+    executionProviderId: string;
+    kind: ExecutionProviderKind;
+    capabilities: string[];
+    aliases?: string[];
+    grants: string[];
+    availability?: Record<string, unknown>;
+    pressure?: ExecutionProviderPressure;
+    maxConcurrentAssignments?: number;
+    nativeUnit?: string;
+    quotaVisibility?: ExecutionProviderQuotaVisibility;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentExpectedOutput {
+    type: string;
+    required: boolean;
+    description?: string;
+    schema?: Record<string, unknown>;
+}
+export interface AgentWorkPackageConstraints {
+    mode: 'planning' | 'acting';
+    requiredCapabilities: string[];
+    allowedPaths?: string[];
+    forbiddenPaths?: string[];
+    allowedOperations?: string[];
+    deadline?: string | null;
+    maxAttempts?: number | null;
+    metadata?: Record<string, unknown>;
+}
+export type AgentHandlerAlgorithmKind = EngineeringHandlerKind;
+export type AgentWorkPackageKind = AgentHandlerAlgorithmKind | string;
+export interface AgentInputSelector {
+    source: string;
+    path?: string;
+    required?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentOutputTemplate {
+    type: string;
+    template?: string;
+    required?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentReviewCriterion {
+    id: string;
+    description: string;
+    required?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentPlanningPolicy {
+    prioritization?: string;
+    maxCandidates?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentReportTemplate {
+    kind: string;
+    title?: string;
+    sections?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface AgentHandlerConfig {
+    workPackageKind?: AgentWorkPackageKind;
+    domain?: string;
+    inputSelectors?: AgentInputSelector[];
+    outputTemplates?: AgentOutputTemplate[];
+    reviewCriteria?: AgentReviewCriterion[];
+    planningPolicy?: AgentPlanningPolicy;
+    reportTemplate?: AgentReportTemplate;
+    delegation?: {
+        required?: boolean;
+        allowedProviderKinds?: string[];
+        reason?: string;
+    };
+    resourceNeeds?: ExecutionResourceNeed[];
+    metadata?: Record<string, unknown>;
+}
+export interface AgentWorkPackage {
+    kind: AgentWorkPackageKind;
+    title: string;
+    summary: string;
+    instructions: string;
+    context: Record<string, unknown>;
+    expectedOutputs: AgentExpectedOutput[];
+    constraints: AgentWorkPackageConstraints;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionProviderDescriptor {
+    id: string;
+    kind: ExecutionProviderKind;
+    capabilities: string[];
+    capabilityAliases?: string[];
+    nativeUnit: string;
+    quotaVisibility: ExecutionProviderQuotaVisibility;
+    maxConcurrentAssignments: number;
+    supportsAsync: boolean;
+    supportsCancel: boolean;
+    supportsResume: boolean;
+    supportsUsage: boolean;
+    supportsArtifacts: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionProviderObserveInput {
+    capacityProviderId?: string | null;
+    executionProviderId?: string | null;
+    runnerId?: string | null;
+    activeAssignmentIds?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionProviderObservation {
+    descriptor?: ExecutionProviderDescriptor;
+    supply?: ExecutionCapabilitySupply;
+    pressure?: ExecutionProviderPressure;
+    available?: boolean;
+    activeAssignmentCount?: number;
+    blockedReason?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface ExecutionPreparationResult {
+    accepted: boolean;
+    summary: string;
+    retryable?: boolean;
+    code?: string | null;
+    metadata?: Record<string, unknown>;
+}

package/dist/types/agents/agent-trigger-kinds.d.ts

@@ -0,0 +1,189 @@
+export declare const AGENT_TRIGGER_KINDS: readonly ["schedule", "message", "follow", "startup"];
+export declare const AGENT_PERMISSION_OPERATIONS: readonly ["get", "read", "search", "follow", "pick", "create", "update"];
+export declare const AGENT_MESSAGE_STATUSES: readonly ["pending", "claimed", "completed", "failed", "dead_letter"];
+export declare const AGENT_RUN_STATUSES: readonly ["running", "completed", "failed", "waiting"];
+export declare const AGENT_HANDLER_KINDS: readonly ["writer", "actor", "estimate", "releaser", "reporter"];
+export declare const AGENT_ACTIVITY_TYPES: readonly ["planning", "estimating", "acting", "reviewing", "reporting", "chat"];
+export declare const ENGINEERING_HANDLER_KINDS: readonly ["writer", "actor", "estimate", "releaser", "reporter"];
+export declare const AGENT_CLI_ALLOW_TOOLS: readonly ["shell(git)", "shell(npm)", "web"];
+export declare const EXECUTION_RESOURCE_NEED_KINDS: readonly ["repository", "treedx_workspace", "workflow", "secret", "external_issue", "external_job"];
+export declare const EXECUTION_PROVIDER_KINDS: readonly ["ai_model", "human_issue_queue", "deterministic_workflow", "local_process"];
+export declare const BUILT_IN_AGENT_EXECUTION_PROVIDER_IDS: readonly ["codex", "opencode", "copilot", "jira", "github_issues", "discord", "workflow", "platform-operation"];
+export declare const EXECUTION_RUN_STATUSES: readonly ["accepted", "running", "waiting", "blocked", "completed", "returned", "failed", "cancelled"];
+export declare const EXECUTION_PROVIDER_PRESSURE_STATES: readonly ["idle", "normal", "busy", "throttled", "exhausted"];
+export declare const EXECUTION_PROVIDER_QUOTA_VISIBILITIES: readonly ["opaque", "partial", "exact"];
+export type AgentTriggerKind = (typeof AGENT_TRIGGER_KINDS)[number];
+export type AgentPermissionOperation = (typeof AGENT_PERMISSION_OPERATIONS)[number];
+export type AgentMessageStatus = (typeof AGENT_MESSAGE_STATUSES)[number];
+export type AgentRunStatus = (typeof AGENT_RUN_STATUSES)[number];
+export type AgentHandlerKind = string;
+export type AgentActivityType = (typeof AGENT_ACTIVITY_TYPES)[number];
+export type EngineeringHandlerKind = (typeof ENGINEERING_HANDLER_KINDS)[number];
+export type AgentCliAllowTool = (typeof AGENT_CLI_ALLOW_TOOLS)[number];
+export type ExecutionResourceNeedKind = (typeof EXECUTION_RESOURCE_NEED_KINDS)[number] | string;
+export type ExecutionProviderKind = (typeof EXECUTION_PROVIDER_KINDS)[number] | string;
+export type BuiltInAgentExecutionProviderId = (typeof BUILT_IN_AGENT_EXECUTION_PROVIDER_IDS)[number];
+export type ExecutionRunStatus = (typeof EXECUTION_RUN_STATUSES)[number];
+export type ExecutionProviderPressure = (typeof EXECUTION_PROVIDER_PRESSURE_STATES)[number];
+export type ExecutionProviderQuotaVisibility = (typeof EXECUTION_PROVIDER_QUOTA_VISIBILITIES)[number];
+export interface AgentTriggerConfig {
+    type: AgentTriggerKind;
+    cron?: string;
+    messageTypes?: string[];
+    models?: string[];
+    sinceField?: string;
+    runOnStart?: boolean;
+}
+export interface AgentPermissionConfig {
+    model: string;
+    operations: AgentPermissionOperation[];
+}
+export interface AgentExecutionBoundaryPolicy {
+    repository?: {
+        readPaths?: string[];
+        writePaths?: string[];
+        allowCodeMutation?: boolean;
+    };
+    network?: {
+        allowWeb?: boolean;
+        allowedDomains?: string[];
+    };
+    shell?: {
+        allowCommands?: boolean;
+        allowedCommands?: string[];
+        deniedCommands?: string[];
+    };
+}
+export interface AgentOutputContract {
+    messageTypes: string[];
+    modelMutations: string[];
+}
+export interface AgentSignalSubscription {
+    contract: string;
+    groupScope?: import('../../governance/groups/contracts.js').SignalGroupScope;
+    filters?: Record<string, unknown>;
+    cardinality?: 'single' | 'each';
+    producerPolicy?: 'any' | 'all' | 'quorum';
+    quorum?: number;
+}
+export interface AgentSignalPolicy {
+    subscribesTo?: AgentSignalSubscription[];
+    publishes?: string[];
+}
+export interface AgentToolPolicy {
+    allowed: string[];
+    denied?: string[];
+}
+export interface AgentContentScope {
+    models: string[];
+    actions?: import('../../content/contracts.js').ContentAction[];
+    books?: string[];
+    paths?: string[];
+    relations?: string[];
+}
+export interface AgentContentAccessPolicy {
+    read?: AgentContentScope;
+    write?: AgentContentScope;
+    commit?: {
+        allowed: boolean;
+    };
+}
+export interface AgentActivityPermissions {
+    content?: Record<string, {
+        operations: import('../../content/contracts.js').ContentAction[];
+        filters?: Record<string, unknown>;
+    }>;
+    commit?: {
+        allowed: boolean;
+    };
+    repository?: AgentExecutionBoundaryPolicy['repository'];
+    network?: AgentExecutionBoundaryPolicy['network'];
+    shell?: AgentExecutionBoundaryPolicy['shell'];
+}
+export type AgentBranchPolicy = {
+    kind: 'read-only';
+    base: 'main' | 'staging';
+} | {
+    kind: 'main-planning-content';
+    base: 'main';
+} | {
+    kind: 'staging-content';
+    base: 'staging';
+} | {
+    kind: 'assignment-feature';
+    base: 'staging';
+    target: 'staging';
+    prefix?: string;
+    branchNameTemplate?: string;
+    worktree?: 'new' | 'reuse';
+    updateBaseBeforeRun?: boolean;
+    mergeTargetBeforeSave?: boolean;
+} | {
+    kind: 'staging-release';
+    base: 'staging';
+    target: 'main';
+};
+export type AgentQuestionAnswerPolicy = {
+    kind: 'team-human';
+    teamId?: string;
+    requiredRoles?: string[];
+} | {
+    kind: 'human-or-agent';
+    teamId?: string;
+    allowedRoles?: string[];
+    allowedAgentIds?: string[];
+    allowedAgentClasses?: string[];
+    allowedActivityProfiles?: string[];
+} | {
+    kind: 'specific-human';
+    teamMemberId: string;
+} | {
+    kind: 'specific-agent';
+    projectId: string;
+    agentSlug: string;
+};
+export interface AgentQuestionPolicy {
+    defaultAnswerPolicy?: AgentQuestionAnswerPolicy;
+    blockExecutionWhenCreated?: boolean;
+}
+export interface AgentActivityPromptConfig {
+    system: string;
+    task?: string;
+    templates?: Record<string, string>;
+}
+export interface AgentActivityExecutionConfig {
+    requiredCapabilities?: string[];
+    maxRuntimeSeconds?: number;
+    closeoutWarningSeconds?: number;
+    maxRetries?: number;
+    verificationRequired?: boolean;
+    maxTotalTokens?: number;
+    warningTokens?: number;
+    maxCostAmount?: number;
+    costCurrency?: string;
+    nativeLimits?: Array<{
+        unit: string;
+        amount: number;
+        enforceable?: boolean;
+    }>;
+    pricingGeneration?: string;
+    enforcementConfidence?: 'exact' | 'bounded' | 'estimated' | 'opaque';
+    allowedPaths?: string[];
+    forbiddenPaths?: string[];
+}
+export interface AgentActivityPlanningIntent {
+    objective?: string;
+    proposalTypes?: string[];
+    artifactKind?: string;
+    subjectModel?: string;
+    subjectId?: string | null;
+    includeWorkdayArtifacts?: boolean;
+    stage?: 'discovery' | 'synthesis' | 'deliberation' | 'evaluation' | 'revision' | 'closeout';
+    stages?: Array<{
+        stage: 'discovery' | 'synthesis' | 'deliberation' | 'evaluation' | 'revision' | 'closeout';
+        promptTask?: string;
+        signals?: AgentSignalPolicy;
+    }>;
+    requiresArtifactKinds?: string[];
+    proposalTypes?: string[];
+}

package/dist/types/agents/agent-trigger-kinds.js

@@ -0,0 +1,107 @@
+const AGENT_TRIGGER_KINDS = ["schedule", "message", "follow", "startup"];
+const AGENT_PERMISSION_OPERATIONS = [
+  "get",
+  "read",
+  "search",
+  "follow",
+  "pick",
+  "create",
+  "update"
+];
+const AGENT_MESSAGE_STATUSES = [
+  "pending",
+  "claimed",
+  "completed",
+  "failed",
+  "dead_letter"
+];
+const AGENT_RUN_STATUSES = ["running", "completed", "failed", "waiting"];
+const AGENT_HANDLER_KINDS = [
+  "writer",
+  "actor",
+  "estimate",
+  "releaser",
+  "reporter"
+];
+const AGENT_ACTIVITY_TYPES = [
+  "planning",
+  "estimating",
+  "acting",
+  "reviewing",
+  "reporting",
+  "chat"
+];
+const ENGINEERING_HANDLER_KINDS = [
+  "writer",
+  "actor",
+  "estimate",
+  "releaser",
+  "reporter"
+];
+const AGENT_CLI_ALLOW_TOOLS = [
+  "shell(git)",
+  "shell(npm)",
+  "web"
+];
+const EXECUTION_RESOURCE_NEED_KINDS = [
+  "repository",
+  "treedx_workspace",
+  "workflow",
+  "secret",
+  "external_issue",
+  "external_job"
+];
+const EXECUTION_PROVIDER_KINDS = [
+  "ai_model",
+  "human_issue_queue",
+  "deterministic_workflow",
+  "local_process"
+];
+const BUILT_IN_AGENT_EXECUTION_PROVIDER_IDS = [
+  "codex",
+  "opencode",
+  "copilot",
+  "jira",
+  "github_issues",
+  "discord",
+  "workflow",
+  "platform-operation"
+];
+const EXECUTION_RUN_STATUSES = [
+  "accepted",
+  "running",
+  "waiting",
+  "blocked",
+  "completed",
+  "returned",
+  "failed",
+  "cancelled"
+];
+const EXECUTION_PROVIDER_PRESSURE_STATES = [
+  "idle",
+  "normal",
+  "busy",
+  "throttled",
+  "exhausted"
+];
+const EXECUTION_PROVIDER_QUOTA_VISIBILITIES = [
+  "opaque",
+  "partial",
+  "exact"
+];
+export {
+  AGENT_ACTIVITY_TYPES,
+  AGENT_CLI_ALLOW_TOOLS,
+  AGENT_HANDLER_KINDS,
+  AGENT_MESSAGE_STATUSES,
+  AGENT_PERMISSION_OPERATIONS,
+  AGENT_RUN_STATUSES,
+  AGENT_TRIGGER_KINDS,
+  BUILT_IN_AGENT_EXECUTION_PROVIDER_IDS,
+  ENGINEERING_HANDLER_KINDS,
+  EXECUTION_PROVIDER_KINDS,
+  EXECUTION_PROVIDER_PRESSURE_STATES,
+  EXECUTION_PROVIDER_QUOTA_VISIBILITIES,
+  EXECUTION_RESOURCE_NEED_KINDS,
+  EXECUTION_RUN_STATUSES
+};