@treeseed/sdk 0.8.10 → 0.8.11

package/dist/d1-store.js

@@ -120,6 +120,9 @@ class MemoryAgentDatabase {
     if (model === "task") {
       return [...this.tasks.values()];
     }
+    if (model === "task_output") {
+      return [...this.taskOutputs.values()].flat();
+    }
     if (model === "graph_run") {
       return [...this.graphRuns.values()];
     }
@@ -160,6 +163,9 @@ class MemoryAgentDatabase {
     if (request.model === "task") {
       return this.tasks.get(key) ?? null;
     }
+    if (request.model === "task_output") {
+      return [...this.taskOutputs.values()].flat().find((output) => output.id === key) ?? null;
+    }
     if (request.model === "graph_run") {
       return this.graphRuns.get(key) ?? null;
     }

package/dist/git-runtime.js

@@ -52,8 +52,10 @@ class GitRuntime {
     try {
       await execFileAsync("git", ["commit", "-m", commitMessage], { cwd: worktreePath });
     } catch (error) {
-      const message = error && typeof error === "object" && "stderr" in error ? String(error.stderr ?? "") : "";
-      if (!message.includes("nothing to commit")) {
+      const stderr = error && typeof error === "object" && "stderr" in error ? String(error.stderr ?? "") : "";
+      const stdout2 = error && typeof error === "object" && "stdout" in error ? String(error.stdout ?? "") : "";
+      if (!`${stdout2}
+${stderr}`.includes("nothing to commit")) {
         throw error;
       }
     }

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

@@ -0,0 +1,48 @@
+import type { SdkContextPack, SdkContextPackRequest, SdkGraphQueryStage, SdkGraphQueryView } from '../sdk-types.ts';
+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;
+    purpose: DeclarativeContextQueryPurpose;
+    query: string;
+    scope?: string;
+    relations?: string[];
+    depth?: number;
+    budget?: number;
+    format?: DeclarativeContextQueryFormat;
+    filters?: Record<string, unknown>;
+    required?: boolean;
+}
+export type HandlerContextPackSource = 'agent_spec' | 'content_frontmatter' | 'work_package' | 'task_payload' | 'default_role_context';
+export interface DeclarativeContextQuerySourceRef {
+    source: HandlerContextPackSource;
+    ref?: string;
+    priority: number;
+}
+export interface CompiledDeclarativeContextQuery {
+    query: DeclarativeContextQuery;
+    request: SdkContextPackRequest;
+    warnings: string[];
+}
+export interface DeclarativeContextQueryCompileResult {
+    ok: boolean;
+    compiled: CompiledDeclarativeContextQuery | null;
+    errors: string[];
+    warnings: string[];
+}
+export interface ResolvedHandlerContextPack {
+    id: string;
+    purpose: string;
+    source: HandlerContextPackSource;
+    sourceRef?: string;
+    query: DeclarativeContextQuery;
+    request: SdkContextPackRequest;
+    pack: SdkContextPack;
+    warnings: string[];
+}
+export declare function declarativeContextPurposeToGraphStage(purpose: string): SdkGraphQueryStage;
+export declare function declarativeContextFormatToGraphView(format: string | undefined): SdkGraphQueryView;
+export declare function compileDeclarativeContextQuery(query: DeclarativeContextQuery, options?: {
+    defaultLimit?: number;
+    maxDepth?: number;
+}): DeclarativeContextQueryCompileResult;

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

@@ -0,0 +1,126 @@
+const VALID_RELATIONS = [
+  "related",
+  "depends_on",
+  "implements",
+  "references",
+  "parent",
+  "child",
+  "supersedes"
+];
+const PURPOSE_TO_STAGE = {
+  plan: "plan",
+  research: "research",
+  implement: "implement",
+  debug: "debug",
+  review: "review"
+};
+const FORMAT_TO_VIEW = {
+  summary: "brief",
+  brief: "brief",
+  full: "full",
+  sources: "list",
+  list: "list",
+  map: "map"
+};
+function asPositiveInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function normalizeString(value) {
+  return value.trim();
+}
+function declarativeContextPurposeToGraphStage(purpose) {
+  return PURPOSE_TO_STAGE[purpose.trim().toLowerCase()] ?? "plan";
+}
+function declarativeContextFormatToGraphView(format) {
+  return FORMAT_TO_VIEW[(format ?? "summary").trim().toLowerCase()] ?? "brief";
+}
+function compileDeclarativeContextQuery(query, options = {}) {
+  const errors = [];
+  const warnings = [];
+  const maxDepth = options.maxDepth ?? 3;
+  const defaultLimit = options.defaultLimit ?? 8;
+  const id = normalizeString(query.id ?? "");
+  if (!id) {
+    errors.push("Context query id is required.");
+  }
+  const purpose = normalizeString(query.purpose ?? "");
+  if (!purpose) {
+    errors.push(`Context query "${id || "<unknown>"}" purpose is required.`);
+  }
+  const textQuery = normalizeString(query.query ?? "");
+  if (!textQuery) {
+    errors.push(`Context query "${id || "<unknown>"}" query is required.`);
+  }
+  const depth = query.depth ?? 1;
+  if (!Number.isInteger(depth) || depth < 0 || depth > maxDepth) {
+    errors.push(`Context query "${id || "<unknown>"}" depth must be an integer between 0 and ${maxDepth}.`);
+  }
+  if (query.budget !== void 0 && !asPositiveInteger(query.budget)) {
+    errors.push(`Context query "${id || "<unknown>"}" budget 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 "/".`);
+  }
+  const relations = (query.relations ?? ["related", "references"]).map((entry) => entry.trim().toLowerCase());
+  const invalidRelations = relations.filter((relation) => !VALID_RELATIONS.includes(relation));
+  if (invalidRelations.length > 0) {
+    errors.push(`Context query "${id || "<unknown>"}" has invalid relations: ${invalidRelations.join(", ")}.`);
+  }
+  const uniqueRelations = [...new Set(relations)];
+  if (uniqueRelations.length !== relations.length) {
+    warnings.push(`Context query "${id || "<unknown>"}" included duplicate relations; duplicates were removed.`);
+  }
+  const stage = declarativeContextPurposeToGraphStage(purpose);
+  if (stage === "plan" && !["plan", ""].includes(purpose.toLowerCase()) && !PURPOSE_TO_STAGE[purpose.toLowerCase()]) {
+    warnings.push(`Context query "${id || "<unknown>"}" purpose "${purpose}" is not a graph stage; using "plan".`);
+  }
+  const view = declarativeContextFormatToGraphView(query.format);
+  if (query.format && !FORMAT_TO_VIEW[query.format.trim().toLowerCase()]) {
+    warnings.push(`Context query "${id || "<unknown>"}" format "${query.format}" is not a graph view; using "brief".`);
+  }
+  if (errors.length > 0) {
+    return { ok: false, compiled: null, errors, warnings };
+  }
+  const request = {
+    query: textQuery,
+    stage,
+    relations: uniqueRelations,
+    view,
+    options: {
+      depth,
+      limit: defaultLimit,
+      maxNodes: defaultLimit
+    }
+  };
+  if (scope) {
+    request.scopePaths = [scope];
+  }
+  if (query.budget !== void 0) {
+    request.budget = {
+      maxTokens: query.budget
+    };
+  }
+  return {
+    ok: true,
+    compiled: {
+      query: {
+        ...query,
+        id,
+        purpose,
+        query: textQuery,
+        scope,
+        relations: uniqueRelations
+      },
+      request,
+      warnings
+    },
+    errors: [],
+    warnings
+  };
+}
+export {
+  compileDeclarativeContextQuery,
+  declarativeContextFormatToGraphView,
+  declarativeContextPurposeToGraphStage
+};

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { PUBLISHED_CONTENT_MANIFEST_SCHEMA_VERSION, EDITORIAL_PREVIEW_COOKIE, Te
 export { createFilesystemContentSource, createPublishedContentPipeline, } from './platform/published-content-pipeline.ts';
 export { loadTreeseedManifest, loadTreeseedTenantManifest, resolveTreeseedTenantRoot, getTenantContentRoot, tenantFeatureEnabled, tenantModelRendered, } from './platform/tenant-config.ts';
 export { parseGraphDsl } from './graph/dsl.ts';
+export { compileDeclarativeContextQuery, declarativeContextFormatToGraphView, declarativeContextPurposeToGraphStage, type CompiledDeclarativeContextQuery, type DeclarativeContextQuery, type DeclarativeContextQueryCompileResult, type DeclarativeContextQueryFormat, type DeclarativeContextQueryPurpose, type DeclarativeContextQuerySourceRef, type HandlerContextPackSource, type ResolvedHandlerContextPack, } from './graph/context-query-contracts.ts';
 export { createDefaultGraphRankingProvider, DEFAULT_GRAPH_RANKING_PROVIDER } from './graph/ranking.ts';
 export { BUILTIN_MODEL_REGISTRY, MODEL_REGISTRY, buildBuiltinModelRegistry, buildModelRegistry, buildScopedModelRegistry, mergeModelRegistries, resolveModelDefinition, } from './model-registry.ts';
 export { normalizeAgentCliOptions, buildCopilotAllowToolArgs } from './cli-tools.ts';
@@ -20,6 +21,7 @@ export { collectTreeseedDependencyStatus, collectTreeseedToolStatus, createTrees
 export { runTreeseedCopilotTask, type TreeseedCopilotTaskInput, type TreeseedCopilotTaskResult, } from './copilot.ts';
 export { findDispatchCapability, listSdkDispatchCapabilities, listWorkflowDispatchCapabilities, } from './dispatch.ts';
 export { executeSdkOperation, findSdkOperation, listSdkOperationNames, } from './sdk-dispatch.ts';
+export { AGENT_OPERATION_MODES, AGENT_OPERATION_NAMES, createAgentOperationEvent, decideAgentOperationPermission, deniedAgentOperationResult, isAgentOperationName, resolveAgentOperationGrant, type AgentDeterministicOperationStep, type AgentOperationApprovalRef, type AgentOperationEvent, type AgentOperationGrant, type AgentOperationMergeFailure, type AgentOperationMode, type AgentOperationName, type AgentOperationPermissionCode, type AgentOperationPermissionDecision, type AgentOperationRequest, type AgentOperationResult, type AgentOperationStatus, } from './operations/agent-tools.ts';
 export { resolveSdkRecordVersion } from './sdk-version.ts';
 export { normalizeAliasedRecord, preprocessAliasedRecord, resolveAliasedField, } from './field-aliases.ts';
 export { canonicalizeFrontmatter, normalizeFilterFields, normalizeMutationData, normalizeRecordToCanonicalShape, normalizeSortFields, readCanonicalFieldValue, resolveModelField, validateModelFieldAliases, } from './sdk-fields.ts';

package/dist/index.js

@@ -94,6 +94,11 @@ import {
   tenantModelRendered
 } from "./platform/tenant-config.js";
 import { parseGraphDsl } from "./graph/dsl.js";
+import {
+  compileDeclarativeContextQuery,
+  declarativeContextFormatToGraphView,
+  declarativeContextPurposeToGraphStage
+} from "./graph/context-query-contracts.js";
 import { createDefaultGraphRankingProvider, DEFAULT_GRAPH_RANKING_PROVIDER } from "./graph/ranking.js";
 import {
   BUILTIN_MODEL_REGISTRY,
@@ -127,6 +132,15 @@ import {
   findSdkOperation,
   listSdkOperationNames
 } from "./sdk-dispatch.js";
+import {
+  AGENT_OPERATION_MODES,
+  AGENT_OPERATION_NAMES,
+  createAgentOperationEvent,
+  decideAgentOperationPermission,
+  deniedAgentOperationResult,
+  isAgentOperationName,
+  resolveAgentOperationGrant
+} from "./operations/agent-tools.js";
 import { resolveSdkRecordVersion } from "./sdk-version.js";
 import {
   normalizeAliasedRecord,
@@ -200,6 +214,8 @@ import { getTreeseedVerifyDriverStatus, runTreeseedVerifyDriver } from "./verifi
 import { CloudflareHttpD1Database } from "./d1-http.js";
 export {
   AGENT_MESSAGE_KINDS,
+  AGENT_OPERATION_MODES,
+  AGENT_OPERATION_NAMES,
   AgentSdk,
   BUILTIN_MODEL_REGISTRY,
   CloudflareHttpD1Database,
@@ -250,6 +266,8 @@ export {
   collectTreeseedDependencyStatus,
   collectTreeseedReconcileStatus,
   collectTreeseedToolStatus,
+  compileDeclarativeContextQuery,
+  createAgentOperationEvent,
   createControlPlaneReporter,
   createDefaultGraphRankingProvider,
   createFilesystemContentSource,
@@ -260,7 +278,11 @@ export {
   createTeamScopedR2OverlayContentRuntimeProvider,
   createTreeseedManagedToolEnv,
   createTreeseedReconcileRegistry,
+  decideAgentOperationPermission,
+  declarativeContextFormatToGraphView,
+  declarativeContextPurposeToGraphStage,
   defaultHubContentResolutionPolicy,
+  deniedAgentOperationResult,
   deriveTreeseedDesiredUnits,
   destroyTreeseedTargetUnits,
   ensureRailwayEnvironment,
@@ -278,6 +300,7 @@ export {
   getTreeseedVerifyDriverStatus,
   importKnowledgePack,
   installTreeseedDependencies,
+  isAgentOperationName,
   isTeamScopedR2ContentEnabled,
   listIntegratedMarketCatalog,
   listRailwayEnvironments,
@@ -320,6 +343,7 @@ export {
   removeMarketProfile,
   reservationHasCapacity,
   reserveCreditsForEstimate,
+  resolveAgentOperationGrant,
   resolveAliasedField,
   resolveCatalogMarketProfiles,
   resolveCloudflareR2Bucket,

package/dist/operations/agent-tools.d.ts

@@ -0,0 +1,114 @@
+export declare const AGENT_OPERATION_NAMES: readonly ["switch", "dev", "verify", "save", "stage", "merge_to_staging", "close", "release"];
+export declare const AGENT_OPERATION_MODES: readonly ["dry_run", "read_only", "mutating"];
+export type AgentOperationName = (typeof AGENT_OPERATION_NAMES)[number];
+export type AgentOperationMode = (typeof AGENT_OPERATION_MODES)[number];
+export type AgentOperationStatus = 'completed' | 'waiting' | 'failed' | 'skipped' | 'retry_created';
+export interface AgentOperationApprovalRef {
+    id: string;
+    kind?: string;
+    state: 'pending' | 'approved' | 'rejected' | 'expired' | 'superseded';
+}
+export interface AgentOperationRequest {
+    operation: AgentOperationName;
+    mode: AgentOperationMode;
+    taskId: string;
+    taskKind?: string;
+    workDayId?: string;
+    agentSlug: string;
+    agentRole: string;
+    projectId: string;
+    environment: string;
+    repoRoot: string;
+    worktreeRoot?: string;
+    featureBranch?: string;
+    stagingBranch?: string;
+    approvalId?: string;
+    approval?: AgentOperationApprovalRef;
+    permissionGrantId?: string;
+    allowedPaths?: string[];
+    forbiddenPaths?: string[];
+    changedPaths?: string[];
+    input: Record<string, unknown>;
+}
+export interface AgentDeterministicOperationStep {
+    id: string;
+    operation: AgentOperationName;
+    stage: 'before_mutation' | 'during_mutation' | 'after_mutation' | 'after_verification_passes' | 'after_verification_fails' | 'after_staging_merge_fails' | 'closeout' | string;
+    mode: AgentOperationMode;
+    required?: boolean;
+}
+export interface AgentOperationGrant {
+    id: string;
+    state?: 'active' | 'paused' | 'revoked';
+    operations: AgentOperationName[];
+    modes: AgentOperationMode[];
+    agentRoles?: string[];
+    taskKinds?: string[];
+    projectIds?: string[];
+    environments?: string[];
+    allowedPaths?: string[];
+    forbiddenPaths?: string[];
+    requiresApproval?: boolean;
+    approvalIds?: string[];
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentOperationMergeFailure {
+    targetBranch: string;
+    featureBranch: string;
+    conflictedPaths: string[];
+    message: string;
+    repairTaskId?: string;
+}
+export interface AgentOperationResult {
+    operation: AgentOperationName;
+    status: AgentOperationStatus;
+    summary: string;
+    changedPaths: string[];
+    stagedPaths: string[];
+    mergedToStaging?: boolean;
+    mergeFailure?: AgentOperationMergeFailure;
+    commandsRun: string[];
+    artifacts: Array<{
+        kind: string;
+        ref: string;
+    }>;
+    error?: {
+        code: string;
+        message: string;
+        retryable: boolean;
+    };
+    metadata: Record<string, unknown>;
+}
+export type AgentOperationPermissionCode = 'allowed' | 'invalid_operation' | 'operation_permission_required' | 'operation_grant_inactive' | 'operation_grant_expired' | 'operation_mode_not_granted' | 'operation_role_not_granted' | 'operation_task_kind_not_granted' | 'operation_project_not_granted' | 'operation_environment_not_granted' | 'operation_approval_required' | 'operation_release_approval_required' | 'operation_worktree_required' | 'operation_allowed_paths_required' | 'operation_path_not_allowed' | 'operation_path_forbidden';
+export interface AgentOperationPermissionDecision {
+    allowed: boolean;
+    status: 'completed' | 'waiting' | 'failed';
+    code: AgentOperationPermissionCode;
+    summary: string;
+    grant?: AgentOperationGrant;
+    metadata: Record<string, unknown>;
+}
+export interface AgentOperationEvent {
+    operation: AgentOperationName;
+    mode: AgentOperationMode;
+    agentRole: string;
+    taskId: string;
+    permissionGrantId?: string;
+    inputSummary: Record<string, unknown>;
+    result: AgentOperationResult;
+    createdAt: string;
+}
+export declare function isAgentOperationName(value: string): value is AgentOperationName;
+export declare function resolveAgentOperationGrant(request: AgentOperationRequest, grants: readonly AgentOperationGrant[], now?: Date): AgentOperationGrant | null;
+export declare function decideAgentOperationPermission(input: {
+    request: AgentOperationRequest;
+    grants: readonly AgentOperationGrant[];
+    now?: Date;
+}): AgentOperationPermissionDecision;
+export declare function deniedAgentOperationResult(request: AgentOperationRequest, decision: AgentOperationPermissionDecision): AgentOperationResult;
+export declare function createAgentOperationEvent(input: {
+    request: AgentOperationRequest;
+    result: AgentOperationResult;
+    createdAt?: string;
+}): AgentOperationEvent;

package/dist/operations/agent-tools.js

@@ -0,0 +1,183 @@
+const AGENT_OPERATION_NAMES = [
+  "switch",
+  "dev",
+  "verify",
+  "save",
+  "stage",
+  "merge_to_staging",
+  "close",
+  "release"
+];
+const AGENT_OPERATION_MODES = ["dry_run", "read_only", "mutating"];
+function normalizePath(value) {
+  return value.replace(/\\/gu, "/").replace(/^\.?\//u, "").replace(/\/+/gu, "/");
+}
+function matchesPattern(path, pattern) {
+  const normalizedPath = normalizePath(path);
+  const normalizedPattern = normalizePath(pattern);
+  if (normalizedPattern.endsWith("/**")) {
+    const prefix = normalizedPattern.slice(0, -3);
+    return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
+  }
+  if (normalizedPattern.endsWith("/")) {
+    return normalizedPath.startsWith(normalizedPattern);
+  }
+  return normalizedPath === normalizedPattern || normalizedPath.startsWith(`${normalizedPattern}/`);
+}
+function listMatches(value, allowed) {
+  return !allowed?.length || value !== void 0 && allowed.includes(value);
+}
+function grantActive(grant, now) {
+  if ((grant.state ?? "active") !== "active") {
+    return "operation_grant_inactive";
+  }
+  if (grant.expiresAt && Date.parse(grant.expiresAt) <= now.valueOf()) {
+    return "operation_grant_expired";
+  }
+  return null;
+}
+function deny(code, summary, options = {}) {
+  return {
+    allowed: false,
+    status: options.status ?? "waiting",
+    code,
+    summary,
+    grant: options.grant,
+    metadata: options.metadata ?? {}
+  };
+}
+function allow(grant, metadata = {}) {
+  return {
+    allowed: true,
+    status: "completed",
+    code: "allowed",
+    summary: `Operation grant ${grant.id} allows this request.`,
+    grant,
+    metadata
+  };
+}
+function isAgentOperationName(value) {
+  return AGENT_OPERATION_NAMES.includes(value);
+}
+function resolveAgentOperationGrant(request, grants, now = /* @__PURE__ */ new Date()) {
+  return grants.find((grant) => {
+    if (request.permissionGrantId && grant.id !== request.permissionGrantId) return false;
+    if (grantActive(grant, now)) return false;
+    if (!grant.operations.includes(request.operation)) return false;
+    return true;
+  }) ?? null;
+}
+function decideAgentOperationPermission(input) {
+  const { request } = input;
+  const now = input.now ?? /* @__PURE__ */ new Date();
+  if (!isAgentOperationName(request.operation)) {
+    return deny("invalid_operation", `Unsupported agent operation "${String(request.operation)}".`, { status: "failed" });
+  }
+  if (request.operation === "release") {
+    const approval = request.approval;
+    if (!approval || approval.state !== "approved" || request.approvalId && approval.id !== request.approvalId) {
+      return deny("operation_release_approval_required", "Release requires an explicit approved release approval.");
+    }
+  }
+  const grant = resolveAgentOperationGrant(request, input.grants, now);
+  if (!grant) {
+    return deny("operation_permission_required", `No operation grant allows ${request.agentRole} to run ${request.operation}.`);
+  }
+  const activeCode = grantActive(grant, now);
+  if (activeCode) {
+    return deny(activeCode, `Operation grant ${grant.id} is not active.`, { grant });
+  }
+  if (!grant.modes.includes(request.mode)) {
+    return deny("operation_mode_not_granted", `Operation grant ${grant.id} does not allow ${request.mode} mode.`, { grant });
+  }
+  if (!listMatches(request.agentRole, grant.agentRoles)) {
+    return deny("operation_role_not_granted", `Operation grant ${grant.id} does not allow role ${request.agentRole}.`, { grant });
+  }
+  if (!listMatches(request.taskKind, grant.taskKinds)) {
+    return deny("operation_task_kind_not_granted", `Operation grant ${grant.id} does not allow task kind ${request.taskKind ?? "<none>"}.`, { grant });
+  }
+  if (!listMatches(request.projectId, grant.projectIds)) {
+    return deny("operation_project_not_granted", `Operation grant ${grant.id} does not allow project ${request.projectId}.`, { grant });
+  }
+  if (!listMatches(request.environment, grant.environments)) {
+    return deny("operation_environment_not_granted", `Operation grant ${grant.id} does not allow environment ${request.environment}.`, { grant });
+  }
+  if (grant.requiresApproval && (!request.approval || request.approval.state !== "approved")) {
+    return deny("operation_approval_required", `Operation grant ${grant.id} requires approval.`, { grant });
+  }
+  if (grant.approvalIds?.length && (!request.approval || !grant.approvalIds.includes(request.approval.id) || request.approval.state !== "approved")) {
+    return deny("operation_approval_required", `Operation grant ${grant.id} requires one of its approved approval ids.`, { grant });
+  }
+  if (request.mode === "mutating" && !request.worktreeRoot && request.operation !== "release") {
+    return deny("operation_worktree_required", `Mutating operation ${request.operation} requires an assigned worktree root.`, { grant });
+  }
+  const allowedPaths = request.allowedPaths?.length ? request.allowedPaths : grant.allowedPaths ?? [];
+  const forbiddenPaths = [...grant.forbiddenPaths ?? [], ...request.forbiddenPaths ?? []];
+  const changedPaths = request.changedPaths ?? [];
+  if ((request.operation === "stage" || request.operation === "merge_to_staging") && allowedPaths.length === 0) {
+    return deny("operation_allowed_paths_required", `${request.operation} requires allowed paths.`, { grant });
+  }
+  for (const changedPath of changedPaths) {
+    if (forbiddenPaths.some((pattern) => matchesPattern(changedPath, pattern))) {
+      return deny("operation_path_forbidden", `${changedPath} is forbidden.`, {
+        grant,
+        status: "failed",
+        metadata: { changedPath, forbiddenPaths }
+      });
+    }
+    if (allowedPaths.length > 0 && !allowedPaths.some((pattern) => matchesPattern(changedPath, pattern))) {
+      return deny("operation_path_not_allowed", `${changedPath} is outside allowed paths.`, {
+        grant,
+        status: "failed",
+        metadata: { changedPath, allowedPaths }
+      });
+    }
+  }
+  return allow(grant, { allowedPaths, forbiddenPaths });
+}
+function deniedAgentOperationResult(request, decision) {
+  return {
+    operation: request.operation,
+    status: decision.status,
+    summary: decision.summary,
+    changedPaths: request.changedPaths ?? [],
+    stagedPaths: [],
+    commandsRun: [],
+    artifacts: [],
+    error: {
+      code: decision.code,
+      message: decision.summary,
+      retryable: decision.status === "waiting"
+    },
+    metadata: {
+      permission: decision
+    }
+  };
+}
+function createAgentOperationEvent(input) {
+  return {
+    operation: input.request.operation,
+    mode: input.request.mode,
+    agentRole: input.request.agentRole,
+    taskId: input.request.taskId,
+    permissionGrantId: input.request.permissionGrantId,
+    inputSummary: {
+      projectId: input.request.projectId,
+      environment: input.request.environment,
+      allowedPaths: input.request.allowedPaths ?? [],
+      forbiddenPaths: input.request.forbiddenPaths ?? [],
+      changedPaths: input.request.changedPaths ?? []
+    },
+    result: input.result,
+    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+export {
+  AGENT_OPERATION_MODES,
+  AGENT_OPERATION_NAMES,
+  createAgentOperationEvent,
+  decideAgentOperationPermission,
+  deniedAgentOperationResult,
+  isAgentOperationName,
+  resolveAgentOperationGrant
+};

package/dist/operations/services/commit-message-provider.js

@@ -29,7 +29,7 @@ const danglingSubjectEndings = /* @__PURE__ */ new Set([
   "update",
   "with"
 ]);
-const defaultTimeoutMs = 3e4;
+const defaultTimeoutMs = 6e4;
 const defaultMaxDiffChars = 12e3;
 const subjectMaxLength = 72;
 function envValue(env, key) {

package/dist/operations/services/hub-provider-launch.js

@@ -352,7 +352,7 @@ function applyManagedProjectDefaults(projectRoot, input) {
       ...config.providers ?? {},
       forms: config.providers?.forms ?? "store_only",
       agents: {
-        execution: "copilot",
+        execution: "codex",
         mutation: "local_branch",
         repository: "git",
         verification: "local",

package/dist/operations/services/runtime-tools.js

@@ -37,7 +37,7 @@ const TREESEED_DEFAULT_PLUGIN_REFERENCES = [
 const TREESEED_DEFAULT_PROVIDER_SELECTIONS = {
   forms: "store_only",
   agents: {
-    execution: "copilot",
+    execution: "codex",
     mutation: "local_branch",
     repository: "git",
     verification: "local",

package/dist/operations.d.ts

@@ -5,5 +5,6 @@ export { TreeseedOperationsSdk } from './operations/runtime.ts';
 export type { HubContentResolutionPolicy, KnowledgeHubLaunchIntent, KnowledgeHubLaunchPhase, KnowledgeHubLaunchPlan, KnowledgeHubLaunchResult, KnowledgeHubRepositoryPlan, RepositoryHost, } from './operations/services/hub-launch.ts';
 export type { TreeseedOperationContext, TreeseedOperationImplementation, TreeseedOperationId, TreeseedOperationMetadata, TreeseedOperationProvider, TreeseedOperationProviderId, TreeseedOperationRequest, TreeseedOperationResult, TreeseedOperationGroup, } from './operations-types.ts';
 export { TreeseedOperationError } from './operations-types.ts';
+export { AGENT_OPERATION_MODES, AGENT_OPERATION_NAMES, createAgentOperationEvent, decideAgentOperationPermission, deniedAgentOperationResult, isAgentOperationName, resolveAgentOperationGrant, type AgentDeterministicOperationStep, type AgentOperationApprovalRef, type AgentOperationEvent, type AgentOperationGrant, type AgentOperationMergeFailure, type AgentOperationMode, type AgentOperationName, type AgentOperationPermissionCode, type AgentOperationPermissionDecision, type AgentOperationRequest, type AgentOperationResult, type AgentOperationStatus, } from './operations/agent-tools.ts';
 export { TreeseedWorkflowSdk } from './workflow.ts';
 export type * from './workflow.ts';

package/dist/operations.js

@@ -15,20 +15,36 @@ import {
 } from "./operations/services/hub-launch.js";
 import { TreeseedOperationsSdk } from "./operations/runtime.js";
 import { TreeseedOperationError } from "./operations-types.js";
+import {
+  AGENT_OPERATION_MODES,
+  AGENT_OPERATION_NAMES,
+  createAgentOperationEvent,
+  decideAgentOperationPermission,
+  deniedAgentOperationResult,
+  isAgentOperationName,
+  resolveAgentOperationGrant
+} from "./operations/agent-tools.js";
 import { TreeseedWorkflowSdk } from "./workflow.js";
 export {
+  AGENT_OPERATION_MODES,
+  AGENT_OPERATION_NAMES,
   TRESEED_OPERATION_SPECS,
   TreeseedOperationError,
   TreeseedOperationsSdk,
   TreeseedWorkflowSdk,
   collectTreeseedConfigSeedValues,
+  createAgentOperationEvent,
   createKnowledgeHubRepositories,
+  decideAgentOperationPermission,
   defaultHubContentResolutionPolicy,
+  deniedAgentOperationResult,
   executeKnowledgeHubLaunch,
   findTreeseedOperation,
+  isAgentOperationName,
   listTreeseedOperationNames,
   normalizeKnowledgeHubLaunchIntent,
   planKnowledgeHubLaunch,
   planKnowledgeHubRepositories,
+  resolveAgentOperationGrant,
   validateRepositoryHost
 };

package/dist/platform/environment.js

@@ -106,6 +106,10 @@ function processingPlaneEnabled(context) {
 function formsEnabled(context) {
   return webSurfaceEnabled(context) && (context.deployConfig.providers?.forms ?? "store_only") !== "none";
 }
+function codexExecutionSelected(context) {
+  const execution = context.deployConfig.providers?.agents?.execution ?? "codex";
+  return execution === "codex" || execution === "codex_subscription";
+}
 function railwayManagedEnabled(context) {
   if (!workflowPlaneAllows("processing")) {
     return false;
@@ -333,6 +337,7 @@ const PREDICATES = {
   apiSurfaceEnabled: (context) => apiSurfaceEnabled(context),
   processingPlaneEnabled: (context) => processingPlaneEnabled(context),
   formsEnabled: (context) => formsEnabled(context),
+  codexExecutionSelected: (context) => codexExecutionSelected(context),
   railwayManagedEnabled: (context) => railwayManagedEnabled(context),
   hubTreeseedHosted: (context) => resolveHubMode(context) === "treeseed_hosted",
   hubCustomerHosted: (context) => resolveHubMode(context) === "customer_hosted",

package/dist/platform/plugins/constants.js

@@ -3,7 +3,7 @@ const TREESEED_DEFAULT_PROVIDER_SELECTIONS = {
   forms: "store_only",
   operations: "default",
   agents: {
-    execution: "copilot",
+    execution: "codex",
     mutation: "local_branch",
     repository: "git",
     verification: "local",

package/dist/plugin-default.js

@@ -6,7 +6,7 @@ var plugin_default_default = defineTreeseedPlugin({
     forms: ["store_only", "notify_admin", "full_email"],
     operations: ["default"],
     agents: {
-      execution: ["stub", "manual", "copilot"],
+      execution: ["stub", "manual", "copilot", "codex", "codex_subscription"],
       mutation: ["local_branch"],
       repository: ["stub", "git"],
       verification: ["stub", "local"],

package/dist/treeseed/template-catalog/templates/starter-basic/template/treeseed.site.yaml

@@ -72,7 +72,7 @@ plugins:
 providers:
   forms: store_only
   agents:
-    execution: copilot
+    execution: codex
     mutation: local_branch
     repository: git
     verification: local

package/dist/types/agents.d.ts

@@ -27,6 +27,18 @@ export interface AgentOutputContract {
     modelMutations: string[];
 }
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeseed/sdk",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "description": "Shared Treeseed SDK for content-backed and D1-backed object models.",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -96,6 +96,10 @@
       "types": "./dist/operations.d.ts",
       "default": "./dist/operations.js"
     },
+    "./operations/agent-tools": {
+      "types": "./dist/operations/agent-tools.d.ts",
+      "default": "./dist/operations/agent-tools.js"
+    },
     "./workflow": {
       "types": "./dist/workflow.d.ts",
       "default": "./dist/workflow.js"
@@ -197,6 +201,10 @@
       "types": "./dist/graph.d.ts",
       "default": "./dist/graph.js"
     },
+    "./graph/context-query-contracts": {
+      "types": "./dist/graph/context-query-contracts.d.ts",
+      "default": "./dist/graph/context-query-contracts.js"
+    },
     "./sdk-filters": {
       "types": "./dist/sdk-filters.d.ts",
       "default": "./dist/sdk-filters.js"