@treeseed/agent 0.1.2

package/dist/agents/contracts/messages.js

@@ -0,0 +1,138 @@
+const AGENT_MESSAGE_TYPES = [
+  "question_priority_updated",
+  "objective_priority_updated",
+  "architecture_updated",
+  "subscriber_notified",
+  "research_started",
+  "research_completed",
+  "task_complete",
+  "task_waiting",
+  "task_failed",
+  "task_verified",
+  "review_failed",
+  "review_waiting",
+  "release_started",
+  "release_completed",
+  "release_failed"
+];
+function ensureString(value, label) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`Invalid ${label}: expected non-empty string.`);
+  }
+  return value;
+}
+function ensureOptionalString(value, label) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  return ensureString(value, label);
+}
+function ensureStringArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new Error(`Invalid ${label}: expected array.`);
+  }
+  return value.map((entry, index) => ensureString(entry, `${label}[${index}]`));
+}
+function ensureNumber(value, label) {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    throw new Error(`Invalid ${label}: expected number.`);
+  }
+  return value;
+}
+function parseAgentMessagePayload(type, payloadJson) {
+  const parsed = JSON.parse(payloadJson);
+  switch (type) {
+    case "question_priority_updated":
+      return {
+        questionId: ensureString(parsed.questionId, "questionId"),
+        reason: ensureString(parsed.reason, "reason"),
+        plannerRunId: ensureString(parsed.plannerRunId, "plannerRunId")
+      };
+    case "objective_priority_updated":
+      return {
+        objectiveId: ensureString(parsed.objectiveId, "objectiveId"),
+        reason: ensureString(parsed.reason, "reason"),
+        plannerRunId: ensureString(parsed.plannerRunId, "plannerRunId")
+      };
+    case "architecture_updated":
+      return {
+        objectiveId: ensureString(parsed.objectiveId, "objectiveId"),
+        knowledgeId: ensureString(parsed.knowledgeId, "knowledgeId"),
+        architectRunId: ensureString(parsed.architectRunId, "architectRunId")
+      };
+    case "subscriber_notified":
+      return {
+        email: ensureString(parsed.email, "email"),
+        itemCount: ensureNumber(parsed.itemCount, "itemCount"),
+        notifierRunId: ensureString(parsed.notifierRunId, "notifierRunId")
+      };
+    case "research_started":
+      return {
+        questionId: ensureString(parsed.questionId, "questionId"),
+        researcherRunId: ensureString(parsed.researcherRunId, "researcherRunId")
+      };
+    case "research_completed":
+      return {
+        questionId: ensureString(parsed.questionId, "questionId"),
+        knowledgeId: ensureOptionalString(parsed.knowledgeId, "knowledgeId"),
+        researcherRunId: ensureString(parsed.researcherRunId, "researcherRunId")
+      };
+    case "task_complete":
+      return {
+        branchName: ensureOptionalString(parsed.branchName, "branchName"),
+        changedTargets: ensureStringArray(parsed.changedTargets, "changedTargets"),
+        engineerRunId: ensureString(parsed.engineerRunId, "engineerRunId")
+      };
+    case "task_waiting":
+      return {
+        blockingReason: ensureString(parsed.blockingReason, "blockingReason"),
+        engineerRunId: ensureString(parsed.engineerRunId, "engineerRunId")
+      };
+    case "task_failed":
+      return {
+        failureSummary: ensureString(parsed.failureSummary, "failureSummary"),
+        engineerRunId: ensureString(parsed.engineerRunId, "engineerRunId")
+      };
+    case "task_verified":
+      return {
+        branchName: ensureOptionalString(parsed.branchName, "branchName"),
+        reviewerRunId: ensureString(parsed.reviewerRunId, "reviewerRunId")
+      };
+    case "review_failed":
+      return {
+        failureSummary: ensureString(parsed.failureSummary, "failureSummary"),
+        reviewerRunId: ensureString(parsed.reviewerRunId, "reviewerRunId")
+      };
+    case "review_waiting":
+      return {
+        blockingReason: ensureString(parsed.blockingReason, "blockingReason"),
+        reviewerRunId: ensureString(parsed.reviewerRunId, "reviewerRunId")
+      };
+    case "release_started":
+      return {
+        taskRunId: ensureOptionalString(parsed.taskRunId, "taskRunId"),
+        releaserRunId: ensureString(parsed.releaserRunId, "releaserRunId")
+      };
+    case "release_completed":
+      return {
+        releaseSummary: ensureString(parsed.releaseSummary, "releaseSummary"),
+        releaserRunId: ensureString(parsed.releaserRunId, "releaserRunId")
+      };
+    case "release_failed":
+      return {
+        failureSummary: ensureString(parsed.failureSummary, "failureSummary"),
+        releaserRunId: ensureString(parsed.releaserRunId, "releaserRunId")
+      };
+    default:
+      throw new Error(`Unsupported message type "${type}".`);
+  }
+}
+function serializeAgentMessagePayload(type, payload) {
+  parseAgentMessagePayload(type, JSON.stringify(payload));
+  return payload;
+}
+export {
+  AGENT_MESSAGE_TYPES,
+  parseAgentMessagePayload,
+  serializeAgentMessagePayload
+};

package/dist/agents/d1-store.js

@@ -0,0 +1 @@
+export * from "@treeseed/sdk/d1-store";

package/dist/agents/frontmatter.js

@@ -0,0 +1 @@
+export * from "@treeseed/sdk/frontmatter";

package/dist/agents/git-runtime.js

@@ -0,0 +1 @@
+export * from "@treeseed/sdk/git-runtime";

package/dist/agents/index.js

@@ -0,0 +1,5 @@
+import { AGENT_HANDLER_REGISTRY, resolveAgentHandler } from "./registry.js";
+export {
+  AGENT_HANDLER_REGISTRY,
+  resolveAgentHandler
+};

package/dist/agents/kernel/agent-kernel.js

@@ -0,0 +1,284 @@
+import { createExecutionAdapter } from "../adapters/execution.js";
+import { LocalBranchMutationAdapter } from "../adapters/mutations.js";
+import { createNotificationAdapter } from "../adapters/notification.js";
+import { createRepositoryInspectionAdapter } from "../adapters/repository.js";
+import { createResearchAdapter } from "../adapters/research.js";
+import { createVerificationAdapter } from "../adapters/verification.js";
+import { resolveAgentHandler } from "../registry.js";
+import { resolveTriggerDecision } from "./trigger-resolver.js";
+import { loadActiveAgentSpecs, loadAllAgentSpecs, summarizeAgentSpec } from "../spec-loader.js";
+import { getTreeseedAgentProviderSelections } from "@treeseed/core/deploy/runtime";
+import { resolveAgentRuntimeProviders } from "../../agent-runtime.js";
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+class AgentKernel {
+  constructor(sdk, repoRoot, options) {
+    this.sdk = sdk;
+    this.repoRoot = repoRoot;
+    const runtimeProviders = resolveAgentRuntimeProviders(repoRoot, getTreeseedAgentProviderSelections());
+    this.execution = options?.execution ?? runtimeProviders.execution ?? createExecutionAdapter();
+    this.mutations = options?.mutations ?? runtimeProviders.mutations ?? new LocalBranchMutationAdapter(repoRoot);
+    this.repository = options?.repository ?? runtimeProviders.repository ?? createRepositoryInspectionAdapter();
+    this.verification = options?.verification ?? runtimeProviders.verification ?? createVerificationAdapter();
+    this.notifications = options?.notifications ?? runtimeProviders.notifications ?? createNotificationAdapter();
+    this.research = options?.research ?? runtimeProviders.research ?? createResearchAdapter();
+  }
+  sdk;
+  repoRoot;
+  execution;
+  mutations;
+  repository;
+  verification;
+  notifications;
+  research;
+  activeRuns = /* @__PURE__ */ new Set();
+  lastRunAt = /* @__PURE__ */ new Map();
+  async doctor() {
+    const { specs, diagnostics } = await loadAllAgentSpecs(this.sdk);
+    for (const agent of specs.filter((entry) => entry.enabled)) {
+      resolveAgentHandler(agent.handler);
+    }
+    const errors = diagnostics.filter((entry) => entry.severity === "error");
+    if (errors.length) {
+      throw new Error(
+        `Agent spec validation failed: ${errors.map((entry) => `${entry.slug}:${entry.field}:${entry.message}`).join(" | ")}`
+      );
+    }
+    return {
+      agents: specs.map(summarizeAgentSpec),
+      diagnostics
+    };
+  }
+  sortAgents(agents) {
+    const priority = {
+      planner: 10,
+      researcher: 20,
+      architect: 30,
+      engineer: 40,
+      reviewer: 50,
+      releaser: 60,
+      notifier: 70
+    };
+    return [...agents].sort(
+      (left, right) => (priority[left.handler] ?? 100) - (priority[right.handler] ?? 100)
+    );
+  }
+  async resolveTrigger(agent, mode = "auto") {
+    const decision = await resolveTriggerDecision({
+      agent,
+      mode,
+      isRunning: this.activeRuns.has(agent.slug),
+      lastRunAt: this.lastRunAt.get(agent.slug),
+      sdk: this.sdk.scopeForAgent(agent)
+    });
+    return decision.kind === "ready" ? decision.invocation ?? null : null;
+  }
+  async recordRunTrace(trace) {
+    await this.sdk.recordRun({ run: trace });
+  }
+  buildTrace(agent, runId, trigger, overrides) {
+    return {
+      runId,
+      agentSlug: agent.slug,
+      handlerKind: agent.handler,
+      triggerKind: trigger.kind,
+      triggerSource: trigger.source,
+      claimedMessageId: trigger.message?.id ?? null,
+      selectedItemKey: null,
+      branchName: null,
+      commitSha: null,
+      changedPaths: [],
+      summary: null,
+      error: null,
+      errorCategory: null,
+      startedAt: nowIso(),
+      finishedAt: null,
+      status: "running",
+      ...overrides
+    };
+  }
+  categorizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("not allowed")) {
+      return "permission_error";
+    }
+    if (message.includes("message")) {
+      return "message_claim_error";
+    }
+    if (message.includes("lease")) {
+      return "lease_error";
+    }
+    if (message.includes("commit") || message.includes("worktree") || message.includes("artifact")) {
+      return "mutation_error";
+    }
+    if (message.includes("Copilot") || message.includes("execution")) {
+      return "execution_error";
+    }
+    return "sdk_error";
+  }
+  async executeAgent(agent, trigger) {
+    if (this.activeRuns.has(agent.slug)) {
+      return {
+        status: "waiting",
+        summary: `Agent ${agent.slug} is already running.`
+      };
+    }
+    this.activeRuns.add(agent.slug);
+    const runId = crypto.randomUUID();
+    const handler = resolveAgentHandler(agent.handler);
+    const scopedSdk = this.sdk.scopeForAgent(agent);
+    const context = {
+      runId,
+      repoRoot: this.repoRoot,
+      agent,
+      sdk: scopedSdk,
+      trigger,
+      execution: this.execution,
+      mutations: this.mutations,
+      repository: this.repository,
+      verification: this.verification,
+      notifications: this.notifications,
+      research: this.research
+    };
+    await this.recordRunTrace(this.buildTrace(agent, runId, trigger, {}));
+    try {
+      const inputs = await handler.resolveInputs(context);
+      const result = await handler.execute(context, inputs);
+      const output = await handler.emitOutputs(context, result);
+      if (trigger.message) {
+        await scopedSdk.ackMessage({
+          id: trigger.message.id,
+          status: output.status === "completed" ? "completed" : output.status === "waiting" ? "pending" : "failed"
+        });
+      }
+      await this.recordRunTrace(
+        this.buildTrace(agent, runId, trigger, {
+          status: output.status,
+          branchName: output.metadata?.branchName ?? null,
+          commitSha: output.metadata?.commitSha ?? null,
+          changedPaths: output.metadata?.changedPaths ?? [],
+          summary: output.summary,
+          error: output.status === "failed" ? output.stderr ?? output.summary : null,
+          errorCategory: output.status === "failed" ? output.errorCategory ?? "execution_error" : null,
+          finishedAt: nowIso()
+        })
+      );
+      await this.sdk.upsertCursor({
+        agentSlug: agent.slug,
+        cursorKey: "last_run_at",
+        cursorValue: nowIso()
+      });
+      this.lastRunAt.set(agent.slug, Date.now());
+      return output;
+    } catch (error) {
+      if (trigger.message) {
+        await scopedSdk.ackMessage({
+          id: trigger.message.id,
+          status: "failed"
+        });
+      }
+      await this.recordRunTrace(
+        this.buildTrace(agent, runId, trigger, {
+          status: "failed",
+          error: error instanceof Error ? error.message : String(error),
+          errorCategory: this.categorizeError(error),
+          finishedAt: nowIso()
+        })
+      );
+      throw error;
+    } finally {
+      this.activeRuns.delete(agent.slug);
+    }
+  }
+  async runAgent(slug, mode = "manual") {
+    const { specs, diagnostics } = await loadActiveAgentSpecs(this.sdk);
+    const errors = diagnostics.filter((entry) => entry.severity === "error");
+    if (errors.length) {
+      throw new Error(
+        `Agent spec validation failed: ${errors.map((entry) => `${entry.slug}:${entry.field}:${entry.message}`).join(" | ")}`
+      );
+    }
+    const agents = this.sortAgents(specs);
+    const agent = agents.find((entry) => entry.slug === slug);
+    if (!agent) {
+      throw new Error(`Unknown or disabled agent "${slug}".`);
+    }
+    const trigger = await this.resolveTrigger(agent, mode);
+    if (!trigger) {
+      return {
+        status: "waiting",
+        summary: `No runnable trigger found for ${slug}.`
+      };
+    }
+    return this.executeAgent(agent, trigger);
+  }
+  async runCycle() {
+    const { specs, diagnostics } = await loadActiveAgentSpecs(this.sdk);
+    const errors = diagnostics.filter((entry) => entry.severity === "error");
+    if (errors.length) {
+      throw new Error(
+        `Agent spec validation failed: ${errors.map((entry) => `${entry.slug}:${entry.field}:${entry.message}`).join(" | ")}`
+      );
+    }
+    const agents = this.sortAgents(specs);
+    const results = [];
+    for (const agent of agents) {
+      const runsThisCycle = agent.triggerPolicy?.maxRunsPerCycle ?? 1;
+      for (let index = 0; index < runsThisCycle; index += 1) {
+        const trigger = await this.resolveTrigger(agent, "auto");
+        if (!trigger) {
+          break;
+        }
+        results.push({
+          slug: agent.slug,
+          result: await this.executeAgent(agent, trigger)
+        });
+      }
+    }
+    return results;
+  }
+  async start(intervalMs = Number(process.env.TREESEED_AGENT_SUPERVISOR_INTERVAL_MS ?? 6e4)) {
+    await this.runCycle();
+    setInterval(() => {
+      void this.runCycle();
+    }, intervalMs);
+  }
+  async drainMessages() {
+    const { specs, diagnostics } = await loadActiveAgentSpecs(this.sdk);
+    const errors = diagnostics.filter((entry) => entry.severity === "error");
+    if (errors.length) {
+      throw new Error(
+        `Agent spec validation failed: ${errors.map((entry) => `${entry.slug}:${entry.field}:${entry.message}`).join(" | ")}`
+      );
+    }
+    const agents = this.sortAgents(specs);
+    const messageAgents = agents.filter(
+      (agent) => agent.triggers.some((trigger) => trigger.type === "message")
+    );
+    const results = [];
+    for (const agent of messageAgents) {
+      results.push({
+        slug: agent.slug,
+        result: await this.runAgent(agent.slug, "auto")
+      });
+    }
+    return results;
+  }
+  releaseLeases() {
+    return this.sdk.releaseAllLeases();
+  }
+  async replayMessage(id) {
+    await this.sdk.ackMessage({
+      id,
+      status: "pending"
+    });
+    return {
+      id,
+      status: "pending"
+    };
+  }
+}
+export {
+  AgentKernel
+};

package/dist/agents/kernel/trigger-resolver.js

@@ -0,0 +1,153 @@
+import crypto from "node:crypto";
+function buildManualInvocation(agent) {
+  const scheduleLike = agent.triggers.find((trigger) => trigger.type === "schedule" || trigger.type === "startup");
+  if (!scheduleLike) {
+    return null;
+  }
+  return {
+    kind: "manual",
+    source: "manual",
+    trigger: scheduleLike
+  };
+}
+function evaluateCooldown(agent, lastRunAt) {
+  const cooldownMs = agent.execution.cooldownSeconds * 1e3;
+  return (lastRunAt ?? 0) > 0 && Date.now() - (lastRunAt ?? 0) < cooldownMs;
+}
+async function resolveMessageTrigger(agent, sdk, trigger, messageBatchSize) {
+  for (let index = 0; index < messageBatchSize; index += 1) {
+    const claimed = await sdk.claimMessage({
+      workerId: `${agent.slug}-${crypto.randomUUID()}`,
+      messageTypes: trigger.messageTypes ?? [],
+      leaseSeconds: agent.execution.leaseSeconds
+    });
+    if (claimed.payload) {
+      return {
+        kind: "ready",
+        selectedTrigger: trigger,
+        invocation: {
+          kind: "message",
+          source: "message",
+          trigger,
+          message: claimed.payload
+        }
+      };
+    }
+  }
+  return {
+    kind: "no_message_available",
+    selectedTrigger: trigger,
+    reason: `No matching messages for ${agent.slug}.`
+  };
+}
+async function resolveFollowTrigger(agent, sdk, trigger) {
+  const models = trigger.models ?? [];
+  const since = (await sdk.getCursor({
+    agentSlug: agent.slug,
+    cursorKey: `follow:${models.join(",") || "all"}`
+  })).payload ?? trigger.sinceField ?? (/* @__PURE__ */ new Date(0)).toISOString();
+  for (const model of models) {
+    const followed = await sdk.follow({
+      model,
+      since: String(since)
+    });
+    if (followed.payload.items.length) {
+      return {
+        kind: "ready",
+        selectedTrigger: trigger,
+        invocation: {
+          kind: "follow",
+          source: "follow",
+          trigger,
+          followModels: models,
+          cursorValue: String(since)
+        }
+      };
+    }
+  }
+  return {
+    kind: "no_follow_activity",
+    selectedTrigger: trigger,
+    reason: `No followed activity for ${agent.slug}.`
+  };
+}
+function resolveScheduleLikeTrigger(agent, trigger, mode, lastRunAt) {
+  if (mode !== "manual" && evaluateCooldown(agent, lastRunAt)) {
+    return {
+      kind: "blocked_by_cooldown",
+      selectedTrigger: trigger,
+      reason: `Agent ${agent.slug} is cooling down.`
+    };
+  }
+  return {
+    kind: "ready",
+    selectedTrigger: trigger,
+    invocation: {
+      kind: mode === "manual" ? "manual" : trigger.type === "startup" || trigger.runOnStart ? "startup" : "schedule",
+      source: mode === "manual" ? "manual" : trigger.type === "startup" || trigger.runOnStart ? "startup" : "schedule",
+      trigger
+    }
+  };
+}
+async function resolveTriggerDecision(input) {
+  if (input.isRunning) {
+    return {
+      kind: "blocked_by_concurrency",
+      reason: `Agent ${input.agent.slug} is already running.`
+    };
+  }
+  const mode = input.mode ?? "auto";
+  const messageBatchSize = input.agent.triggerPolicy?.messageBatchSize ?? 1;
+  const triggerGroups = {
+    message: input.agent.triggers.filter((trigger) => trigger.type === "message"),
+    follow: input.agent.triggers.filter((trigger) => trigger.type === "follow"),
+    schedule: input.agent.triggers.filter((trigger) => trigger.type === "startup" || trigger.type === "schedule")
+  };
+  for (const trigger of triggerGroups.message) {
+    const decision = await resolveMessageTrigger(input.agent, input.sdk, trigger, messageBatchSize);
+    if (!decision) {
+      continue;
+    }
+    if (decision.kind === "ready") {
+      return decision;
+    }
+  }
+  for (const trigger of triggerGroups.follow) {
+    const decision = await resolveFollowTrigger(input.agent, input.sdk, trigger);
+    if (decision.kind === "ready") {
+      return decision;
+    }
+  }
+  for (const trigger of triggerGroups.schedule) {
+    const decision = resolveScheduleLikeTrigger(input.agent, trigger, mode, input.lastRunAt);
+    if (decision.kind === "ready") {
+      return decision;
+    }
+    if (decision.kind === "blocked_by_cooldown") {
+      return decision;
+    }
+  }
+  if (mode === "manual") {
+    const invocation = buildManualInvocation(input.agent);
+    return invocation ? { kind: "ready", invocation, selectedTrigger: invocation.trigger } : { kind: "no_trigger_available", reason: `No manual-capable trigger found for ${input.agent.slug}.` };
+  }
+  if (triggerGroups.message.length) {
+    return {
+      kind: "no_message_available",
+      reason: `No matching messages for ${input.agent.slug}.`
+    };
+  }
+  if (triggerGroups.follow.length) {
+    return {
+      kind: "no_follow_activity",
+      reason: `No followed activity for ${input.agent.slug}.`
+    };
+  }
+  return {
+    kind: "no_trigger_available",
+    reason: `No runnable triggers defined for ${input.agent.slug}.`
+  };
+}
+export {
+  resolveTriggerDecision
+};

package/dist/agents/model-registry.js

@@ -0,0 +1 @@
+export * from "@treeseed/sdk/models";

package/dist/agents/registry-helper.js

@@ -0,0 +1,14 @@
+function defineAgentHandlerRegistry(registry) {
+  return registry;
+}
+function resolveAgentHandlerFromRegistry(registry, kind) {
+  const handler = registry[kind];
+  if (!handler) {
+    throw new Error(`No runtime handler is registered for agent handler "${kind}".`);
+  }
+  return handler;
+}
+export {
+  defineAgentHandlerRegistry,
+  resolveAgentHandlerFromRegistry
+};