@treeseed/sdk 0.1.1

package/dist/src/types/agents.d.ts

@@ -0,0 +1,100 @@
+export declare const AGENT_TRIGGER_KINDS: readonly ["schedule", "message", "follow", "startup"];
+export declare const AGENT_PERMISSION_OPERATIONS: readonly ["get", "read", "search", "follow", "pick", "create", "update"];
+export declare const AGENT_MESSAGE_STATUSES: readonly ["pending", "claimed", "completed", "failed", "dead_letter"];
+export declare const AGENT_RUN_STATUSES: readonly ["running", "completed", "failed", "waiting"];
+export declare const AGENT_HANDLER_KINDS: readonly ["planner", "architect", "engineer", "notifier", "researcher", "reviewer", "releaser"];
+export declare const AGENT_CLI_ALLOW_TOOLS: readonly ["shell(git)", "shell(npm)", "web"];
+export type AgentTriggerKind = (typeof AGENT_TRIGGER_KINDS)[number];
+export type AgentPermissionOperation = (typeof AGENT_PERMISSION_OPERATIONS)[number];
+export type AgentMessageStatus = (typeof AGENT_MESSAGE_STATUSES)[number];
+export type AgentRunStatus = (typeof AGENT_RUN_STATUSES)[number];
+export type AgentHandlerKind = string;
+export type AgentCliAllowTool = (typeof AGENT_CLI_ALLOW_TOOLS)[number];
+export interface AgentTriggerConfig {
+    type: AgentTriggerKind;
+    cron?: string;
+    messageTypes?: string[];
+    models?: string[];
+    sinceField?: string;
+    runOnStart?: boolean;
+}
+export interface AgentPermissionConfig {
+    model: string;
+    operations: AgentPermissionOperation[];
+}
+export interface AgentOutputContract {
+    messageTypes: string[];
+    modelMutations: string[];
+}
+export interface AgentExecutionConfig {
+    maxConcurrency: number;
+    timeoutSeconds: number;
+    cooldownSeconds: number;
+    leaseSeconds: number;
+    retryLimit: number;
+    branchPrefix: string;
+}
+export interface AgentTriggerPolicy {
+    maxRunsPerCycle?: number;
+    messageBatchSize?: number;
+}
+export interface AgentCliOptions {
+    model?: string;
+    allowTools?: AgentCliAllowTool[];
+    additionalArgs?: string[];
+}
+export interface AgentRuntimeSpec {
+    slug: string;
+    handler: AgentHandlerKind;
+    enabled: boolean;
+    systemPrompt: string;
+    persona: string;
+    cli: AgentCliOptions;
+    triggers: AgentTriggerConfig[];
+    triggerPolicy?: AgentTriggerPolicy;
+    permissions: AgentPermissionConfig[];
+    execution: AgentExecutionConfig;
+    outputs: AgentOutputContract;
+}
+export interface AgentMessageRecord {
+    [key: string]: unknown;
+    id: number;
+    type: string;
+    status: AgentMessageStatus;
+    payloadJson: string;
+    relatedModel: string | null;
+    relatedId: string | null;
+    priority: number;
+    availableAt: string;
+    claimedBy: string | null;
+    claimedAt: string | null;
+    leaseExpiresAt: string | null;
+    attempts: number;
+    maxAttempts: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AgentRunRecord {
+    [key: string]: unknown;
+    runId: string;
+    agentSlug: string;
+    triggerSource: string;
+    status: AgentRunStatus;
+    selectedItemKey: string | null;
+    selectedMessageId: number | null;
+    branchName: string | null;
+    prUrl: string | null;
+    summary: string | null;
+    error: string | null;
+    startedAt: string;
+    finishedAt: string | null;
+}
+export interface ContentLeaseRecord {
+    [key: string]: unknown;
+    model: string;
+    itemKey: string;
+    claimedBy: string;
+    claimedAt: string;
+    leaseExpiresAt: string;
+    token: string;
+}

package/dist/src/types/cloudflare.d.ts

@@ -0,0 +1,32 @@
+export interface KvNamespacePutOptions {
+    expirationTtl?: number;
+}
+export interface KvNamespaceLike {
+    get(key: string): Promise<string | null>;
+    put(key: string, value: string, options?: KvNamespacePutOptions): Promise<void>;
+}
+export interface D1PreparedStatementLike {
+    bind(...values: unknown[]): D1PreparedStatementLike;
+    run(): Promise<unknown>;
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    all<T = Record<string, unknown>>(): Promise<{
+        results: T[];
+    }>;
+    raw<T = unknown[]>(): Promise<T[]>;
+}
+export interface D1DatabaseLike {
+    prepare(query: string): D1PreparedStatementLike;
+    batch?(statements: D1PreparedStatementLike[]): Promise<unknown[]>;
+    exec?(query: string): Promise<unknown>;
+}
+export interface CloudflareRuntimeAssets {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+export interface CloudflareRuntime {
+    env: {
+        FORM_GUARD_KV: KvNamespaceLike;
+        SITE_DATA_DB: D1DatabaseLike;
+        SESSION: KvNamespaceLike;
+        ASSETS?: CloudflareRuntimeAssets;
+    };
+}

package/dist/src/wrangler-d1.d.ts

@@ -0,0 +1,25 @@
+import type { D1DatabaseLike, D1PreparedStatementLike } from './types/cloudflare.ts';
+declare class WranglerD1PreparedStatement implements D1PreparedStatementLike {
+    private readonly databaseName;
+    private readonly cwd;
+    private readonly persistTo?;
+    private readonly query;
+    private bindings;
+    constructor(databaseName: string, cwd: string, persistTo?: string | undefined, query?: string);
+    bind(...values: unknown[]): this;
+    private execute;
+    run(): Promise<any[]>;
+    all<T = Record<string, unknown>>(): Promise<{
+        results: T[];
+    }>;
+    first<T = Record<string, unknown>>(): Promise<NonNullable<T> | null>;
+    raw<T = unknown[]>(): Promise<T[]>;
+}
+export declare class WranglerD1Database implements D1DatabaseLike {
+    private readonly databaseName;
+    private readonly cwd;
+    private readonly persistTo?;
+    constructor(databaseName: string, cwd: string, persistTo?: string | undefined);
+    prepare(query: string): WranglerD1PreparedStatement;
+}
+export {};

package/dist/stores/cursor-store.js

@@ -0,0 +1,158 @@
+import { SqliteStoreBase, nowIso, toSqlValue } from "./helpers.js";
+import { createCursorEnvelope, cursorEntityFromEnvelope, TRESEED_ENVELOPE_SCHEMA_VERSION } from "./envelopes.js";
+function cursorFromRow(row) {
+  return {
+    agentSlug: String(row.agentSlug ?? row.agent_slug ?? ""),
+    cursorKey: String(row.cursorKey ?? row.cursor_key ?? ""),
+    cursorValue: String(row.cursorValue ?? row.cursor_value ?? ""),
+    updatedAt: row.updatedAt !== void 0 && row.updatedAt !== null ? String(row.updatedAt) : row.updated_at !== void 0 && row.updated_at !== null ? String(row.updated_at) : null
+  };
+}
+function buildFilterSql(filters = []) {
+  return filters?.length ? `WHERE ${filters.map((filter) => {
+    switch (filter.op) {
+      case "eq":
+        return `${filter.field} = ${toSqlValue(filter.value)}`;
+      case "in":
+        return `${filter.field} IN (${(Array.isArray(filter.value) ? filter.value : [filter.value]).map(toSqlValue).join(", ")})`;
+      case "updated_since":
+        return `${filter.field} >= ${toSqlValue(filter.value)}`;
+      default:
+        return `${filter.field} LIKE ${toSqlValue(`%${String(filter.value ?? "")}%`)}`;
+    }
+  }).join(" AND ")}` : "";
+}
+class CursorStore extends SqliteStoreBase {
+  async usesEnvelopeTable() {
+    return this.tableExists("cursor_state");
+  }
+  async getByKey(key) {
+    const [agentSlug, cursorKey] = key.split(":", 2);
+    if (!agentSlug || !cursorKey) {
+      return null;
+    }
+    if (await this.usesEnvelopeTable()) {
+      const row2 = await this.selectFirst(
+        `SELECT * FROM cursor_state WHERE agent_slug = ${toSqlValue(agentSlug)} AND cursor_key = ${toSqlValue(cursorKey)} LIMIT 1`
+      );
+      return row2 ? cursorEntityFromEnvelope(row2) : null;
+    }
+    const row = await this.selectFirst(
+      `SELECT * FROM agent_cursors WHERE agent_slug = ${toSqlValue(agentSlug)} AND cursor_key = ${toSqlValue(cursorKey)} LIMIT 1`
+    );
+    return row ? cursorFromRow(row) : null;
+  }
+  async get(request) {
+    if (await this.usesEnvelopeTable()) {
+      const row2 = await this.selectFirst(
+        `SELECT payload_json FROM cursor_state WHERE agent_slug = ${toSqlValue(request.agentSlug)} AND cursor_key = ${toSqlValue(request.cursorKey)} LIMIT 1`
+      );
+      if (typeof row2?.payload_json !== "string") {
+        return null;
+      }
+      try {
+        return String(JSON.parse(row2.payload_json).cursorValue ?? "");
+      } catch {
+        return null;
+      }
+    }
+    const row = await this.selectFirst(
+      `SELECT cursor_value FROM agent_cursors WHERE agent_slug = ${toSqlValue(request.agentSlug)} AND cursor_key = ${toSqlValue(request.cursorKey)} LIMIT 1`
+    );
+    return row?.cursor_value !== void 0 && row?.cursor_value !== null ? String(row.cursor_value) : null;
+  }
+  async search(request) {
+    if (await this.usesEnvelopeTable()) {
+      const sql2 = [
+        "SELECT * FROM cursor_state",
+        buildEnvelopeFilterSql(request.filters),
+        request.sort?.length ? `ORDER BY ${request.sort.map((entry) => `${cursorSortColumn(entry.field)} ${entry.direction === "asc" ? "ASC" : "DESC"}`).join(", ")}` : "",
+        request.limit ? `LIMIT ${request.limit}` : ""
+      ].filter(Boolean).join(" ");
+      const rows2 = await this.selectAll(sql2);
+      return rows2.map(cursorEntityFromEnvelope);
+    }
+    const sql = [
+      "SELECT * FROM agent_cursors",
+      buildFilterSql(request.filters),
+      request.sort?.length ? `ORDER BY ${request.sort.map((entry) => `${entry.field} ${entry.direction === "asc" ? "ASC" : "DESC"}`).join(", ")}` : "",
+      request.limit ? `LIMIT ${request.limit}` : ""
+    ].filter(Boolean).join(" ");
+    const rows = await this.selectAll(sql);
+    return rows.map(cursorFromRow);
+  }
+  async upsert(request) {
+    if (await this.usesEnvelopeTable()) {
+      const envelope = createCursorEnvelope({
+        agentSlug: request.agentSlug,
+        cursorKey: request.cursorKey,
+        cursorValue: request.cursorValue
+      });
+      await this.execute(
+        `INSERT OR REPLACE INTO cursor_state (agent_slug, cursor_key, status, schema_version, updated_at, payload_json, meta_json) VALUES (${toSqlValue(request.agentSlug)}, ${toSqlValue(request.cursorKey)}, ${toSqlValue(envelope.status)}, ${TRESEED_ENVELOPE_SCHEMA_VERSION}, ${toSqlValue(nowIso())}, ${toSqlValue(JSON.stringify(envelope.payload))}, ${toSqlValue(JSON.stringify(envelope.meta))})`
+      );
+      return;
+    }
+    await this.execute(
+      `INSERT OR REPLACE INTO agent_cursors (agent_slug, cursor_key, cursor_value, updated_at) VALUES (${toSqlValue(request.agentSlug)}, ${toSqlValue(request.cursorKey)}, ${toSqlValue(request.cursorValue)}, ${toSqlValue(nowIso())})`
+    );
+  }
+  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 ?? "");
+    await this.upsert({
+      agentSlug,
+      cursorKey,
+      cursorValue
+    });
+    return this.getByKey(`${agentSlug}:${cursorKey}`);
+  }
+}
+function buildEnvelopeFilterSql(filters = []) {
+  return filters?.length ? `WHERE ${filters.map((filter) => {
+    const field = cursorFilterColumn(filter.field);
+    switch (filter.op) {
+      case "eq":
+        return `${field} = ${toSqlValue(filter.value)}`;
+      case "in":
+        return `${field} IN (${(Array.isArray(filter.value) ? filter.value : [filter.value]).map(toSqlValue).join(", ")})`;
+      case "updated_since":
+        return `updated_at >= ${toSqlValue(filter.value)}`;
+      default:
+        return `${field} LIKE ${toSqlValue(`%${String(filter.value ?? "")}%`)}`;
+    }
+  }).join(" AND ")}` : "";
+}
+function cursorFilterColumn(field) {
+  switch (field) {
+    case "agentSlug":
+    case "agent_slug":
+      return "agent_slug";
+    case "cursorKey":
+    case "cursor_key":
+      return "cursor_key";
+    case "updatedAt":
+    case "updated_at":
+      return "updated_at";
+    default:
+      return `json_extract(payload_json, '$.${field}')`;
+  }
+}
+function cursorSortColumn(field) {
+  switch (field) {
+    case "agentSlug":
+    case "agent_slug":
+      return "agent_slug";
+    case "cursorKey":
+    case "cursor_key":
+      return "cursor_key";
+    case "updatedAt":
+    case "updated_at":
+    default:
+      return "updated_at";
+  }
+}
+export {
+  CursorStore
+};

package/dist/stores/envelopes.js

@@ -0,0 +1,219 @@
+const TRESEED_ENVELOPE_SCHEMA_VERSION = 1;
+function parseJsonObject(value, fallback) {
+  if (typeof value !== "string" || value.trim().length === 0) return fallback;
+  try {
+    return { ...fallback, ...JSON.parse(value) };
+  } catch {
+    return fallback;
+  }
+}
+function createSubscriptionEnvelope(input) {
+  return {
+    recordType: "subscription",
+    schemaVersion: TRESEED_ENVELOPE_SCHEMA_VERSION,
+    status: input.status ?? "active",
+    payload: {
+      email: input.email,
+      name: input.name ?? null,
+      source: input.source ?? "sdk",
+      consentAt: input.consentAt ?? null,
+      ipHash: input.ipHash ?? ""
+    },
+    meta: input.meta ?? {}
+  };
+}
+function subscriptionEntityFromEnvelope(row) {
+  const payload = parseJsonObject(row.payload_json, {
+    email: String(row.record_key ?? row.lookup_key ?? ""),
+    name: null,
+    source: "sdk",
+    consentAt: null,
+    ipHash: ""
+  });
+  return {
+    id: row.id !== void 0 ? Number(row.id) : void 0,
+    recordType: "subscription",
+    schemaVersion: Number(row.schema_version ?? TRESEED_ENVELOPE_SCHEMA_VERSION),
+    email: payload.email,
+    name: payload.name,
+    status: String(row.status ?? "active"),
+    source: payload.source,
+    consent_at: payload.consentAt ?? void 0,
+    created_at: row.created_at ? String(row.created_at) : void 0,
+    updated_at: row.updated_at ? String(row.updated_at) : void 0,
+    ip_hash: payload.ipHash,
+    metaJson: typeof row.meta_json === "string" ? row.meta_json : "{}"
+  };
+}
+function createContactSubmissionEnvelope(input) {
+  return {
+    recordType: "contact_submission",
+    schemaVersion: TRESEED_ENVELOPE_SCHEMA_VERSION,
+    status: "received",
+    payload: {
+      name: input.name,
+      email: input.email,
+      organization: input.organization ?? null,
+      contactType: input.contactType,
+      subject: input.subject,
+      message: input.message,
+      userAgent: input.userAgent,
+      ipHash: input.ipHash
+    },
+    meta: input.meta ?? {}
+  };
+}
+function createMessageEnvelope(input) {
+  return {
+    recordType: "message",
+    schemaVersion: TRESEED_ENVELOPE_SCHEMA_VERSION,
+    status: "pending",
+    payload: { body: input.payload },
+    meta: input.meta ?? {}
+  };
+}
+function messageEntityFromEnvelope(row) {
+  const payload = parseJsonObject(row.payload_json, { body: {} });
+  return {
+    id: Number(row.id ?? 0),
+    recordType: "message",
+    schemaVersion: Number(row.schema_version ?? TRESEED_ENVELOPE_SCHEMA_VERSION),
+    type: String(row.message_type ?? ""),
+    status: String(row.status ?? "pending"),
+    payloadJson: JSON.stringify(payload.body ?? {}),
+    metaJson: typeof row.meta_json === "string" ? row.meta_json : "{}",
+    relatedModel: row.related_model ? String(row.related_model) : null,
+    relatedId: row.related_id ? String(row.related_id) : null,
+    priority: Number(row.priority ?? 0),
+    availableAt: String(row.available_at ?? ""),
+    claimedBy: row.claimed_by ? String(row.claimed_by) : null,
+    claimedAt: row.claimed_at ? String(row.claimed_at) : null,
+    leaseExpiresAt: row.lease_expires_at ? String(row.lease_expires_at) : null,
+    attempts: Number(row.attempts ?? 0),
+    maxAttempts: Number(row.max_attempts ?? 3),
+    createdAt: String(row.created_at ?? ""),
+    updatedAt: String(row.updated_at ?? "")
+  };
+}
+function createRunEnvelope(input) {
+  return {
+    recordType: "agent_run",
+    schemaVersion: TRESEED_ENVELOPE_SCHEMA_VERSION,
+    status: input.status,
+    payload: {
+      triggerSource: input.triggerSource,
+      handlerKind: input.handlerKind ?? null,
+      triggerKind: input.triggerKind ?? null,
+      selectedItemKey: input.selectedItemKey ?? null,
+      selectedMessageId: input.selectedMessageId ?? null,
+      claimedMessageId: input.claimedMessageId ?? null,
+      branchName: input.branchName ?? null,
+      prUrl: input.prUrl ?? null,
+      summary: input.summary ?? null,
+      error: input.error ?? null,
+      errorCategory: input.errorCategory ?? null,
+      commitSha: input.commitSha ?? null,
+      changedPaths: input.changedPaths ?? [],
+      finishedAt: input.finishedAt ?? null
+    },
+    meta: {
+      runId: input.runId,
+      agentSlug: input.agentSlug
+    }
+  };
+}
+function runEntityFromEnvelope(row) {
+  const payload = parseJsonObject(row.payload_json, {
+    triggerSource: "",
+    selectedItemKey: null,
+    selectedMessageId: null,
+    branchName: null,
+    prUrl: null,
+    summary: null,
+    error: null,
+    changedPaths: [],
+    finishedAt: null
+  });
+  const meta = parseJsonObject(row.meta_json, {
+    runId: String(row.record_key ?? ""),
+    agentSlug: String(row.lookup_key ?? "")
+  });
+  return {
+    recordType: "agent_run",
+    schemaVersion: Number(row.schema_version ?? TRESEED_ENVELOPE_SCHEMA_VERSION),
+    runId: meta.runId,
+    agentSlug: meta.agentSlug,
+    status: String(row.status ?? ""),
+    triggerSource: payload.triggerSource,
+    handlerKind: payload.handlerKind ?? null,
+    triggerKind: payload.triggerKind ?? null,
+    selectedItemKey: payload.selectedItemKey ?? null,
+    selectedMessageId: payload.selectedMessageId ?? null,
+    claimedMessageId: payload.claimedMessageId ?? null,
+    branchName: payload.branchName ?? null,
+    prUrl: payload.prUrl ?? null,
+    summary: payload.summary ?? null,
+    error: payload.error ?? null,
+    errorCategory: payload.errorCategory ?? null,
+    commitSha: payload.commitSha ?? (row.secondary_key ? String(row.secondary_key) : null),
+    changedPaths: payload.changedPaths ?? [],
+    startedAt: String(row.created_at ?? ""),
+    finishedAt: payload.finishedAt ?? null
+  };
+}
+function createCursorEnvelope(input) {
+  return {
+    recordType: "agent_cursor",
+    schemaVersion: TRESEED_ENVELOPE_SCHEMA_VERSION,
+    status: "active",
+    payload: { cursorValue: input.cursorValue },
+    meta: input.meta ?? {}
+  };
+}
+function cursorEntityFromEnvelope(row) {
+  const payload = parseJsonObject(row.payload_json, { cursorValue: "" });
+  return {
+    recordType: "agent_cursor",
+    schemaVersion: Number(row.schema_version ?? TRESEED_ENVELOPE_SCHEMA_VERSION),
+    agentSlug: String(row.agent_slug ?? ""),
+    cursorKey: String(row.cursor_key ?? ""),
+    cursorValue: payload.cursorValue,
+    updatedAt: row.updated_at ? String(row.updated_at) : null
+  };
+}
+function createLeaseEnvelope(input) {
+  return {
+    recordType: "content_lease",
+    schemaVersion: TRESEED_ENVELOPE_SCHEMA_VERSION,
+    status: "claimed",
+    payload: { token: input.token },
+    meta: input.meta ?? {}
+  };
+}
+function leaseEntityFromEnvelope(row) {
+  const payload = parseJsonObject(row.payload_json, { token: "" });
+  return {
+    recordType: "content_lease",
+    schemaVersion: Number(row.schema_version ?? TRESEED_ENVELOPE_SCHEMA_VERSION),
+    model: String(row.model ?? ""),
+    itemKey: String(row.item_key ?? ""),
+    claimedBy: row.claimed_by ? String(row.claimed_by) : "",
+    claimedAt: row.claimed_at ? String(row.claimed_at) : "",
+    leaseExpiresAt: row.lease_expires_at ? String(row.lease_expires_at) : "",
+    token: payload.token
+  };
+}
+export {
+  TRESEED_ENVELOPE_SCHEMA_VERSION,
+  createContactSubmissionEnvelope,
+  createCursorEnvelope,
+  createLeaseEnvelope,
+  createMessageEnvelope,
+  createRunEnvelope,
+  createSubscriptionEnvelope,
+  cursorEntityFromEnvelope,
+  leaseEntityFromEnvelope,
+  messageEntityFromEnvelope,
+  runEntityFromEnvelope,
+  subscriptionEntityFromEnvelope
+};

package/dist/stores/helpers.js

@@ -0,0 +1,42 @@
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function toSqlValue(value) {
+  if (value === null || value === void 0) {
+    return "NULL";
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? "1" : "0";
+  }
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+class SqliteStoreBase {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  async selectAll(query) {
+    const result = await this.db.prepare(query).all();
+    return result.results ?? [];
+  }
+  async selectFirst(query) {
+    return this.db.prepare(query).first();
+  }
+  async execute(query) {
+    await this.db.prepare(query).run();
+  }
+  async tableExists(tableName) {
+    const row = await this.selectFirst(
+      `SELECT name FROM sqlite_master WHERE type = 'table' AND name = ${toSqlValue(tableName)} LIMIT 1`
+    );
+    return Boolean(row?.name);
+  }
+}
+export {
+  SqliteStoreBase,
+  nowIso,
+  toSqlValue
+};