@treeseed/sdk 0.1.2 → 0.3.1

package/dist/sdk-types.js

@@ -11,7 +11,13 @@ const SDK_MODEL_NAMES = [
   "agent",
   "agent_run",
   "agent_cursor",
-  "content_lease"
+  "content_lease",
+  "work_day",
+  "task",
+  "task_event",
+  "task_output",
+  "graph_run",
+  "report"
 ];
 const SDK_OPERATIONS = ["get", "read", "search", "follow", "pick", "create", "update"];
 const SDK_STORAGE_BACKENDS = ["content", "d1"];

package/dist/sdk-version.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveSdkRecordVersion(record: Record<string, unknown> | null | undefined): string | null;
+export declare function assertExpectedVersion(expectedVersion: string | undefined, record: Record<string, unknown> | null | undefined, label: string): void;

package/dist/sdk-version.js

@@ -0,0 +1,42 @@
+function firstString(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value;
+    }
+  }
+  return null;
+}
+function resolveSdkRecordVersion(record) {
+  if (!record) {
+    return null;
+  }
+  return firstString(record, [
+    "updatedAt",
+    "updated_at",
+    "leaseExpiresAt",
+    "lease_expires_at",
+    "finishedAt",
+    "finished_at",
+    "startedAt",
+    "started_at",
+    "createdAt",
+    "created_at"
+  ]);
+}
+function assertExpectedVersion(expectedVersion, record, label) {
+  if (!expectedVersion) {
+    return;
+  }
+  const currentVersion = resolveSdkRecordVersion(record);
+  if (!currentVersion) {
+    throw new Error(`${label} does not expose a comparable version for optimistic updates.`);
+  }
+  if (currentVersion !== expectedVersion) {
+    throw new Error(`${label} version mismatch. Expected ${expectedVersion} but found ${currentVersion}.`);
+  }
+}
+export {
+  assertExpectedVersion,
+  resolveSdkRecordVersion
+};

package/dist/sdk.d.ts

@@ -0,0 +1,215 @@
+import type { AgentPermissionConfig, AgentRuntimeSpec } from './types/agents.ts';
+import { ContentStore } from './content-store.ts';
+import { type AgentDatabase } from './d1-store.ts';
+import { type LoadedTreeseedPluginEntry } from './platform/plugins.ts';
+import type { SdkAckMessageRequest, SdkClaimMessageRequest, SdkClaimTaskRequest, SdkCloseWorkDayRequest, SdkCompleteTaskRequest, SdkCreateReportRequest, SdkCreateMessageRequest, SdkCreateTaskRequest, SdkCursorRequest, SdkFailTaskRequest, SdkFollowRequest, SdkGetRequest, SdkGetCursorRequest, SdkJsonEnvelope, SdkLeaseReleaseRequest, SdkManagerContextPayload, SdkMutationRequest, SdkGraphQueryOptions, SdkGraphQueryRequest, SdkGraphRefreshRequest, SdkGraphSearchOptions, SdkContextPackRequest, SdkGraphDslParseResult, SdkPickRequest, SdkRecordRunRequest, SdkSearchRequest, SdkStartWorkDayRequest, SdkTaskProgressRequest, SdkTaskSearchRequest, SdkUpdateRequest, SdkModelDefinition, SdkModelRegistry, SdkGraphRankingProvider } from './sdk-types.ts';
+export interface AgentSdkOptions {
+    repoRoot?: string;
+    database?: AgentDatabase;
+    models?: SdkModelDefinition[];
+    modelRegistry?: SdkModelRegistry;
+    graphRankingProvider?: SdkGraphRankingProvider;
+    plugins?: LoadedTreeseedPluginEntry[];
+}
+export declare class AgentSdk {
+    readonly database: AgentDatabase;
+    readonly content: ContentStore;
+    readonly models: SdkModelRegistry;
+    private readonly graph;
+    constructor(options?: AgentSdkOptions);
+    static createLocal(options: {
+        repoRoot?: string;
+        databaseName?: string;
+        persistTo?: string;
+        models?: SdkModelDefinition[];
+        modelRegistry?: SdkModelRegistry;
+    }): AgentSdk;
+    private envelope;
+    get(request: SdkGetRequest): Promise<SdkJsonEnvelope<Record<string, unknown> | import("./sdk-types.ts").SdkContentEntry | null>>;
+    read(request: SdkGetRequest): Promise<{
+        operation: "read";
+        ok: boolean;
+        model: import("./sdk-types.ts").SdkModelName;
+        payload: Record<string, unknown> | import("./sdk-types.ts").SdkContentEntry | null;
+        meta?: Record<string, unknown>;
+    }>;
+    search(request: SdkSearchRequest): Promise<SdkJsonEnvelope<Record<string, unknown>[] | import("./sdk-types.ts").SdkContentEntry[]>>;
+    follow(request: SdkFollowRequest): Promise<SdkJsonEnvelope<{
+        items: Record<string, unknown>[];
+        since: string;
+    } | {
+        items: import("./sdk-types.ts").SdkContentEntry[];
+        since: string;
+    }>>;
+    pick(request: SdkPickRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkPickResult<Record<string, unknown>> | import("./sdk-types.ts").SdkPickResult<import("./sdk-types.ts").SdkContentEntry>>>;
+    create(request: SdkMutationRequest): Promise<SdkJsonEnvelope<Record<string, unknown> | {
+        item: import("./sdk-types.ts").SdkContentEntry;
+        git: import("./git-runtime.ts").GitMutationResult;
+    }>>;
+    update(request: SdkUpdateRequest): Promise<SdkJsonEnvelope<Record<string, unknown> | {
+        item: import("./sdk-types.ts").SdkContentEntry;
+        git: import("./git-runtime.ts").GitMutationResult;
+    } | null>>;
+    claimMessage(request: SdkClaimMessageRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkMessageEntity | null>>;
+    ackMessage(request: SdkAckMessageRequest): Promise<SdkJsonEnvelope<{
+        id: number;
+        status: "pending" | "claimed" | "completed" | "failed" | "dead_letter";
+    }>>;
+    createMessage(request: SdkCreateMessageRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkMessageEntity>>;
+    recordRun(request: SdkRecordRunRequest): Promise<SdkJsonEnvelope<Record<string, unknown>>>;
+    getCursor(request: SdkGetCursorRequest): Promise<SdkJsonEnvelope<string | null>>;
+    upsertCursor(request: SdkCursorRequest): Promise<SdkJsonEnvelope<SdkCursorRequest>>;
+    releaseLease(request: SdkLeaseReleaseRequest): Promise<SdkJsonEnvelope<SdkLeaseReleaseRequest>>;
+    releaseAllLeases(): Promise<SdkJsonEnvelope<{
+        count: number;
+    }>>;
+    startWorkDay(request: SdkStartWorkDayRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkWorkDayEntity | null>>;
+    closeWorkDay(request: SdkCloseWorkDayRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkWorkDayEntity | null>>;
+    createTask(request: SdkCreateTaskRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkTaskEntity | null>>;
+    claimTask(request: SdkClaimTaskRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkTaskEntity | null>>;
+    recordTaskProgress(request: SdkTaskProgressRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkTaskEntity | null>>;
+    completeTask(request: SdkCompleteTaskRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkTaskEntity | null>>;
+    failTask(request: SdkFailTaskRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkTaskEntity | null>>;
+    appendTaskEvent(request: {
+        taskId: string;
+        kind: string;
+        data?: Record<string, unknown>;
+        actor: string;
+    }): Promise<SdkJsonEnvelope<Record<string, unknown> | null>>;
+    searchTasks(request: SdkTaskSearchRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkTaskEntity[]>>;
+    createReport(request: SdkCreateReportRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkReportEntity | null>>;
+    getManagerContext(taskId: string): Promise<SdkJsonEnvelope<SdkManagerContextPayload>>;
+    listAgentSpecs(options?: {
+        enabled?: boolean;
+    }): Promise<AgentRuntimeSpec[]>;
+    listRawAgentSpecs(options?: {
+        enabled?: boolean;
+    }): Promise<Record<string, unknown>[] | import("./sdk-types.ts").SdkContentEntry[]>;
+    scopeForAgent(agent: Pick<AgentRuntimeSpec, 'slug' | 'permissions'>): ScopedAgentSdk;
+    /** Advanced graph maintenance helper. Most application code should use parseGraphDsl() -> queryGraph() -> buildContextPack(). */
+    refreshGraph(request?: SdkGraphRefreshRequest): Promise<import("./sdk-types.ts").SdkGraphRefreshPayload>;
+    /** Advanced lexical graph primitive for file nodes. Prefer queryGraph() or buildContextPack() for AI-context retrieval. */
+    searchFiles(query: string, options?: SdkGraphSearchOptions): Promise<import("./sdk-types.ts").SdkGraphSearchResult[]>;
+    /** Advanced lexical graph primitive for section nodes. Prefer queryGraph() or buildContextPack() for AI-context retrieval. */
+    searchSections(query: string, options?: SdkGraphSearchOptions): Promise<import("./sdk-types.ts").SdkGraphSearchResult[]>;
+    /** Advanced lexical graph primitive for entity nodes. Prefer queryGraph() or buildContextPack() for AI-context retrieval. */
+    searchEntities(query: string, options?: SdkGraphSearchOptions): Promise<import("./sdk-types.ts").SdkGraphSearchResult[]>;
+    /** Advanced graph primitive that returns one raw graph node by id. */
+    getGraphNode(id: string): Promise<import("./sdk-types.ts").SdkGraphNode | null>;
+    /** Advanced graph primitive for direct neighborhood inspection. Prefer queryGraph() for ranked retrieval. */
+    getNeighbors(id: string, options?: SdkGraphQueryOptions): Promise<{
+        node: import("./sdk-types.ts").SdkGraphNode | null;
+        nodes: import("./sdk-types.ts").SdkGraphNode[];
+        edges: import("./sdk-types.ts").SdkGraphEdge[];
+    }>;
+    /** Advanced traversal primitive for direct reference walking. Prefer queryGraph() when you need ranking and ctx-aware behavior. */
+    followReferences(id: string, options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphTraversalResult>;
+    /** Advanced graph primitive for incoming-link inspection. */
+    getBacklinks(id: string, options?: SdkGraphQueryOptions): Promise<{
+        node: import("./sdk-types.ts").SdkGraphNode | null;
+        nodes: import("./sdk-types.ts").SdkGraphNode[];
+        edges: import("./sdk-types.ts").SdkGraphEdge[];
+    }>;
+    /** Advanced graph primitive for local relatedness. Prefer queryGraph() for the primary ranked graph workflow. */
+    getRelated(id: string, options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphQueryNodeResult[]>;
+    /** Advanced traversal primitive for raw subgraph extraction. Prefer buildContextPack() when you need prompt-ready output. */
+    getSubgraph(seedIds: string[], options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphTraversalResult>;
+    /** Primary graph workflow helper. Resolves roots before ranking and traversal. */
+    resolveSeeds(request: SdkGraphQueryRequest): Promise<import("./sdk-types.ts").SdkGraphSeedResolution>;
+    /** Primary graph workflow entrypoint for ranked graph retrieval. */
+    queryGraph(request: SdkGraphQueryRequest): Promise<import("./sdk-types.ts").SdkGraphQueryResult>;
+    /** Primary graph workflow entrypoint for prompt-ready AI context assembly. */
+    buildContextPack(request: SdkContextPackRequest): Promise<import("./sdk-types.ts").SdkContextPack>;
+    /** Primary graph workflow helper. Parses the public ctx DSL into a typed graph request. */
+    parseGraphDsl(source: string): Promise<SdkGraphDslParseResult>;
+    /** Primary graph workflow helper for resolving ids, paths, and anchors into graph nodes. */
+    resolveReference(reference: string, options?: {
+        fromNodeId?: string;
+        fromPath?: string;
+        models?: string[];
+    }): Promise<import("./sdk-types.ts").SdkGraphNode | null>;
+    /** Primary graph workflow helper for explaining why two nodes are connected. */
+    explainReferenceChain(fromId: string, toId: string): Promise<import("./sdk-types.ts").SdkGraphPathExplanation | null>;
+}
+/** Operational SDK wrapper that enforces agent permissions on top of AgentSdk. */
+export declare class ScopedAgentSdk {
+    private readonly base;
+    private readonly actor;
+    private readonly permissions;
+    constructor(base: AgentSdk, actor: string, permissions: AgentPermissionConfig[]);
+    private assertAllowed;
+    private allowedModelsFor;
+    private assertGraphNodeAllowed;
+    get(request: SdkGetRequest): Promise<SdkJsonEnvelope<Record<string, unknown> | import("./sdk-types.ts").SdkContentEntry | null>>;
+    read(request: SdkGetRequest): Promise<{
+        operation: "read";
+        ok: boolean;
+        model: import("./sdk-types.ts").SdkModelName;
+        payload: Record<string, unknown> | import("./sdk-types.ts").SdkContentEntry | null;
+        meta?: Record<string, unknown>;
+    }>;
+    search(request: SdkSearchRequest): Promise<SdkJsonEnvelope<Record<string, unknown>[] | import("./sdk-types.ts").SdkContentEntry[]>>;
+    follow(request: SdkFollowRequest): Promise<SdkJsonEnvelope<{
+        items: Record<string, unknown>[];
+        since: string;
+    } | {
+        items: import("./sdk-types.ts").SdkContentEntry[];
+        since: string;
+    }>>;
+    pick(request: SdkPickRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkPickResult<Record<string, unknown>> | import("./sdk-types.ts").SdkPickResult<import("./sdk-types.ts").SdkContentEntry>>>;
+    create(request: Omit<SdkMutationRequest, 'actor'>): Promise<SdkJsonEnvelope<Record<string, unknown> | {
+        item: import("./sdk-types.ts").SdkContentEntry;
+        git: import("./git-runtime.ts").GitMutationResult;
+    }>>;
+    update(request: Omit<SdkUpdateRequest, 'actor'>): Promise<SdkJsonEnvelope<Record<string, unknown> | {
+        item: import("./sdk-types.ts").SdkContentEntry;
+        git: import("./git-runtime.ts").GitMutationResult;
+    } | null>>;
+    claimMessage(request: SdkClaimMessageRequest): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkMessageEntity | null>>;
+    ackMessage(request: SdkAckMessageRequest): Promise<SdkJsonEnvelope<{
+        id: number;
+        status: "pending" | "claimed" | "completed" | "failed" | "dead_letter";
+    }>>;
+    createMessage(request: Omit<SdkCreateMessageRequest, 'actor'>): Promise<SdkJsonEnvelope<import("./sdk-types.ts").SdkMessageEntity>>;
+    recordRun(request: SdkRecordRunRequest): Promise<SdkJsonEnvelope<Record<string, unknown>>>;
+    getCursor(request: SdkGetCursorRequest): Promise<SdkJsonEnvelope<string | null>>;
+    upsertCursor(request: SdkCursorRequest): Promise<SdkJsonEnvelope<SdkCursorRequest>>;
+    releaseLease(request: SdkLeaseReleaseRequest): Promise<SdkJsonEnvelope<SdkLeaseReleaseRequest>>;
+    releaseAllLeases(): Promise<SdkJsonEnvelope<{
+        count: number;
+    }>>;
+    refreshGraph(request?: SdkGraphRefreshRequest): Promise<import("./sdk-types.ts").SdkGraphRefreshPayload>;
+    /** Advanced lexical graph primitive for file nodes. Scoped to models the agent may search. */
+    searchFiles(query: string, options?: SdkGraphSearchOptions): Promise<import("./sdk-types.ts").SdkGraphSearchResult[]>;
+    /** Advanced lexical graph primitive for section nodes. Scoped to models the agent may search. */
+    searchSections(query: string, options?: SdkGraphSearchOptions): Promise<import("./sdk-types.ts").SdkGraphSearchResult[]>;
+    /** Advanced lexical graph primitive for entity nodes. Scoped to models the agent may search. */
+    searchEntities(query: string, options?: SdkGraphSearchOptions): Promise<import("./sdk-types.ts").SdkGraphSearchResult[]>;
+    getGraphNode(id: string): Promise<import("./sdk-types.ts").SdkGraphNode | null>;
+    getNeighbors(id: string, options?: SdkGraphQueryOptions): Promise<{
+        node: import("./sdk-types.ts").SdkGraphNode | null;
+        nodes: import("./sdk-types.ts").SdkGraphNode[];
+        edges: import("./sdk-types.ts").SdkGraphEdge[];
+    }>;
+    followReferences(id: string, options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphTraversalResult>;
+    getBacklinks(id: string, options?: SdkGraphQueryOptions): Promise<{
+        node: import("./sdk-types.ts").SdkGraphNode | null;
+        nodes: import("./sdk-types.ts").SdkGraphNode[];
+        edges: import("./sdk-types.ts").SdkGraphEdge[];
+    }>;
+    getRelated(id: string, options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphQueryNodeResult[]>;
+    getSubgraph(seedIds: string[], options?: SdkGraphQueryOptions): Promise<import("./sdk-types.ts").SdkGraphTraversalResult>;
+    /** Primary graph workflow helper, scoped to followable models. */
+    resolveSeeds(request: SdkGraphQueryRequest): Promise<import("./sdk-types.ts").SdkGraphSeedResolution>;
+    /** Primary graph workflow entrypoint for ranked graph retrieval, scoped to followable models. */
+    queryGraph(request: SdkGraphQueryRequest): Promise<import("./sdk-types.ts").SdkGraphQueryResult>;
+    /** Primary graph workflow entrypoint for prompt-ready context assembly, scoped to followable models. */
+    buildContextPack(request: SdkContextPackRequest): Promise<import("./sdk-types.ts").SdkContextPack>;
+    parseGraphDsl(source: string): Promise<SdkGraphDslParseResult>;
+    resolveReference(reference: string, options?: {
+        fromNodeId?: string;
+        fromPath?: string;
+        models?: string[];
+    }): Promise<import("./sdk-types.ts").SdkGraphNode | null>;
+    explainReferenceChain(fromId: string, toId: string): Promise<import("./sdk-types.ts").SdkGraphPathExplanation | null>;
+}

package/dist/sdk.js

@@ -2,7 +2,9 @@ import { resolveSdkRepoRoot } from "./runtime.js";
 import { normalizeAgentCliOptions } from "./cli-tools.js";
 import { ContentStore } from "./content-store.js";
 import { CloudflareD1AgentDatabase, MemoryAgentDatabase } from "./d1-store.js";
-import { resolveModelDefinition } from "./model-registry.js";
+import { ContentGraphRuntime } from "./graph.js";
+import { loadTreeseedPlugins } from "./platform/plugins.js";
+import { buildScopedModelRegistry, resolveModelDefinition } from "./model-registry.js";
 import { WranglerD1Database } from "./wrangler-d1.js";
 function normalizeAgentSpec(entry) {
   if (!entry) {
@@ -27,10 +29,25 @@ function operationAllowed(permissions, model, operation) {
 class AgentSdk {
   database;
   content;
+  models;
+  graph;
   constructor(options = {}) {
     const repoRoot = resolveSdkRepoRoot(options.repoRoot);
+    this.models = options.modelRegistry ?? buildScopedModelRegistry(repoRoot, options.models);
     this.database = options.database ?? new MemoryAgentDatabase();
-    this.content = new ContentStore(repoRoot, this.database);
+    this.content = new ContentStore(repoRoot, this.database, this.models);
+    let plugins = options.plugins;
+    if (!plugins) {
+      try {
+        plugins = loadTreeseedPlugins();
+      } catch {
+        plugins = [];
+      }
+    }
+    this.graph = new ContentGraphRuntime(repoRoot, this.models, {
+      rankingProvider: options.graphRankingProvider,
+      plugins
+    });
   }
   static createLocal(options) {
     const repoRoot = resolveSdkRepoRoot(options.repoRoot);
@@ -41,20 +58,22 @@ class AgentSdk {
     );
     return new AgentSdk({
       repoRoot,
-      database: new CloudflareD1AgentDatabase(d1)
+      database: new CloudflareD1AgentDatabase(d1),
+      models: options.models,
+      modelRegistry: options.modelRegistry
     });
   }
   envelope(model, operation, payload, meta) {
     return {
       ok: true,
-      model: resolveModelDefinition(model).name,
+      model: resolveModelDefinition(model, this.models).name,
       operation,
       payload,
       meta
     };
   }
   async get(request) {
-    const definition = resolveModelDefinition(request.model);
+    const definition = resolveModelDefinition(request.model, this.models);
     const payload = definition.storage === "content" ? await this.content.get({ ...request, model: definition.name }) : await this.database.get({ ...request, model: definition.name });
     return this.envelope(definition.name, "get", payload);
   }
@@ -65,33 +84,33 @@ class AgentSdk {
     }));
   }
   async search(request) {
-    const definition = resolveModelDefinition(request.model);
+    const definition = resolveModelDefinition(request.model, this.models);
     const payload = definition.storage === "content" ? await this.content.search({ ...request, model: definition.name }) : await this.database.search({ ...request, model: definition.name });
     return this.envelope(definition.name, "search", payload, {
       count: Array.isArray(payload) ? payload.length : 0
     });
   }
   async follow(request) {
-    const definition = resolveModelDefinition(request.model);
+    const definition = resolveModelDefinition(request.model, this.models);
     const payload = definition.storage === "content" ? await this.content.follow({ ...request, model: definition.name }) : await this.database.follow({ ...request, model: definition.name });
     return this.envelope(definition.name, "follow", payload, {
       count: payload.items.length
     });
   }
   async pick(request) {
-    const definition = resolveModelDefinition(request.model);
+    const definition = resolveModelDefinition(request.model, this.models);
     const payload = definition.storage === "content" ? await this.content.pick({ ...request, model: definition.name }) : await this.database.pick({ ...request, model: definition.name });
     return this.envelope(definition.name, "pick", payload, {
       claimed: Boolean(payload.item)
     });
   }
   async create(request) {
-    const definition = resolveModelDefinition(request.model);
+    const definition = resolveModelDefinition(request.model, this.models);
     const payload = definition.storage === "content" ? await this.content.create({ ...request, model: definition.name }) : await this.database.create({ ...request, model: definition.name });
     return this.envelope(definition.name, "create", payload);
   }
   async update(request) {
-    const definition = resolveModelDefinition(request.model);
+    const definition = resolveModelDefinition(request.model, this.models);
     const payload = definition.storage === "content" ? await this.content.update({ ...request, model: definition.name }) : await this.database.update({ ...request, model: definition.name });
     return this.envelope(definition.name, "update", payload);
   }
@@ -129,6 +148,50 @@ class AgentSdk {
     const count = await this.database.releaseAllLeases();
     return this.envelope("content_lease", "update", { count });
   }
+  async startWorkDay(request) {
+    const payload = await this.database.startWorkDay(request);
+    return this.envelope("work_day", "create", payload);
+  }
+  async closeWorkDay(request) {
+    const payload = await this.database.closeWorkDay(request);
+    return this.envelope("work_day", "update", payload);
+  }
+  async createTask(request) {
+    const payload = await this.database.createTask(request);
+    return this.envelope("task", "create", payload);
+  }
+  async claimTask(request) {
+    const payload = await this.database.claimTask(request);
+    return this.envelope("task", "update", payload);
+  }
+  async recordTaskProgress(request) {
+    const payload = await this.database.recordTaskProgress(request);
+    return this.envelope("task", "update", payload);
+  }
+  async completeTask(request) {
+    const payload = await this.database.completeTask(request);
+    return this.envelope("task", "update", payload);
+  }
+  async failTask(request) {
+    const payload = await this.database.failTask(request);
+    return this.envelope("task", "update", payload);
+  }
+  async appendTaskEvent(request) {
+    const payload = await this.database.appendTaskEvent(request);
+    return this.envelope("task_event", "create", payload);
+  }
+  async searchTasks(request) {
+    const payload = await this.database.searchTasks(request);
+    return this.envelope("task", "search", payload, { count: payload.length });
+  }
+  async createReport(request) {
+    const payload = await this.database.createReport(request);
+    return this.envelope("report", "create", payload);
+  }
+  async getManagerContext(taskId) {
+    const payload = await this.database.getManagerContext(taskId);
+    return this.envelope("task", "get", payload);
+  }
   async listAgentSpecs(options) {
     const rawEntries = await this.listRawAgentSpecs(options);
     return rawEntries.map((entry) => normalizeAgentSpec(entry)).filter((entry) => Boolean(entry && entry.slug));
@@ -145,6 +208,70 @@ class AgentSdk {
   scopeForAgent(agent) {
     return new ScopedAgentSdk(this, agent.slug, agent.permissions);
   }
+  /** Advanced graph maintenance helper. Most application code should use parseGraphDsl() -> queryGraph() -> buildContextPack(). */
+  refreshGraph(request) {
+    return this.graph.refresh(request);
+  }
+  /** Advanced lexical graph primitive for file nodes. Prefer queryGraph() or buildContextPack() for AI-context retrieval. */
+  searchFiles(query, options) {
+    return this.graph.searchFiles(query, options);
+  }
+  /** Advanced lexical graph primitive for section nodes. Prefer queryGraph() or buildContextPack() for AI-context retrieval. */
+  searchSections(query, options) {
+    return this.graph.searchSections(query, options);
+  }
+  /** Advanced lexical graph primitive for entity nodes. Prefer queryGraph() or buildContextPack() for AI-context retrieval. */
+  searchEntities(query, options) {
+    return this.graph.searchEntities(query, options);
+  }
+  /** Advanced graph primitive that returns one raw graph node by id. */
+  getGraphNode(id) {
+    return this.graph.getNode(id);
+  }
+  /** Advanced graph primitive for direct neighborhood inspection. Prefer queryGraph() for ranked retrieval. */
+  getNeighbors(id, options) {
+    return this.graph.getNeighbors(id, options);
+  }
+  /** Advanced traversal primitive for direct reference walking. Prefer queryGraph() when you need ranking and ctx-aware behavior. */
+  followReferences(id, options) {
+    return this.graph.followReferences(id, options);
+  }
+  /** Advanced graph primitive for incoming-link inspection. */
+  getBacklinks(id, options) {
+    return this.graph.getBacklinks(id, options);
+  }
+  /** Advanced graph primitive for local relatedness. Prefer queryGraph() for the primary ranked graph workflow. */
+  getRelated(id, options) {
+    return this.graph.getRelated(id, options);
+  }
+  /** Advanced traversal primitive for raw subgraph extraction. Prefer buildContextPack() when you need prompt-ready output. */
+  getSubgraph(seedIds, options) {
+    return this.graph.getSubgraph(seedIds, options);
+  }
+  /** Primary graph workflow helper. Resolves roots before ranking and traversal. */
+  resolveSeeds(request) {
+    return this.graph.resolveSeeds(request);
+  }
+  /** Primary graph workflow entrypoint for ranked graph retrieval. */
+  queryGraph(request) {
+    return this.graph.queryGraph(request);
+  }
+  /** Primary graph workflow entrypoint for prompt-ready AI context assembly. */
+  buildContextPack(request) {
+    return this.graph.buildContextPack(request);
+  }
+  /** Primary graph workflow helper. Parses the public ctx DSL into a typed graph request. */
+  parseGraphDsl(source) {
+    return this.graph.parseGraphDsl(source);
+  }
+  /** Primary graph workflow helper for resolving ids, paths, and anchors into graph nodes. */
+  resolveReference(reference, options) {
+    return this.graph.resolveReference(reference, options);
+  }
+  /** Primary graph workflow helper for explaining why two nodes are connected. */
+  explainReferenceChain(fromId, toId) {
+    return this.graph.explainReferenceChain(fromId, toId);
+  }
 }
 class ScopedAgentSdk {
   constructor(base, actor, permissions) {
@@ -156,11 +283,26 @@ class ScopedAgentSdk {
   actor;
   permissions;
   assertAllowed(model, operation) {
-    const normalized = resolveModelDefinition(model).name;
+    const normalized = resolveModelDefinition(model, this.base.models).name;
     if (!operationAllowed(this.permissions, normalized, operation)) {
       throw new Error(`Agent "${this.actor}" is not allowed to ${operation} ${normalized}.`);
     }
   }
+  allowedModelsFor(operation) {
+    return this.permissions.filter((permission) => permission.operations.map(normalizeOperation).includes(normalizeOperation(operation))).map((permission) => resolveModelDefinition(permission.model, this.base.models).name);
+  }
+  async assertGraphNodeAllowed(id, operation) {
+    const node = await this.base.getGraphNode(id);
+    if (!node?.sourceModel) {
+      return node;
+    }
+    const allowedOps = operation === "get" ? ["search", "follow"] : [operation];
+    const permitted = allowedOps.some((op) => this.allowedModelsFor(op).includes(node.sourceModel));
+    if (!permitted) {
+      throw new Error(`Agent "${this.actor}" is not allowed to ${operation} graph node ${id}.`);
+    }
+    return node;
+  }
   get(request) {
     this.assertAllowed(request.model, "get");
     return this.base.get(request);
@@ -225,6 +367,88 @@ class ScopedAgentSdk {
   releaseAllLeases() {
     return this.base.releaseAllLeases();
   }
+  refreshGraph(request) {
+    return this.base.refreshGraph(request);
+  }
+  /** Advanced lexical graph primitive for file nodes. Scoped to models the agent may search. */
+  searchFiles(query, options) {
+    const allowedModels = this.allowedModelsFor("search");
+    return this.base.searchFiles(query, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  /** Advanced lexical graph primitive for section nodes. Scoped to models the agent may search. */
+  searchSections(query, options) {
+    const allowedModels = this.allowedModelsFor("search");
+    return this.base.searchSections(query, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  /** Advanced lexical graph primitive for entity nodes. Scoped to models the agent may search. */
+  searchEntities(query, options) {
+    const allowedModels = this.allowedModelsFor("search");
+    return this.base.searchEntities(query, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  async getGraphNode(id) {
+    return this.assertGraphNodeAllowed(id, "get");
+  }
+  async getNeighbors(id, options) {
+    await this.assertGraphNodeAllowed(id, "follow");
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.getNeighbors(id, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  async followReferences(id, options) {
+    await this.assertGraphNodeAllowed(id, "follow");
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.followReferences(id, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  async getBacklinks(id, options) {
+    await this.assertGraphNodeAllowed(id, "follow");
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.getBacklinks(id, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  async getRelated(id, options) {
+    await this.assertGraphNodeAllowed(id, "follow");
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.getRelated(id, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  getSubgraph(seedIds, options) {
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.getSubgraph(seedIds, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  /** Primary graph workflow helper, scoped to followable models. */
+  resolveSeeds(request) {
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.resolveSeeds({
+      ...request,
+      options: { ...request.options, models: request.options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels }
+    });
+  }
+  /** Primary graph workflow entrypoint for ranked graph retrieval, scoped to followable models. */
+  queryGraph(request) {
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.queryGraph({
+      ...request,
+      options: { ...request.options, models: request.options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels }
+    });
+  }
+  /** Primary graph workflow entrypoint for prompt-ready context assembly, scoped to followable models. */
+  buildContextPack(request) {
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.buildContextPack({
+      ...request,
+      options: { ...request.options, models: request.options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels }
+    });
+  }
+  parseGraphDsl(source) {
+    return this.base.parseGraphDsl(source);
+  }
+  resolveReference(reference, options) {
+    const allowedModels = this.allowedModelsFor("follow");
+    return this.base.resolveReference(reference, { ...options, models: options?.models?.filter((model) => allowedModels.includes(model)) ?? allowedModels });
+  }
+  explainReferenceChain(fromId, toId) {
+    return Promise.all([
+      this.assertGraphNodeAllowed(fromId, "follow"),
+      this.assertGraphNodeAllowed(toId, "follow")
+    ]).then(() => this.base.explainReferenceChain(fromId, toId));
+  }
 }
 export {
   AgentSdk,

package/dist/stores/cursor-store.js

@@ -1,3 +1,4 @@
+import { assertExpectedVersion } from "../sdk-version.js";
 import { SqliteStoreBase, nowIso, toSqlValue } from "./helpers.js";
 import { createCursorEnvelope, cursorEntityFromEnvelope, TRESEED_ENVELOPE_SCHEMA_VERSION } from "./envelopes.js";
 function cursorFromRow(row) {
@@ -98,9 +99,14 @@ class CursorStore extends SqliteStoreBase {
     );
   }
   async update(request) {
-    const agentSlug = String(request.data.agentSlug ?? request.id ?? request.key ?? "");
-    const cursorKey = String(request.data.cursorKey ?? request.slug ?? "");
-    const cursorValue = String(request.data.cursorValue ?? "");
+    const agentSlug = String(request.data.agent_slug ?? request.data.agentSlug ?? request.id ?? request.key ?? "");
+    const cursorKey = String(request.data.cursor_key ?? request.data.cursorKey ?? request.slug ?? "");
+    const cursorValue = String(request.data.cursor_value ?? request.data.cursorValue ?? "");
+    assertExpectedVersion(
+      request.expectedVersion,
+      await this.getByKey(`${agentSlug}:${cursorKey}`),
+      `agent_cursor "${agentSlug}:${cursorKey}"`
+    );
     await this.upsert({
       agentSlug,
       cursorKey,

package/dist/stores/lease-store.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { assertExpectedVersion } from "../sdk-version.js";
 import { SqliteStoreBase, nowIso, toSqlValue } from "./helpers.js";
 import { createLeaseEnvelope, leaseEntityFromEnvelope, TRESEED_ENVELOPE_SCHEMA_VERSION } from "./envelopes.js";
 function leaseFromRow(row) {
@@ -117,9 +118,14 @@ class LeaseStore extends SqliteStoreBase {
   }
   async update(request) {
     const model = String(request.data.model ?? request.id ?? "");
-    const itemKey = String(request.data.itemKey ?? request.slug ?? request.key ?? "");
-    const claimedBy = String(request.data.claimedBy ?? request.actor);
+    const itemKey = String(request.data.item_key ?? request.data.itemKey ?? request.slug ?? request.key ?? "");
+    const claimedBy = String(request.data.claimed_by ?? request.data.claimedBy ?? request.actor);
     const leaseSeconds = Number(request.data.leaseSeconds ?? 300);
+    assertExpectedVersion(
+      request.expectedVersion,
+      await this.getByKey(`${model}:${itemKey}`),
+      `content_lease "${model}:${itemKey}"`
+    );
     return this.create({ model, itemKey, claimedBy, leaseSeconds });
   }
   async releaseAll() {