@treeseed/agent 0.8.5

package/dist/agents/runtime-types.d.ts

@@ -0,0 +1,118 @@
+import type { AgentHandlerKind, AgentRuntimeSpec, AgentRunStatus, AgentTriggerConfig } from '@treeseed/sdk/types/agents';
+import type { AgentErrorCategory } from './contracts/run.ts';
+import type { ScopedAgentSdk } from '@treeseed/sdk/sdk';
+import type { SdkMessageEntity } from '@treeseed/sdk/types';
+export interface AgentTriggerInvocation {
+    kind: 'startup' | 'schedule' | 'message' | 'manual' | 'follow';
+    source: string;
+    trigger: AgentTriggerConfig;
+    message?: SdkMessageEntity | null;
+    followModels?: string[];
+    cursorValue?: string | null;
+}
+export interface AgentExecutionResult {
+    status: AgentRunStatus;
+    summary: string;
+    stdout?: string;
+    stderr?: string;
+    errorCategory?: AgentErrorCategory | null;
+    metadata?: Record<string, unknown>;
+}
+export interface AgentMutationResult {
+    branchName: string | null;
+    commitMessage: string | null;
+    worktreePath: string | null;
+    commitSha: string | null;
+    changedPaths: string[];
+}
+export interface AgentRepositoryInspectionResult {
+    branchName: string | null;
+    changedPaths: string[];
+    commitSha: string | null;
+    summary: string;
+}
+export interface AgentVerificationResult {
+    status: 'completed' | 'failed' | 'waiting';
+    summary: string;
+    stdout?: string;
+    stderr?: string;
+    errorCategory?: AgentErrorCategory | null;
+}
+export interface AgentNotificationResult {
+    status: 'completed' | 'failed' | 'waiting';
+    summary: string;
+    deliveredCount: number;
+}
+export interface AgentResearchResult {
+    status: 'completed' | 'failed' | 'waiting';
+    summary: string;
+    markdown: string;
+    sources?: string[];
+    errorCategory?: AgentErrorCategory | null;
+}
+export interface AgentExecutionAdapter {
+    runTask(input: {
+        agent: AgentRuntimeSpec;
+        runId: string;
+        prompt: string;
+    }): Promise<AgentExecutionResult>;
+}
+export interface AgentMutationAdapter {
+    writeArtifact(input: {
+        runId: string;
+        agent: AgentRuntimeSpec;
+        relativePath: string;
+        content: string;
+        commitMessage: string;
+    }): Promise<AgentMutationResult>;
+}
+export interface AgentRepositoryInspectionAdapter {
+    inspectBranch(input: {
+        repoRoot: string;
+        branchName: string | null;
+    }): Promise<AgentRepositoryInspectionResult>;
+}
+export interface AgentVerificationAdapter {
+    runChecks(input: {
+        agent: AgentRuntimeSpec;
+        runId: string;
+        commands: string[];
+    }): Promise<AgentVerificationResult>;
+}
+export interface AgentNotificationAdapter {
+    deliver(input: {
+        agent: AgentRuntimeSpec;
+        runId: string;
+        recipients: string[];
+        subject: string;
+        body: string;
+    }): Promise<AgentNotificationResult>;
+}
+export interface AgentResearchAdapter {
+    research(input: {
+        agent: AgentRuntimeSpec;
+        runId: string;
+        questionId: string;
+        reason: string | null;
+    }): Promise<AgentResearchResult>;
+}
+export interface AgentContext {
+    runId: string;
+    repoRoot: string;
+    agent: AgentRuntimeSpec;
+    sdk: ScopedAgentSdk;
+    trigger: AgentTriggerInvocation;
+    execution: AgentExecutionAdapter;
+    mutations: AgentMutationAdapter;
+    repository: AgentRepositoryInspectionAdapter;
+    verification: AgentVerificationAdapter;
+    notifications: AgentNotificationAdapter;
+    research: AgentResearchAdapter;
+}
+export interface AgentHandler<TInputs = unknown, TResult = unknown> {
+    kind: AgentHandlerKind;
+    resolveInputs(context: AgentContext): Promise<TInputs>;
+    execute(context: AgentContext, inputs: TInputs): Promise<TResult>;
+    emitOutputs(context: AgentContext, result: TResult): Promise<AgentExecutionResult>;
+}
+export {};

package/dist/agents/spec-loader.d.ts

@@ -0,0 +1,18 @@
+import type { AgentRuntimeSpec } from '@treeseed/sdk/types/agents';
+import { AgentSdk } from '@treeseed/sdk/sdk';
+import type { AgentSpecDiagnostic, NormalizedAgentRuntimeSpec } from './spec-types.ts';
+export interface AgentSpecLoadResult {
+    specs: NormalizedAgentRuntimeSpec[];
+    diagnostics: AgentSpecDiagnostic[];
+}
+export declare function loadAgentSpecs(sdk: AgentSdk, options?: {
+    enabled?: boolean;
+}): Promise<AgentSpecLoadResult>;
+export declare function loadActiveAgentSpecs(sdk: AgentSdk): Promise<AgentSpecLoadResult>;
+export declare function loadAllAgentSpecs(sdk: AgentSdk): Promise<AgentSpecLoadResult>;
+export declare function summarizeAgentSpec(agent: AgentRuntimeSpec): {
+    slug: string;
+    handler: string;
+    enabled: boolean;
+    triggers: ("message" | "follow" | "schedule" | "startup")[];
+};

package/dist/agents/spec-loader.js

@@ -0,0 +1,54 @@
+import { AGENT_MESSAGE_TYPES } from "./contracts/messages.js";
+import { listRegisteredAgentHandlers } from "./registry.js";
+import { normalizeAgentRuntimeSpec } from "./spec-normalizer.js";
+function extractRawSpec(entry) {
+  const frontmatter = entry.frontmatter && typeof entry.frontmatter === "object" ? entry.frontmatter : {};
+  return {
+    ...frontmatter,
+    body: entry.body,
+    id: entry.id
+  };
+}
+async function loadAgentSpecs(sdk, options) {
+  const entries = typeof sdk.listRawAgentSpecs === "function" ? await sdk.listRawAgentSpecs(options) : (await sdk.listAgentSpecs(options)).map(
+    (spec) => ({
+      id: spec.slug,
+      body: "",
+      frontmatter: spec
+    })
+  );
+  const diagnostics = [];
+  const specs = [];
+  for (const entry of entries) {
+    const registeredHandlers = await listRegisteredAgentHandlers();
+    const result = normalizeAgentRuntimeSpec(extractRawSpec(entry), {
+      registeredHandlers,
+      messageTypes: [...AGENT_MESSAGE_TYPES]
+    });
+    diagnostics.push(...result.diagnostics);
+    if (result.spec) {
+      specs.push(result.spec);
+    }
+  }
+  return { specs, diagnostics };
+}
+async function loadActiveAgentSpecs(sdk) {
+  return loadAgentSpecs(sdk, { enabled: true });
+}
+async function loadAllAgentSpecs(sdk) {
+  return loadAgentSpecs(sdk);
+}
+function summarizeAgentSpec(agent) {
+  return {
+    slug: agent.slug,
+    handler: agent.handler,
+    enabled: agent.enabled,
+    triggers: agent.triggers.map((trigger) => trigger.type)
+  };
+}
+export {
+  loadActiveAgentSpecs,
+  loadAgentSpecs,
+  loadAllAgentSpecs,
+  summarizeAgentSpec
+};

package/dist/agents/spec-normalizer.d.ts

@@ -0,0 +1,2 @@
+import type { AgentSpecNormalizationResult, AgentSpecValidationContext, RawAgentRuntimeSpec } from './spec-types.ts';
+export declare function normalizeAgentRuntimeSpec(raw: RawAgentRuntimeSpec, context: AgentSpecValidationContext): AgentSpecNormalizationResult;

package/dist/agents/spec-normalizer.js

@@ -0,0 +1,327 @@
+import {
+  AGENT_CLI_ALLOW_TOOLS
+} from "@treeseed/sdk/types/agents";
+import { AGENT_MESSAGE_TYPES } from "./contracts/messages.js";
+import { normalizeAgentCliOptions } from "./cli-tools.js";
+const TRIGGER_KINDS = ["schedule", "message", "follow", "startup"];
+const PERMISSION_OPERATIONS = ["get", "search", "follow", "pick", "create", "update"];
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function ensureString(value, field, diagnostics, slug) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field,
+      message: `Expected ${field} to be a non-empty string.`
+    });
+    return "";
+  }
+  return value;
+}
+function ensureBoolean(value, field, diagnostics, slug, fallback = false) {
+  if (value === void 0) {
+    return fallback;
+  }
+  if (typeof value !== "boolean") {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field,
+      message: `Expected ${field} to be a boolean.`
+    });
+    return fallback;
+  }
+  return value;
+}
+function ensurePositiveNumber(value, field, diagnostics, slug, fallback, allowZero = false) {
+  if (value === void 0) {
+    return fallback;
+  }
+  if (typeof value !== "number" || Number.isNaN(value) || !allowZero && value <= 0 || allowZero && value < 0) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field,
+      message: `Expected ${field} to be ${allowZero ? "a non-negative" : "a positive"} number.`
+    });
+    return fallback;
+  }
+  return value;
+}
+function normalizeTrigger(value, index, diagnostics, slug) {
+  if (!isPlainObject(value)) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: `triggers[${index}]`,
+      message: "Expected trigger to be an object."
+    });
+    return null;
+  }
+  const type = ensureString(value.type, `triggers[${index}].type`, diagnostics, slug);
+  if (!TRIGGER_KINDS.includes(type)) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: `triggers[${index}].type`,
+      message: `Unsupported trigger type "${String(value.type ?? "")}".`
+    });
+    return null;
+  }
+  return {
+    type,
+    cron: typeof value.cron === "string" ? value.cron : void 0,
+    messageTypes: Array.isArray(value.messageTypes) ? value.messageTypes.filter((entry) => typeof entry === "string") : [],
+    models: Array.isArray(value.models) ? value.models.filter((entry) => typeof entry === "string") : [],
+    sinceField: typeof value.sinceField === "string" ? value.sinceField : void 0,
+    runOnStart: typeof value.runOnStart === "boolean" ? value.runOnStart : false
+  };
+}
+function normalizePermissions(value, diagnostics, slug) {
+  if (!Array.isArray(value)) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: "permissions",
+      message: "Expected permissions to be an array."
+    });
+    return [];
+  }
+  return value.flatMap((entry, index) => {
+    if (!isPlainObject(entry)) {
+      diagnostics.push({
+        severity: "error",
+        slug,
+        field: `permissions[${index}]`,
+        message: "Expected permission entry to be an object."
+      });
+      return [];
+    }
+    const model = ensureString(entry.model, `permissions[${index}].model`, diagnostics, slug);
+    const operations = Array.isArray(entry.operations) ? entry.operations.filter(
+      (operation) => typeof operation === "string" && PERMISSION_OPERATIONS.includes(operation)
+    ) : [];
+    if (!operations.length) {
+      diagnostics.push({
+        severity: "error",
+        slug,
+        field: `permissions[${index}].operations`,
+        message: "Expected at least one valid permission operation."
+      });
+    }
+    return model ? [{ model, operations }] : [];
+  });
+}
+function normalizeExecution(value, diagnostics, slug) {
+  const next = isPlainObject(value) ? value : {};
+  return {
+    maxConcurrency: ensurePositiveNumber(next.maxConcurrency, "execution.maxConcurrency", diagnostics, slug, 1),
+    timeoutSeconds: ensurePositiveNumber(next.timeoutSeconds, "execution.timeoutSeconds", diagnostics, slug, 900),
+    cooldownSeconds: ensurePositiveNumber(next.cooldownSeconds, "execution.cooldownSeconds", diagnostics, slug, 30, true),
+    leaseSeconds: ensurePositiveNumber(next.leaseSeconds, "execution.leaseSeconds", diagnostics, slug, 300),
+    retryLimit: ensurePositiveNumber(next.retryLimit, "execution.retryLimit", diagnostics, slug, 3, true),
+    branchPrefix: ensureString(next.branchPrefix ?? "agent", "execution.branchPrefix", diagnostics, slug) || "agent",
+    providerProfile: normalizeProviderProfile(next.providerProfile, diagnostics, slug)
+  };
+}
+function normalizeWeightedLaneList(value, field, diagnostics, slug) {
+  if (value === void 0) return [];
+  if (!Array.isArray(value)) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field,
+      message: `Expected ${field} to be an array.`
+    });
+    return [];
+  }
+  return value.flatMap((entry, index) => {
+    if (!isPlainObject(entry)) {
+      diagnostics.push({
+        severity: "error",
+        slug,
+        field: `${field}[${index}]`,
+        message: "Expected provider lane entry to be an object."
+      });
+      return [];
+    }
+    return [{
+      providerId: typeof entry.providerId === "string" ? entry.providerId : void 0,
+      provider: typeof entry.provider === "string" ? entry.provider : void 0,
+      laneId: typeof entry.laneId === "string" ? entry.laneId : void 0,
+      model: typeof entry.model === "string" ? entry.model : void 0,
+      modelClass: typeof entry.modelClass === "string" ? entry.modelClass : void 0,
+      weight: ensurePositiveNumber(entry.weight, `${field}[${index}].weight`, diagnostics, slug, 1, true),
+      reason: typeof entry.reason === "string" ? entry.reason : void 0,
+      maxQualityPenalty: typeof entry.maxQualityPenalty === "number" ? entry.maxQualityPenalty : void 0
+    }];
+  });
+}
+function normalizeProviderProfile(value, diagnostics, slug) {
+  if (value === void 0) return void 0;
+  if (!isPlainObject(value)) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: "execution.providerProfile",
+      message: "Expected execution.providerProfile to be an object."
+    });
+    return void 0;
+  }
+  const fallbackPolicy = typeof value.fallbackPolicy === "string" ? value.fallbackPolicy : "allow_substitution";
+  if (!["allow_substitution", "require_same_model_class", "fail_if_unavailable", "ask_for_approval"].includes(fallbackPolicy)) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: "execution.providerProfile.fallbackPolicy",
+      message: `Unsupported fallback policy "${String(value.fallbackPolicy)}".`
+    });
+  }
+  return {
+    requiredCapabilities: Array.isArray(value.requiredCapabilities) ? value.requiredCapabilities.filter((entry) => typeof entry === "string" && entry.trim().length > 0) : [],
+    preferredLanes: normalizeWeightedLaneList(value.preferredLanes, "execution.providerProfile.preferredLanes", diagnostics, slug),
+    acceptableFallbacks: normalizeWeightedLaneList(value.acceptableFallbacks, "execution.providerProfile.acceptableFallbacks", diagnostics, slug).map((entry) => ({
+      providerId: entry.providerId,
+      provider: entry.provider,
+      laneId: entry.laneId,
+      model: entry.model,
+      modelClass: entry.modelClass,
+      maxQualityPenalty: entry.maxQualityPenalty
+    })),
+    disallowedProviders: Array.isArray(value.disallowedProviders) ? value.disallowedProviders.filter((entry) => typeof entry === "string") : void 0,
+    disallowedRegions: Array.isArray(value.disallowedRegions) ? value.disallowedRegions.filter((entry) => typeof entry === "string") : void 0,
+    fallbackPolicy
+  };
+}
+function normalizeOutputs(value, _diagnostics, _slug) {
+  const next = isPlainObject(value) ? value : {};
+  return {
+    messageTypes: Array.isArray(next.messageTypes) ? next.messageTypes.filter((entry) => typeof entry === "string") : [],
+    modelMutations: Array.isArray(next.modelMutations) ? next.modelMutations.filter((entry) => typeof entry === "string") : []
+  };
+}
+function normalizeParts(raw, slugHint, diagnostics) {
+  const slug = ensureString(raw.slug ?? slugHint, "slug", diagnostics, slugHint) || slugHint;
+  const handler = ensureString(raw.handler, "handler", diagnostics, slug);
+  const triggers = Array.isArray(raw.triggers) ? raw.triggers.map((entry, index) => normalizeTrigger(entry, index, diagnostics, slug)).filter((entry) => Boolean(entry)) : [];
+  if (!triggers.length) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: "triggers",
+      message: "Expected at least one trigger."
+    });
+  }
+  try {
+    const cli = normalizeAgentCliOptions(raw.cli);
+    const spec = {
+      slug,
+      handler,
+      enabled: ensureBoolean(raw.enabled, "enabled", diagnostics, slug, true),
+      systemPrompt: ensureString(raw.systemPrompt, "systemPrompt", diagnostics, slug),
+      persona: ensureString(raw.persona, "persona", diagnostics, slug),
+      cli,
+      triggers,
+      triggerPolicy: isPlainObject(raw.triggerPolicy) ? {
+        maxRunsPerCycle: typeof raw.triggerPolicy.maxRunsPerCycle === "number" ? raw.triggerPolicy.maxRunsPerCycle : void 0,
+        messageBatchSize: typeof raw.triggerPolicy.messageBatchSize === "number" ? raw.triggerPolicy.messageBatchSize : void 0
+      } : void 0,
+      permissions: normalizePermissions(raw.permissions, diagnostics, slug),
+      execution: normalizeExecution(raw.execution, diagnostics, slug),
+      outputs: normalizeOutputs(raw.outputs, diagnostics, slug)
+    };
+    return spec;
+  } catch (error) {
+    diagnostics.push({
+      severity: "error",
+      slug,
+      field: "cli",
+      message: error instanceof Error ? error.message : String(error)
+    });
+    return null;
+  }
+}
+function normalizeAgentRuntimeSpec(raw, context) {
+  const slugHint = typeof raw.slug === "string" && raw.slug ? raw.slug : "unknown-agent";
+  const diagnostics = [];
+  const parts = normalizeParts(raw, slugHint, diagnostics);
+  if (!parts) {
+    return { spec: null, diagnostics };
+  }
+  const spec = {
+    ...parts,
+    name: typeof raw.name === "string" ? raw.name : void 0,
+    description: typeof raw.description === "string" ? raw.description : void 0,
+    summary: typeof raw.summary === "string" ? raw.summary : void 0,
+    operator: typeof raw.operator === "string" ? raw.operator : void 0,
+    runtimeStatus: typeof raw.runtimeStatus === "string" ? raw.runtimeStatus : void 0,
+    capabilities: Array.isArray(raw.capabilities) ? raw.capabilities.filter((entry) => typeof entry === "string") : [],
+    tags: Array.isArray(raw.tags) ? raw.tags.filter((entry) => typeof entry === "string") : []
+  };
+  if (!context.registeredHandlers.includes(spec.handler)) {
+    diagnostics.push({
+      severity: "error",
+      slug: spec.slug,
+      field: "handler",
+      message: `No runtime handler is registered for "${spec.handler}".`
+    });
+  }
+  for (const trigger of spec.triggers) {
+    if (trigger.type === "message") {
+      const messagePermission = spec.permissions.find((permission) => permission.model === "message");
+      if (!messagePermission || !messagePermission.operations.includes("pick") || !messagePermission.operations.includes("update")) {
+        diagnostics.push({
+          severity: "error",
+          slug: spec.slug,
+          field: "permissions",
+          message: "Message-triggered agents must allow message pick and update operations."
+        });
+      }
+      for (const messageType of trigger.messageTypes ?? []) {
+        if (!context.messageTypes.includes(messageType) || !AGENT_MESSAGE_TYPES.includes(messageType)) {
+          diagnostics.push({
+            severity: "error",
+            slug: spec.slug,
+            field: "triggers.messageTypes",
+            message: `Unknown message trigger type "${messageType}".`
+          });
+        }
+      }
+    }
+    if (trigger.type === "follow" && !trigger.models?.length) {
+      diagnostics.push({
+        severity: "error",
+        slug: spec.slug,
+        field: "triggers.models",
+        message: "Follow triggers must declare at least one model."
+      });
+    }
+  }
+  for (const messageType of spec.outputs.messageTypes) {
+    if (!context.messageTypes.includes(messageType) || !AGENT_MESSAGE_TYPES.includes(messageType)) {
+      diagnostics.push({
+        severity: "error",
+        slug: spec.slug,
+        field: "outputs.messageTypes",
+        message: `Unknown emitted message type "${messageType}".`
+      });
+    }
+  }
+  if (spec.cli.allowTools?.some((tool) => !AGENT_CLI_ALLOW_TOOLS.includes(tool))) {
+    diagnostics.push({
+      severity: "error",
+      slug: spec.slug,
+      field: "cli.allowTools",
+      message: "Agent declared an unsupported tool allowance."
+    });
+  }
+  return {
+    spec: diagnostics.some((entry) => entry.severity === "error") ? null : spec,
+    diagnostics
+  };
+}
+export {
+  normalizeAgentRuntimeSpec
+};

package/dist/agents/spec-types.d.ts

@@ -0,0 +1,64 @@
+import type { AgentCliOptions, AgentExecutionConfig, AgentHandlerKind, AgentOutputContract, AgentPermissionConfig, AgentTriggerConfig } from '@treeseed/sdk/types/agents';
+export type AgentSpecDiagnosticSeverity = 'error' | 'warning';
+export interface AgentSpecDiagnostic {
+    severity: AgentSpecDiagnosticSeverity;
+    slug: string;
+    field: string;
+    message: string;
+}
+export interface AgentSpecValidationContext {
+    registeredHandlers: readonly AgentHandlerKind[];
+    messageTypes: readonly string[];
+}
+export interface RawAgentRuntimeSpec {
+    id?: unknown;
+    body?: unknown;
+    slug?: unknown;
+    handler?: unknown;
+    enabled?: unknown;
+    systemPrompt?: unknown;
+    persona?: unknown;
+    cli?: unknown;
+    triggers?: unknown;
+    triggerPolicy?: unknown;
+    permissions?: unknown;
+    execution?: unknown;
+    outputs?: unknown;
+    name?: unknown;
+    description?: unknown;
+    summary?: unknown;
+    operator?: unknown;
+    runtimeStatus?: unknown;
+    capabilities?: unknown;
+    tags?: unknown;
+}
+export interface AgentSpecNormalizationResult {
+    spec: NormalizedAgentRuntimeSpec | null;
+    diagnostics: AgentSpecDiagnostic[];
+}
+export interface NormalizedTriggerPolicy {
+    maxRunsPerCycle?: number;
+    messageBatchSize?: number;
+}
+export interface AgentSpecParts {
+    slug: string;
+    handler: AgentHandlerKind;
+    enabled: boolean;
+    systemPrompt: string;
+    persona: string;
+    cli: AgentCliOptions;
+    triggers: AgentTriggerConfig[];
+    triggerPolicy?: NormalizedTriggerPolicy;
+    permissions: AgentPermissionConfig[];
+    execution: AgentExecutionConfig;
+    outputs: AgentOutputContract;
+}
+export type NormalizedAgentRuntimeSpec = AgentSpecParts & {
+    name?: string;
+    description?: string;
+    summary?: string;
+    operator?: string;
+    runtimeStatus?: string;
+    capabilities?: string[];
+    tags?: string[];
+};

package/dist/agents/testing/agents-smoke.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/testing/agents-smoke.js

@@ -0,0 +1,32 @@
+import { createExecutionAdapter } from "../adapters/execution.js";
+import { createAgentTestRuntime } from "./e2e-harness.js";
+async function main() {
+  const target = process.argv[2] ?? "mvp";
+  const execution = createExecutionAdapter();
+  const runtime = await createAgentTestRuntime({
+    execution,
+    executionMode: "copilot",
+    databaseMode: process.env.TREESEED_AGENT_DATABASE_MODE === "local-d1" ? "local-d1" : "memory"
+  });
+  try {
+    await runtime.seedObjectives([{ slug: "smoke-objective" }]);
+    await runtime.seedQuestions([
+      {
+        slug: "smoke-question",
+        relatedObjectives: ["smoke-objective"]
+      }
+    ]);
+    const result = target === "mvp" ? await runtime.runCycle() : await runtime.runAgent(target);
+    const runs = await runtime.readRunLogs();
+    const messages = await runtime.readMessages();
+    console.log(JSON.stringify({
+      target,
+      result,
+      runs,
+      messages
+    }, null, 2));
+  } finally {
+    await runtime.cleanup();
+  }
+}
+void main();

package/dist/agents/testing/e2e-harness.d.ts

@@ -0,0 +1,44 @@
+import type { AgentSdk } from '@treeseed/sdk/sdk';
+import { type SdkCreateMessageRequest, type SdkMessageEntity, type SdkRunEntity } from '@treeseed/sdk/types';
+import type { AgentExecutionAdapter, AgentMutationAdapter } from '../runtime-types.ts';
+import type { AgentKernel } from '../kernel/agent-kernel.ts';
+export interface AgentTestRuntime {
+    rootDir: string;
+    repoRoot: string;
+    persistTo: string;
+    sdk: AgentSdk;
+    kernel: AgentKernel;
+    seedObjectives(entries: Array<{
+        slug: string;
+        date?: string;
+    }>): Promise<void>;
+    seedQuestions(entries: Array<{
+        slug: string;
+        date?: string;
+        relatedObjectives?: string[];
+    }>): Promise<void>;
+    seedKnowledge(entries: Array<{
+        slug: string;
+        title?: string;
+    }>): Promise<void>;
+    seedMessages(entries: Array<Omit<SdkCreateMessageRequest, 'actor'>>): Promise<SdkMessageEntity[]>;
+    clearModelContent(model: 'objective' | 'question' | 'knowledge'): Promise<void>;
+    runAgent(slug: string): Promise<unknown>;
+    runCycle(): Promise<unknown>;
+    readMessages(): Promise<SdkMessageEntity[]>;
+    readRunLogs(): Promise<SdkRunEntity[]>;
+    readContentLeases(): Promise<Record<string, unknown>[]>;
+    readSandboxArtifacts(): Promise<Array<{
+        path: string;
+        content: string;
+    }>>;
+    claimMessage(messageTypes: string[], workerId?: string): Promise<SdkMessageEntity | null>;
+    claimObjectiveLease(itemKey: string, workerId?: string): Promise<string | null>;
+    cleanup(): Promise<void>;
+}
+export declare function createAgentTestRuntime(options?: {
+    execution?: AgentExecutionAdapter;
+    mutations?: AgentMutationAdapter;
+    executionMode?: 'stub' | 'copilot';
+    databaseMode?: 'memory' | 'local-d1';
+}): Promise<AgentTestRuntime>;