@treeseed/agent 0.8.5

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

@@ -0,0 +1,291 @@
+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 { followCursorKey, resolveTriggerDecision } from "./trigger-resolver.js";
+import { loadActiveAgentSpecs, loadAllAgentSpecs, summarizeAgentSpec } from "../spec-loader.js";
+import { getTreeseedAgentProviderSelections } from "@treeseed/sdk/platform/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)) {
+      await 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 = await 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()
+      });
+      if (trigger.kind === "follow") {
+        await this.sdk.upsertCursor({
+          agentSlug: agent.slug,
+          cursorKey: followCursorKey(trigger.followModels),
+          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", invocation) {
+    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 = invocation ?? 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.d.ts

@@ -0,0 +1,19 @@
+import type { AgentRuntimeSpec, AgentTriggerConfig } from '@treeseed/sdk/types/agents';
+import type { ScopedAgentSdk } from '@treeseed/sdk/sdk';
+import type { AgentTriggerInvocation } from '../runtime-types.ts';
+export type TriggerDecisionKind = 'ready' | 'skip' | 'blocked_by_cooldown' | 'blocked_by_concurrency' | 'no_message_available' | 'no_follow_activity' | 'no_trigger_available';
+export interface TriggerDecision {
+    kind: TriggerDecisionKind;
+    invocation?: AgentTriggerInvocation;
+    reason?: string;
+    selectedTrigger?: AgentTriggerConfig;
+}
+export interface TriggerResolverInput {
+    agent: AgentRuntimeSpec;
+    mode?: 'auto' | 'manual';
+    isRunning: boolean;
+    lastRunAt?: number;
+    sdk: ScopedAgentSdk;
+}
+export declare function followCursorKey(models: string[] | undefined): string;
+export declare function resolveTriggerDecision(input: TriggerResolverInput): Promise<TriggerDecision>;

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

@@ -0,0 +1,157 @@
+import crypto from "node:crypto";
+function followCursorKey(models) {
+  return `follow:${(models ?? []).join(",") || "all"}`;
+}
+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: followCursorKey(models)
+  })).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 {
+  followCursorKey,
+  resolveTriggerDecision
+};

package/dist/agents/registry-helper.d.ts

@@ -0,0 +1,4 @@
+import type { AgentHandlerKind } from '@treeseed/sdk/types/agents';
+import type { AgentHandler } from './runtime-types.ts';
+export declare function defineAgentHandlerRegistry(registry: Partial<Record<AgentHandlerKind, AgentHandler>>): Partial<Record<string, AgentHandler<unknown, unknown>>>;
+export declare function resolveAgentHandlerFromRegistry(registry: Partial<Record<AgentHandlerKind, AgentHandler>>, kind: AgentHandlerKind): AgentHandler<unknown, unknown>;

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
+};

package/dist/agents/registry.d.ts

@@ -0,0 +1,6 @@
+import type { AgentHandlerKind } from '@treeseed/sdk/types/agents';
+import type { AgentHandler } from './runtime-types.ts';
+export declare function getTenantAgentHandlerModulePaths(kind: AgentHandlerKind, tenantRoot?: string): string[];
+export declare function loadTenantAgentHandlerRegistry(tenantRoot?: string): Promise<Record<string, AgentHandler>>;
+export declare function listRegisteredAgentHandlers(): Promise<string[]>;
+export declare function resolveAgentHandler(kind: AgentHandlerKind): Promise<AgentHandler<unknown, unknown>>;

package/dist/agents/registry.js

@@ -0,0 +1,98 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getTreeseedAgentProviderSelections } from "@treeseed/sdk/platform/deploy-runtime";
+import { resolveTreeseedTenantRoot } from "@treeseed/sdk/platform/tenant-config";
+import { resolveAgentRuntimeProviders } from "../agent-runtime.js";
+const BUILTIN_HANDLER_KINDS = [
+  "planner",
+  "architect",
+  "engineer",
+  "notifier",
+  "researcher",
+  "reviewer",
+  "releaser"
+];
+const HANDLER_EXPORT_NAMES = {
+  planner: "plannerHandler",
+  architect: "architectHandler",
+  engineer: "engineerHandler",
+  notifier: "notifierHandler",
+  researcher: "researcherHandler",
+  reviewer: "reviewerHandler",
+  releaser: "releaserHandler"
+};
+function getTenantAgentHandlerModulePaths(kind, tenantRoot = resolveTreeseedTenantRoot()) {
+  return [
+    resolve(tenantRoot, "src/agents", `${kind}.js`),
+    resolve(tenantRoot, "src/agents", `${kind}.ts`)
+  ];
+}
+async function loadTenantAgentHandlerRegistry(tenantRoot = resolveTreeseedTenantRoot()) {
+  const registry = {};
+  for (const kind of BUILTIN_HANDLER_KINDS) {
+    const modulePath = getTenantAgentHandlerModulePaths(kind, tenantRoot).find((candidate) => existsSync(candidate));
+    if (!modulePath) {
+      continue;
+    }
+    let moduleExports;
+    try {
+      moduleExports = await import(
+        /* @vite-ignore */
+        pathToFileURL(modulePath).href
+      );
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(`Failed to import tenant agent handler "${kind}" from ${modulePath}: ${reason}`);
+    }
+    const exportName = HANDLER_EXPORT_NAMES[kind];
+    const handler = moduleExports[exportName];
+    if (!handler) {
+      throw new Error(
+        `Tenant agent handler module "${modulePath}" must export "${exportName}" for handler kind "${kind}".`
+      );
+    }
+    const normalizedHandler = handler;
+    if (normalizedHandler.kind !== kind) {
+      throw new Error(
+        `Tenant agent handler "${exportName}" from "${modulePath}" declares kind "${normalizedHandler.kind}", but "${kind}" was expected.`
+      );
+    }
+    registry[kind] = normalizedHandler;
+  }
+  return registry;
+}
+let agentHandlerRegistryPromise = null;
+async function getAgentHandlerRegistry() {
+  if (!agentHandlerRegistryPromise) {
+    agentHandlerRegistryPromise = loadTenantAgentHandlerRegistry();
+  }
+  return agentHandlerRegistryPromise;
+}
+async function listRegisteredAgentHandlers() {
+  const registry = await getAgentHandlerRegistry();
+  const runtimeProviders = resolveAgentRuntimeProviders(resolveTreeseedTenantRoot(), getTreeseedAgentProviderSelections());
+  return [.../* @__PURE__ */ new Set([...Object.keys(registry), ...runtimeProviders.handlers.keys()])];
+}
+async function resolveAgentHandler(kind) {
+  const registry = await getAgentHandlerRegistry();
+  const runtimeProviders = resolveAgentRuntimeProviders(resolveTreeseedTenantRoot(), getTreeseedAgentProviderSelections());
+  const handler = registry[kind] ?? runtimeProviders.handlers.get(kind);
+  if (!handler) {
+    if (BUILTIN_HANDLER_KINDS.includes(kind)) {
+      const expectedPath = getTenantAgentHandlerModulePaths(kind).join('" or "');
+      const expectedExport = HANDLER_EXPORT_NAMES[kind];
+      throw new Error(
+        `No runtime handler is registered for agent handler "${kind}". Expected tenant file "${expectedPath}" exporting "${expectedExport}" or a plugin contribution.`
+      );
+    }
+    throw new Error(`No runtime handler is registered for agent handler "${kind}".`);
+  }
+  return handler;
+}
+export {
+  getTenantAgentHandlerModulePaths,
+  listRegisteredAgentHandlers,
+  loadTenantAgentHandlerRegistry,
+  resolveAgentHandler
+};