@treeseed/sdk 0.1.2 → 0.3.1

package/dist/{src/stores → stores}/message-store.d.ts

@@ -5,7 +5,7 @@ export declare class MessageStore extends SqliteStoreBase {
     private usesEnvelopeTable;
     getById(id: number): Promise<SdkMessageEntity | null>;
     search(request: SdkSearchRequest): Promise<SdkMessageEntity[]>;
-    claim(request: SdkClaimMessageRequest): Promise<SdkMessageEntity | null>;
+    claim(request: SdkClaimMessageRequest, strategy?: 'latest' | 'highest_priority' | 'oldest'): Promise<SdkMessageEntity | null>;
     ack(request: SdkAckMessageRequest): Promise<void>;
     create(request: SdkCreateMessageRequest): Promise<SdkMessageEntity>;
     update(request: SdkUpdateRequest): Promise<SdkMessageEntity | null>;

package/dist/stores/message-store.js

@@ -1,3 +1,4 @@
+import { assertExpectedVersion } from "../sdk-version.js";
 import { SqliteStoreBase, nowIso, toSqlValue } from "./helpers.js";
 import { createMessageEnvelope, messageEntityFromEnvelope, TRESEED_ENVELOPE_SCHEMA_VERSION } from "./envelopes.js";
 function messageFromRow(row) {
@@ -36,6 +37,17 @@ function buildFilterSql(filters = []) {
 function buildOrderSql(sort = []) {
   return sort?.length ? `ORDER BY ${sort.map((entry) => `${entry.field} ${entry.direction === "asc" ? "ASC" : "DESC"}`).join(", ")}` : "";
 }
+function claimOrderSql(strategy) {
+  switch (strategy) {
+    case "oldest":
+      return "ORDER BY available_at ASC, priority DESC";
+    case "latest":
+      return "ORDER BY available_at DESC, priority DESC";
+    case "highest_priority":
+    default:
+      return "ORDER BY priority DESC, available_at ASC";
+  }
+}
 class MessageStore extends SqliteStoreBase {
   async usesEnvelopeTable() {
     return this.tableExists("message_queue");
@@ -68,11 +80,11 @@ class MessageStore extends SqliteStoreBase {
     const rows = await this.selectAll(sql);
     return rows.map(messageFromRow);
   }
-  async claim(request) {
+  async claim(request, strategy = "highest_priority") {
     if (await this.usesEnvelopeTable()) {
       const typeClause2 = request.messageTypes?.length ? ` AND message_type IN (${request.messageTypes.map(toSqlValue).join(", ")})` : "";
       const row2 = await this.selectFirst(
-        `SELECT * FROM message_queue WHERE status IN ('pending', 'failed') AND available_at <= ${toSqlValue(nowIso())}${typeClause2} ORDER BY priority DESC, available_at ASC LIMIT 1`
+        `SELECT * FROM message_queue WHERE status IN ('pending', 'failed') AND available_at <= ${toSqlValue(nowIso())}${typeClause2} ${claimOrderSql(strategy)} LIMIT 1`
       );
       if (!row2) {
         return null;
@@ -86,7 +98,7 @@ class MessageStore extends SqliteStoreBase {
     }
     const typeClause = request.messageTypes?.length ? ` AND type IN (${request.messageTypes.map(toSqlValue).join(", ")})` : "";
     const row = await this.selectFirst(
-      `SELECT * FROM messages WHERE status IN ('pending', 'failed') AND available_at <= ${toSqlValue(nowIso())}${typeClause} ORDER BY priority DESC, available_at ASC LIMIT 1`
+      `SELECT * FROM messages WHERE status IN ('pending', 'failed') AND available_at <= ${toSqlValue(nowIso())}${typeClause} ${claimOrderSql(strategy)} LIMIT 1`
     );
     if (!row) {
       return null;
@@ -136,6 +148,11 @@ class MessageStore extends SqliteStoreBase {
     if (!id) {
       throw new Error("Message update requires an id.");
     }
+    const existing = await this.getById(id);
+    if (!existing) {
+      return null;
+    }
+    assertExpectedVersion(request.expectedVersion, existing, `message ${id}`);
     if (await this.usesEnvelopeTable()) {
       const fields2 = [];
       for (const [key, value] of Object.entries(request.data)) {
@@ -226,18 +243,25 @@ function messageEnvelopeColumn(field) {
     case "type":
       return "message_type";
     case "relatedModel":
+    case "related_model":
       return "related_model";
     case "relatedId":
+    case "related_id":
       return "related_id";
     case "maxAttempts":
+    case "max_attempts":
       return "max_attempts";
     case "availableAt":
+    case "available_at":
       return "available_at";
     case "claimedBy":
+    case "claimed_by":
       return "claimed_by";
     case "claimedAt":
+    case "claimed_at":
       return "claimed_at";
     case "leaseExpiresAt":
+    case "lease_expires_at":
       return "lease_expires_at";
     default:
       return field.replace(/[A-Z]/g, (match) => `_${match.toLowerCase()}`);

package/dist/stores/operational-store.d.ts

@@ -0,0 +1,24 @@
+import type { SdkAppendTaskEventRequest, SdkClaimTaskRequest, SdkCloseWorkDayRequest, SdkCompleteTaskRequest, SdkCreateReportRequest, SdkCreateTaskRequest, SdkFailTaskRequest, SdkGraphRunEntity, SdkReportEntity, SdkStartWorkDayRequest, SdkTaskEntity, SdkTaskEventEntity, SdkTaskOutputEntity, SdkTaskProgressRequest, SdkTaskSearchRequest, SdkWorkDayEntity } from '../sdk-types.ts';
+import { SqliteStoreBase } from './helpers.ts';
+export declare class OperationalStore extends SqliteStoreBase {
+    getWorkDay(id: string): Promise<SdkWorkDayEntity | null>;
+    searchWorkDays(limit?: number): Promise<SdkWorkDayEntity[]>;
+    startWorkDay(request: SdkStartWorkDayRequest): Promise<SdkWorkDayEntity | null>;
+    closeWorkDay(request: SdkCloseWorkDayRequest): Promise<SdkWorkDayEntity | null>;
+    getTask(id: string): Promise<SdkTaskEntity | null>;
+    searchTasks(request?: SdkTaskSearchRequest): Promise<SdkTaskEntity[]>;
+    createTask(request: SdkCreateTaskRequest): Promise<SdkTaskEntity | null>;
+    claimTask(request: SdkClaimTaskRequest): Promise<SdkTaskEntity | null>;
+    recordTaskProgress(request: SdkTaskProgressRequest): Promise<SdkTaskEntity | null>;
+    completeTask(request: SdkCompleteTaskRequest): Promise<SdkTaskEntity | null>;
+    failTask(request: SdkFailTaskRequest): Promise<SdkTaskEntity | null>;
+    appendTaskEvent(request: SdkAppendTaskEventRequest): Promise<SdkTaskEventEntity | null>;
+    listTaskEvents(taskId: string): Promise<SdkTaskEventEntity[]>;
+    listTaskOutputs(taskId: string): Promise<SdkTaskOutputEntity[]>;
+    createGraphRun(input: Omit<SdkGraphRunEntity, 'createdAt'> & {
+        createdAt?: string;
+    }): Promise<SdkGraphRunEntity | null>;
+    getLatestGraphRun(workDayId: string): Promise<SdkGraphRunEntity | null>;
+    createReport(request: SdkCreateReportRequest): Promise<SdkReportEntity | null>;
+    getReport(id: string): Promise<SdkReportEntity | null>;
+}

package/dist/stores/operational-store.js

@@ -0,0 +1,279 @@
+import crypto from "node:crypto";
+import { SqliteStoreBase, nowIso, toSqlValue } from "./helpers.js";
+function json(value) {
+  return JSON.stringify(value ?? {});
+}
+function workDayFromRow(row) {
+  return {
+    id: String(row.id ?? ""),
+    projectId: String(row.project_id ?? row.projectId ?? ""),
+    state: String(row.state ?? "active"),
+    capacityBudget: Number(row.capacity_budget ?? row.capacityBudget ?? 0),
+    capacityUsed: Number(row.capacity_used ?? row.capacityUsed ?? 0),
+    graphVersion: row.graph_version !== void 0 && row.graph_version !== null ? String(row.graph_version) : row.graphVersion !== void 0 && row.graphVersion !== null ? String(row.graphVersion) : null,
+    summaryJson: row.summary_json !== void 0 && row.summary_json !== null ? String(row.summary_json) : row.summaryJson !== void 0 && row.summaryJson !== null ? String(row.summaryJson) : null,
+    startedAt: String(row.started_at ?? row.startedAt ?? nowIso()),
+    endedAt: row.ended_at !== void 0 && row.ended_at !== null ? String(row.ended_at) : row.endedAt !== void 0 && row.endedAt !== null ? String(row.endedAt) : null,
+    createdAt: String(row.created_at ?? row.createdAt ?? nowIso()),
+    updatedAt: String(row.updated_at ?? row.updatedAt ?? nowIso())
+  };
+}
+function taskFromRow(row) {
+  return {
+    id: String(row.id ?? ""),
+    workDayId: String(row.work_day_id ?? row.workDayId ?? ""),
+    agentId: String(row.agent_id ?? row.agentId ?? ""),
+    type: String(row.type ?? ""),
+    state: String(row.state ?? "pending"),
+    priority: Number(row.priority ?? 0),
+    idempotencyKey: String(row.idempotency_key ?? row.idempotencyKey ?? ""),
+    payloadJson: String(row.payload_json ?? row.payloadJson ?? "{}"),
+    payloadHash: row.payload_hash !== void 0 && row.payload_hash !== null ? String(row.payload_hash) : row.payloadHash !== void 0 && row.payloadHash !== null ? String(row.payloadHash) : null,
+    attemptCount: Number(row.attempt_count ?? row.attemptCount ?? 0),
+    maxAttempts: Number(row.max_attempts ?? row.maxAttempts ?? 3),
+    claimedBy: row.claimed_by !== void 0 && row.claimed_by !== null ? String(row.claimed_by) : row.claimedBy !== void 0 && row.claimedBy !== null ? String(row.claimedBy) : null,
+    leaseExpiresAt: row.lease_expires_at !== void 0 && row.lease_expires_at !== null ? String(row.lease_expires_at) : row.leaseExpiresAt !== void 0 && row.leaseExpiresAt !== null ? String(row.leaseExpiresAt) : null,
+    availableAt: String(row.available_at ?? row.availableAt ?? nowIso()),
+    lastErrorCode: row.last_error_code !== void 0 && row.last_error_code !== null ? String(row.last_error_code) : row.lastErrorCode !== void 0 && row.lastErrorCode !== null ? String(row.lastErrorCode) : null,
+    lastErrorMessage: row.last_error_message !== void 0 && row.last_error_message !== null ? String(row.last_error_message) : row.lastErrorMessage !== void 0 && row.lastErrorMessage !== null ? String(row.lastErrorMessage) : null,
+    graphVersion: row.graph_version !== void 0 && row.graph_version !== null ? String(row.graph_version) : row.graphVersion !== void 0 && row.graphVersion !== null ? String(row.graphVersion) : null,
+    parentTaskId: row.parent_task_id !== void 0 && row.parent_task_id !== null ? String(row.parent_task_id) : row.parentTaskId !== void 0 && row.parentTaskId !== null ? String(row.parentTaskId) : null,
+    createdAt: String(row.created_at ?? row.createdAt ?? nowIso()),
+    startedAt: row.started_at !== void 0 && row.started_at !== null ? String(row.started_at) : row.startedAt !== void 0 && row.startedAt !== null ? String(row.startedAt) : null,
+    completedAt: row.completed_at !== void 0 && row.completed_at !== null ? String(row.completed_at) : row.completedAt !== void 0 && row.completedAt !== null ? String(row.completedAt) : null,
+    updatedAt: String(row.updated_at ?? row.updatedAt ?? nowIso())
+  };
+}
+function taskEventFromRow(row) {
+  return {
+    id: String(row.id ?? ""),
+    taskId: String(row.task_id ?? row.taskId ?? ""),
+    seq: Number(row.seq ?? 0),
+    kind: String(row.kind ?? ""),
+    dataJson: String(row.data_json ?? row.dataJson ?? "{}"),
+    createdAt: String(row.created_at ?? row.createdAt ?? nowIso())
+  };
+}
+function taskOutputFromRow(row) {
+  return {
+    id: String(row.id ?? ""),
+    taskId: String(row.task_id ?? row.taskId ?? ""),
+    outputJson: String(row.output_json ?? row.outputJson ?? "{}"),
+    outputRef: row.output_ref !== void 0 && row.output_ref !== null ? String(row.output_ref) : row.outputRef !== void 0 && row.outputRef !== null ? String(row.outputRef) : null,
+    createdAt: String(row.created_at ?? row.createdAt ?? nowIso())
+  };
+}
+function graphRunFromRow(row) {
+  return {
+    id: String(row.id ?? ""),
+    workDayId: String(row.work_day_id ?? row.workDayId ?? ""),
+    corpusHash: String(row.corpus_hash ?? row.corpusHash ?? ""),
+    graphVersion: String(row.graph_version ?? row.graphVersion ?? ""),
+    queryJson: row.query_json !== void 0 && row.query_json !== null ? String(row.query_json) : row.queryJson !== void 0 && row.queryJson !== null ? String(row.queryJson) : null,
+    seedIdsJson: row.seed_ids_json !== void 0 && row.seed_ids_json !== null ? String(row.seed_ids_json) : row.seedIdsJson !== void 0 && row.seedIdsJson !== null ? String(row.seedIdsJson) : null,
+    selectedNodeIdsJson: row.selected_node_ids_json !== void 0 && row.selected_node_ids_json !== null ? String(row.selected_node_ids_json) : row.selectedNodeIdsJson !== void 0 && row.selectedNodeIdsJson !== null ? String(row.selectedNodeIdsJson) : null,
+    statsJson: row.stats_json !== void 0 && row.stats_json !== null ? String(row.stats_json) : row.statsJson !== void 0 && row.statsJson !== null ? String(row.statsJson) : null,
+    snapshotRef: row.snapshot_ref !== void 0 && row.snapshot_ref !== null ? String(row.snapshot_ref) : row.snapshotRef !== void 0 && row.snapshotRef !== null ? String(row.snapshotRef) : null,
+    createdAt: String(row.created_at ?? row.createdAt ?? nowIso())
+  };
+}
+function reportFromRow(row) {
+  return {
+    id: String(row.id ?? ""),
+    workDayId: String(row.work_day_id ?? row.workDayId ?? ""),
+    kind: String(row.kind ?? ""),
+    bodyJson: String(row.body_json ?? row.bodyJson ?? "{}"),
+    renderedRef: row.rendered_ref !== void 0 && row.rendered_ref !== null ? String(row.rendered_ref) : row.renderedRef !== void 0 && row.renderedRef !== null ? String(row.renderedRef) : null,
+    sentAt: row.sent_at !== void 0 && row.sent_at !== null ? String(row.sent_at) : row.sentAt !== void 0 && row.sentAt !== null ? String(row.sentAt) : null,
+    createdAt: String(row.created_at ?? row.createdAt ?? nowIso())
+  };
+}
+class OperationalStore extends SqliteStoreBase {
+  async getWorkDay(id) {
+    const row = await this.selectFirst(`SELECT * FROM work_days WHERE id = ${toSqlValue(id)} LIMIT 1`);
+    return row ? workDayFromRow(row) : null;
+  }
+  async searchWorkDays(limit = 20) {
+    const rows = await this.selectAll(`SELECT * FROM work_days ORDER BY updated_at DESC LIMIT ${limit}`);
+    return rows.map(workDayFromRow);
+  }
+  async startWorkDay(request) {
+    const id = request.id ?? crypto.randomUUID();
+    const timestamp = nowIso();
+    await this.execute(
+      `INSERT OR REPLACE INTO work_days (id, project_id, state, capacity_budget, capacity_used, graph_version, summary_json, started_at, ended_at, created_at, updated_at) VALUES (${toSqlValue(id)}, ${toSqlValue(request.projectId)}, 'active', ${Number(request.capacityBudget ?? 0)}, 0, ${toSqlValue(request.graphVersion ?? null)}, ${toSqlValue(json(request.summary ?? null))}, ${toSqlValue(timestamp)}, NULL, COALESCE((SELECT created_at FROM work_days WHERE id = ${toSqlValue(id)}), ${toSqlValue(timestamp)}), ${toSqlValue(timestamp)})`
+    );
+    return this.getWorkDay(id);
+  }
+  async closeWorkDay(request) {
+    const existing = await this.getWorkDay(request.id);
+    if (!existing) {
+      return null;
+    }
+    const timestamp = nowIso();
+    await this.execute(
+      `UPDATE work_days SET state = ${toSqlValue(request.state ?? "completed")}, summary_json = ${toSqlValue(json(request.summary ?? null))}, ended_at = ${toSqlValue(timestamp)}, updated_at = ${toSqlValue(timestamp)} WHERE id = ${toSqlValue(request.id)}`
+    );
+    return this.getWorkDay(request.id);
+  }
+  async getTask(id) {
+    const row = await this.selectFirst(`SELECT * FROM tasks WHERE id = ${toSqlValue(id)} LIMIT 1`);
+    return row ? taskFromRow(row) : null;
+  }
+  async searchTasks(request = {}) {
+    const clauses = [];
+    if (request.workDayId) clauses.push(`work_day_id = ${toSqlValue(request.workDayId)}`);
+    if (request.agentId) clauses.push(`agent_id = ${toSqlValue(request.agentId)}`);
+    if (request.state) {
+      const states = Array.isArray(request.state) ? request.state : [request.state];
+      clauses.push(`state IN (${states.map((entry) => toSqlValue(entry)).join(", ")})`);
+    }
+    const sql = [
+      "SELECT * FROM tasks",
+      clauses.length ? `WHERE ${clauses.join(" AND ")}` : "",
+      "ORDER BY priority DESC, available_at ASC, created_at ASC",
+      `LIMIT ${request.limit ?? 50}`
+    ].filter(Boolean).join(" ");
+    const rows = await this.selectAll(sql);
+    return rows.map(taskFromRow);
+  }
+  async createTask(request) {
+    const id = request.id ?? crypto.randomUUID();
+    const timestamp = nowIso();
+    await this.execute(
+      `INSERT OR REPLACE INTO tasks (id, work_day_id, agent_id, type, state, priority, idempotency_key, payload_json, payload_hash, attempt_count, max_attempts, claimed_by, lease_expires_at, available_at, last_error_code, last_error_message, graph_version, parent_task_id, created_at, started_at, completed_at, updated_at) VALUES (${toSqlValue(id)}, ${toSqlValue(request.workDayId)}, ${toSqlValue(request.agentId)}, ${toSqlValue(request.type)}, ${toSqlValue(request.state ?? "pending")}, ${Number(request.priority ?? 0)}, ${toSqlValue(request.idempotencyKey)}, ${toSqlValue(json(request.payload))}, ${toSqlValue(request.payloadHash ?? null)}, 0, ${Number(request.maxAttempts ?? 3)}, NULL, NULL, ${toSqlValue(request.availableAt ?? timestamp)}, NULL, NULL, ${toSqlValue(request.graphVersion ?? null)}, ${toSqlValue(request.parentTaskId ?? null)}, COALESCE((SELECT created_at FROM tasks WHERE id = ${toSqlValue(id)}), ${toSqlValue(timestamp)}), NULL, NULL, ${toSqlValue(timestamp)})`
+    );
+    return this.getTask(id);
+  }
+  async claimTask(request) {
+    const existing = await this.getTask(request.id);
+    if (!existing) {
+      return null;
+    }
+    const timestamp = nowIso();
+    const leaseExpiresAt = new Date(Date.now() + request.leaseSeconds * 1e3).toISOString();
+    await this.execute(
+      `UPDATE tasks SET state = 'claimed', claimed_by = ${toSqlValue(request.workerId)}, lease_expires_at = ${toSqlValue(leaseExpiresAt)}, attempt_count = attempt_count + 1, started_at = COALESCE(started_at, ${toSqlValue(timestamp)}), updated_at = ${toSqlValue(timestamp)} WHERE id = ${toSqlValue(request.id)}`
+    );
+    return this.getTask(request.id);
+  }
+  async recordTaskProgress(request) {
+    const existing = await this.getTask(request.id);
+    if (!existing) {
+      return null;
+    }
+    const patch = request.patch ?? {};
+    const currentPayload = JSON.parse(existing.payloadJson);
+    const nextPayload = { ...currentPayload, ...patch };
+    const timestamp = nowIso();
+    await this.execute(
+      `UPDATE tasks SET state = ${toSqlValue(request.state ?? existing.state)}, payload_json = ${toSqlValue(json(nextPayload))}, claimed_by = ${toSqlValue(request.workerId ?? existing.claimedBy)}, updated_at = ${toSqlValue(timestamp)} WHERE id = ${toSqlValue(request.id)}`
+    );
+    if (request.appendEvent?.kind) {
+      await this.appendTaskEvent({
+        taskId: request.id,
+        kind: request.appendEvent.kind,
+        data: request.appendEvent.data,
+        actor: request.actor
+      });
+    }
+    return this.getTask(request.id);
+  }
+  async completeTask(request) {
+    const existing = await this.getTask(request.id);
+    if (!existing) {
+      return null;
+    }
+    const timestamp = nowIso();
+    await this.execute(
+      `UPDATE tasks SET state = 'completed', completed_at = ${toSqlValue(timestamp)}, lease_expires_at = NULL, updated_at = ${toSqlValue(timestamp)} WHERE id = ${toSqlValue(request.id)}`
+    );
+    if (request.output) {
+      await this.execute(
+        `INSERT INTO task_outputs (id, task_id, output_json, output_ref, created_at) VALUES (${toSqlValue(crypto.randomUUID())}, ${toSqlValue(request.id)}, ${toSqlValue(json(request.output))}, ${toSqlValue(request.outputRef ?? null)}, ${toSqlValue(timestamp)})`
+      );
+    }
+    if (request.summary) {
+      await this.appendTaskEvent({
+        taskId: request.id,
+        kind: "completed",
+        data: request.summary,
+        actor: request.actor
+      });
+    }
+    return this.getTask(request.id);
+  }
+  async failTask(request) {
+    const existing = await this.getTask(request.id);
+    if (!existing) {
+      return null;
+    }
+    const timestamp = nowIso();
+    const nextState = request.retryable ? "pending" : "failed";
+    await this.execute(
+      `UPDATE tasks SET state = ${toSqlValue(nextState)}, available_at = ${toSqlValue(request.nextVisibleAt ?? existing.availableAt)}, last_error_code = ${toSqlValue(request.errorCode ?? null)}, last_error_message = ${toSqlValue(request.errorMessage)}, lease_expires_at = NULL, updated_at = ${toSqlValue(timestamp)} WHERE id = ${toSqlValue(request.id)}`
+    );
+    await this.appendTaskEvent({
+      taskId: request.id,
+      kind: nextState === "pending" ? "retry_scheduled" : "failed",
+      data: { errorCode: request.errorCode ?? null, errorMessage: request.errorMessage },
+      actor: request.actor
+    });
+    return this.getTask(request.id);
+  }
+  async appendTaskEvent(request) {
+    const seqRow = await this.selectFirst(
+      `SELECT COALESCE(MAX(seq), 0) + 1 AS next_seq FROM task_events WHERE task_id = ${toSqlValue(request.taskId)}`
+    );
+    const seq = Number(seqRow?.next_seq ?? 1);
+    const id = crypto.randomUUID();
+    const timestamp = nowIso();
+    await this.execute(
+      `INSERT INTO task_events (id, task_id, seq, kind, data_json, created_at) VALUES (${toSqlValue(id)}, ${toSqlValue(request.taskId)}, ${seq}, ${toSqlValue(request.kind)}, ${toSqlValue(json({ ...request.data ?? {}, actor: request.actor }))}, ${toSqlValue(timestamp)})`
+    );
+    const row = await this.selectFirst(`SELECT * FROM task_events WHERE id = ${toSqlValue(id)} LIMIT 1`);
+    return row ? taskEventFromRow(row) : null;
+  }
+  async listTaskEvents(taskId) {
+    const rows = await this.selectAll(
+      `SELECT * FROM task_events WHERE task_id = ${toSqlValue(taskId)} ORDER BY seq ASC`
+    );
+    return rows.map(taskEventFromRow);
+  }
+  async listTaskOutputs(taskId) {
+    const rows = await this.selectAll(
+      `SELECT * FROM task_outputs WHERE task_id = ${toSqlValue(taskId)} ORDER BY created_at ASC`
+    );
+    return rows.map(taskOutputFromRow);
+  }
+  async createGraphRun(input) {
+    const timestamp = input.createdAt ?? nowIso();
+    await this.execute(
+      `INSERT OR REPLACE INTO graph_runs (id, work_day_id, corpus_hash, graph_version, query_json, seed_ids_json, selected_node_ids_json, stats_json, snapshot_ref, created_at) VALUES (${toSqlValue(input.id)}, ${toSqlValue(input.workDayId)}, ${toSqlValue(input.corpusHash)}, ${toSqlValue(input.graphVersion)}, ${toSqlValue(input.queryJson ?? null)}, ${toSqlValue(input.seedIdsJson ?? null)}, ${toSqlValue(input.selectedNodeIdsJson ?? null)}, ${toSqlValue(input.statsJson ?? null)}, ${toSqlValue(input.snapshotRef ?? null)}, ${toSqlValue(timestamp)})`
+    );
+    const row = await this.selectFirst(`SELECT * FROM graph_runs WHERE id = ${toSqlValue(input.id)} LIMIT 1`);
+    return row ? graphRunFromRow(row) : null;
+  }
+  async getLatestGraphRun(workDayId) {
+    const row = await this.selectFirst(
+      `SELECT * FROM graph_runs WHERE work_day_id = ${toSqlValue(workDayId)} ORDER BY created_at DESC LIMIT 1`
+    );
+    return row ? graphRunFromRow(row) : null;
+  }
+  async createReport(request) {
+    const id = request.id ?? crypto.randomUUID();
+    const timestamp = nowIso();
+    await this.execute(
+      `INSERT OR REPLACE INTO reports (id, work_day_id, kind, body_json, rendered_ref, sent_at, created_at) VALUES (${toSqlValue(id)}, ${toSqlValue(request.workDayId)}, ${toSqlValue(request.kind)}, ${toSqlValue(json(request.body))}, ${toSqlValue(request.renderedRef ?? null)}, ${toSqlValue(request.sentAt ?? null)}, ${toSqlValue(timestamp)})`
+    );
+    const row = await this.selectFirst(`SELECT * FROM reports WHERE id = ${toSqlValue(id)} LIMIT 1`);
+    return row ? reportFromRow(row) : null;
+  }
+  async getReport(id) {
+    const row = await this.selectFirst(`SELECT * FROM reports WHERE id = ${toSqlValue(id)} LIMIT 1`);
+    return row ? reportFromRow(row) : null;
+  }
+}
+export {
+  OperationalStore
+};

package/dist/stores/run-store.js

@@ -1,3 +1,4 @@
+import { assertExpectedVersion } from "../sdk-version.js";
 import { SqliteStoreBase, nowIso, toSqlValue } from "./helpers.js";
 import { createRunEnvelope, runEntityFromEnvelope, TRESEED_ENVELOPE_SCHEMA_VERSION } from "./envelopes.js";
 function runFromRecord(row) {
@@ -109,10 +110,16 @@ class RunStore extends SqliteStoreBase {
     return run;
   }
   async update(request) {
+    const runId = String(request.data.run_id ?? request.data.runId ?? request.id ?? request.key ?? "");
+    assertExpectedVersion(
+      request.expectedVersion,
+      runId ? await this.getByKey(runId) : null,
+      `agent_run "${runId}"`
+    );
     return this.record({
       run: {
         ...request.data,
-        runId: request.data.runId ?? request.id ?? request.key
+        runId
       }
     });
   }

package/dist/stores/subscription-store.js

@@ -1,3 +1,4 @@
+import { assertExpectedVersion } from "../sdk-version.js";
 import { SqliteStoreBase, toSqlValue } from "./helpers.js";
 import { createSubscriptionEnvelope, subscriptionEntityFromEnvelope, TRESEED_ENVELOPE_SCHEMA_VERSION } from "./envelopes.js";
 function subscriptionFromRow(row) {
@@ -72,8 +73,8 @@ class SubscriptionStore extends SqliteStoreBase {
         name: data.name !== void 0 && data.name !== null ? String(data.name) : null,
         status: typeof data.status === "string" ? data.status : "active",
         source: typeof data.source === "string" ? data.source : "sdk",
-        consentAt: typeof data.consent_at === "string" ? data.consent_at : (/* @__PURE__ */ new Date()).toISOString(),
-        ipHash: typeof data.ip_hash === "string" ? data.ip_hash : ""
+        consentAt: typeof (data.consent_at ?? data.consentAt) === "string" ? String(data.consent_at ?? data.consentAt) : (/* @__PURE__ */ new Date()).toISOString(),
+        ipHash: typeof (data.ip_hash ?? data.ipHash) === "string" ? String(data.ip_hash ?? data.ipHash) : ""
       });
       const now = (/* @__PURE__ */ new Date()).toISOString();
       await this.execute(
@@ -82,7 +83,7 @@ class SubscriptionStore extends SqliteStoreBase {
       return this.getByKey(envelope.payload.email);
     }
     await this.execute(
-      `INSERT INTO subscriptions (email, name, status, source, consent_at, created_at, updated_at, ip_hash) VALUES (${toSqlValue(data.email)}, ${toSqlValue(data.name ?? null)}, ${toSqlValue(data.status ?? "active")}, ${toSqlValue(data.source ?? "sdk")}, ${toSqlValue(data.consent_at ?? (/* @__PURE__ */ new Date()).toISOString())}, ${toSqlValue(data.created_at ?? (/* @__PURE__ */ new Date()).toISOString())}, ${toSqlValue(data.updated_at ?? (/* @__PURE__ */ new Date()).toISOString())}, ${toSqlValue(data.ip_hash ?? "")})`
+      `INSERT INTO subscriptions (email, name, status, source, consent_at, created_at, updated_at, ip_hash) VALUES (${toSqlValue(data.email)}, ${toSqlValue(data.name ?? null)}, ${toSqlValue(data.status ?? "active")}, ${toSqlValue(data.source ?? "sdk")}, ${toSqlValue(data.consent_at ?? data.consentAt ?? (/* @__PURE__ */ new Date()).toISOString())}, ${toSqlValue(data.created_at ?? data.createdAt ?? (/* @__PURE__ */ new Date()).toISOString())}, ${toSqlValue(data.updated_at ?? data.updatedAt ?? (/* @__PURE__ */ new Date()).toISOString())}, ${toSqlValue(data.ip_hash ?? data.ipHash ?? "")})`
     );
     return this.getByKey(String(data.email));
   }
@@ -92,6 +93,7 @@ class SubscriptionStore extends SqliteStoreBase {
     if (!existing) {
       throw new Error(`No subscription found for "${key}".`);
     }
+    assertExpectedVersion(request.expectedVersion, existing, `subscription "${existing.email}"`);
     const next = {
       ...existing,
       ...request.data,
@@ -103,8 +105,8 @@ class SubscriptionStore extends SqliteStoreBase {
         name: next.name ?? null,
         status: String(next.status ?? "active"),
         source: typeof next.source === "string" ? next.source : "sdk",
-        consentAt: typeof next.consent_at === "string" ? next.consent_at : null,
-        ipHash: typeof next.ip_hash === "string" ? next.ip_hash : "",
+        consentAt: typeof (next.consent_at ?? next.consentAt) === "string" ? String(next.consent_at ?? next.consentAt) : null,
+        ipHash: typeof (next.ip_hash ?? next.ipHash) === "string" ? String(next.ip_hash ?? next.ipHash) : "",
         meta: { legacyId: existing.id }
       });
       await this.execute(

package/dist/template-catalog.d.ts

@@ -0,0 +1,13 @@
+import type { SdkTemplateCatalogEntry, SdkTemplateCatalogResponse } from './sdk-types.ts';
+export interface RemoteTemplateCatalogClientOptions {
+    endpoint: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function parseTemplateCatalogResponse(payload: unknown): SdkTemplateCatalogResponse;
+export declare class RemoteTemplateCatalogClient {
+    private readonly endpoint;
+    private readonly fetchImpl;
+    constructor(options: RemoteTemplateCatalogClientOptions);
+    listTemplates(): Promise<SdkTemplateCatalogResponse>;
+    getTemplate(id: string): Promise<SdkTemplateCatalogEntry | null>;
+}

package/dist/template-catalog.js

@@ -0,0 +1,141 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+function expectRecord(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Invalid template catalog response: expected ${label} to be an object.`);
+  }
+  return value;
+}
+function expectString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid template catalog response: expected ${label} to be a non-empty string.`);
+  }
+  return value.trim();
+}
+function optionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function optionalStringArray(value, label) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid template catalog response: expected ${label} to be an array.`);
+  }
+  return value.map((entry, index) => expectString(entry, `${label}[${index}]`));
+}
+function optionalBoolean(value, label) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "boolean") {
+    throw new Error(`Invalid template catalog response: expected ${label} to be a boolean.`);
+  }
+  return value;
+}
+function expectNumber(value, label) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error(`Invalid template catalog response: expected ${label} to be a number.`);
+  }
+  return value;
+}
+function normalizeTemplateCatalogEntry(value) {
+  const record = expectRecord(value, "template entry");
+  const publisher = expectRecord(record.publisher, "publisher");
+  const fulfillment = expectRecord(record.fulfillment, "fulfillment");
+  const source = expectRecord(fulfillment.source, "fulfillment.source");
+  const offer = record.offer === void 0 ? void 0 : expectRecord(record.offer, "offer");
+  return {
+    id: expectString(record.id ?? record.slug, "id"),
+    displayName: expectString(record.displayName ?? record.title, "displayName"),
+    description: expectString(record.description, "description"),
+    summary: expectString(record.summary, "summary"),
+    status: expectString(record.status ?? "draft", "status"),
+    featured: optionalBoolean(record.featured, "featured"),
+    category: expectString(record.category, "category"),
+    audience: optionalStringArray(record.audience, "audience") ?? [],
+    tags: optionalStringArray(record.tags, "tags") ?? [],
+    publisher: {
+      id: expectString(publisher.id, "publisher.id"),
+      name: expectString(publisher.name, "publisher.name"),
+      url: optionalString(publisher.url)
+    },
+    publisherVerified: optionalBoolean(record.publisherVerified, "publisherVerified"),
+    templateVersion: expectString(record.templateVersion, "templateVersion"),
+    templateApiVersion: expectNumber(record.templateApiVersion, "templateApiVersion"),
+    minCliVersion: expectString(record.minCliVersion, "minCliVersion"),
+    minCoreVersion: optionalString(record.minCoreVersion),
+    fulfillment: {
+      source: {
+        kind: "git",
+        repoUrl: expectString(source.repoUrl, "fulfillment.source.repoUrl"),
+        directory: expectString(source.directory, "fulfillment.source.directory"),
+        ref: expectString(source.ref, "fulfillment.source.ref"),
+        integrity: optionalString(source.integrity)
+      },
+      hooksPolicy: expectString(fulfillment.hooksPolicy ?? "builtin_only", "fulfillment.hooksPolicy"),
+      supportsReconcile: typeof fulfillment.supportsReconcile === "boolean" ? fulfillment.supportsReconcile : true
+    },
+    offer: offer ? {
+      priceModel: optionalString(offer.priceModel),
+      license: optionalString(offer.license),
+      support: optionalString(offer.support)
+    } : void 0,
+    relatedBooks: optionalStringArray(record.relatedBooks, "relatedBooks") ?? [],
+    relatedKnowledge: optionalStringArray(record.relatedKnowledge, "relatedKnowledge") ?? [],
+    relatedObjectives: optionalStringArray(record.relatedObjectives, "relatedObjectives") ?? []
+  };
+}
+function parseTemplateCatalogResponse(payload) {
+  if (Array.isArray(payload)) {
+    return {
+      items: payload.map((entry) => normalizeTemplateCatalogEntry(entry)),
+      meta: {}
+    };
+  }
+  const record = expectRecord(payload, "root");
+  const envelopePayload = record.payload;
+  const items = Array.isArray(record.items) ? record.items : Array.isArray(envelopePayload) ? envelopePayload : Array.isArray(expectRecord(envelopePayload ?? {}, "payload").items) ? expectRecord(envelopePayload ?? {}, "payload").items : null;
+  if (!items) {
+    throw new Error("Invalid template catalog response: expected an item array.");
+  }
+  return {
+    items: items.map((entry) => normalizeTemplateCatalogEntry(entry)),
+    meta: typeof record.meta === "object" && record.meta !== null ? record.meta : {}
+  };
+}
+async function loadTemplateCatalogPayload(endpoint, fetchImpl) {
+  if (endpoint.startsWith("file:")) {
+    const filePath = endpoint.startsWith("file://") ? new URL(endpoint) : resolve(process.cwd(), endpoint.slice("file:".length));
+    const raw = readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  }
+  const response = await fetchImpl(endpoint, {
+    headers: {
+      accept: "application/json"
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Template catalog request failed with ${response.status} ${response.statusText}.`);
+  }
+  return response.json();
+}
+class RemoteTemplateCatalogClient {
+  endpoint;
+  fetchImpl;
+  constructor(options) {
+    this.endpoint = options.endpoint;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+  }
+  async listTemplates() {
+    return parseTemplateCatalogResponse(await loadTemplateCatalogPayload(this.endpoint, this.fetchImpl));
+  }
+  async getTemplate(id) {
+    const catalog = await this.listTemplates();
+    return catalog.items.find((entry) => entry.id === id) ?? null;
+  }
+}
+export {
+  RemoteTemplateCatalogClient,
+  parseTemplateCatalogResponse
+};

package/dist/treeseed/services/compose.yml

@@ -0,0 +1,7 @@
+services:
+  mailpit:
+    image: axllent/mailpit:latest
+    container_name: treeseed_mailpit
+    ports:
+      - "1025:1025"
+      - "8025:8025"