@treeseed/agent 0.8.5

package/dist/agents/adapters/research.d.ts

@@ -0,0 +1,26 @@
+import type { AgentResearchAdapter } from '../runtime-types.ts';
+export declare class StubResearchAdapter implements AgentResearchAdapter {
+    research(input: {
+        questionId: string;
+        reason: string | null;
+        runId: string;
+    }): Promise<{
+        status: "completed";
+        summary: string;
+        markdown: string;
+        sources: never[];
+    }>;
+}
+export declare class ProjectGraphResearchAdapter implements AgentResearchAdapter {
+    research(input: {
+        questionId: string;
+        reason: string | null;
+        runId: string;
+    }): Promise<{
+        status: "completed";
+        summary: string;
+        markdown: string;
+        sources: any;
+    }>;
+}
+export declare function createResearchAdapter(): StubResearchAdapter | ProjectGraphResearchAdapter;

package/dist/agents/adapters/research.js

@@ -0,0 +1,59 @@
+import { AgentSdk } from "@treeseed/sdk";
+import { resolveTreeseedTenantRoot } from "@treeseed/sdk/platform/tenant-config";
+import { getTreeseedAgentProviderSelections } from "@treeseed/sdk/platform/deploy-runtime";
+class StubResearchAdapter {
+  async research(input) {
+    return {
+      status: "completed",
+      summary: `Research prepared for ${input.questionId}.`,
+      markdown: [
+        "# Research Summary",
+        "",
+        `Question: ${input.questionId}`,
+        `Reason: ${input.reason ?? "not provided"}`,
+        `Run: ${input.runId}`,
+        "",
+        "This is a stub research summary produced by the runtime adapter."
+      ].join("\n"),
+      sources: []
+    };
+  }
+}
+class ProjectGraphResearchAdapter {
+  async research(input) {
+    const repoRoot = resolveTreeseedTenantRoot();
+    const sdk = AgentSdk.createLocal({ repoRoot });
+    const graphResult = await sdk.queryGraph({
+      query: input.questionId,
+      options: {
+        limit: 5
+      }
+    }).catch(() => null);
+    const items = Array.isArray(graphResult?.items) ? graphResult.items : [];
+    return {
+      status: "completed",
+      summary: `Graph-backed research prepared for ${input.questionId}.`,
+      markdown: [
+        "# Research Summary",
+        "",
+        `Question: ${input.questionId}`,
+        `Reason: ${input.reason ?? "not provided"}`,
+        `Run: ${input.runId}`,
+        "",
+        items.length ? "Relevant graph context:" : "No ranked graph context was available. The question is still recorded for follow-up.",
+        ...items.map((item) => `- ${String(item.title ?? item.id ?? "context")}`)
+      ].join("\n"),
+      sources: items.map((item) => String(item.id ?? item.title ?? "")).filter(Boolean)
+    };
+  }
+}
+function createResearchAdapter() {
+  return String(
+    process.env.TREESEED_AGENT_RESEARCH_PROVIDER ?? getTreeseedAgentProviderSelections().research
+  ).toLowerCase() === "project_graph" ? new ProjectGraphResearchAdapter() : new StubResearchAdapter();
+}
+export {
+  ProjectGraphResearchAdapter,
+  StubResearchAdapter,
+  createResearchAdapter
+};

package/dist/agents/adapters/verification.d.ts

@@ -0,0 +1,36 @@
+import type { AgentVerificationAdapter } from '../runtime-types.ts';
+export declare class StubVerificationAdapter implements AgentVerificationAdapter {
+    runChecks(input: {
+        commands: string[];
+        runId: string;
+    }): Promise<{
+        status: "completed";
+        summary: string;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare class LocalVerificationAdapter implements AgentVerificationAdapter {
+    runChecks(input: {
+        commands: string[];
+    }): Promise<{
+        status: "waiting";
+        summary: string;
+        stdout: string;
+        stderr: string;
+        errorCategory?: undefined;
+    } | {
+        status: "failed";
+        summary: string;
+        stdout: string;
+        stderr: string;
+        errorCategory: "execution_error";
+    } | {
+        status: "completed";
+        summary: string;
+        stdout: string;
+        stderr: string;
+        errorCategory?: undefined;
+    }>;
+}
+export declare function createVerificationAdapter(): StubVerificationAdapter | LocalVerificationAdapter;

package/dist/agents/adapters/verification.js

@@ -0,0 +1,62 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getTreeseedAgentProviderSelections } from "@treeseed/sdk/platform/deploy-runtime";
+const execFileAsync = promisify(execFile);
+class StubVerificationAdapter {
+  async runChecks(input) {
+    return {
+      status: "completed",
+      summary: input.commands.length ? `Stub verification completed for ${input.runId}.` : "No verification commands configured.",
+      stdout: input.commands.join("\n"),
+      stderr: ""
+    };
+  }
+}
+class LocalVerificationAdapter {
+  async runChecks(input) {
+    if (!input.commands.length) {
+      return {
+        status: "waiting",
+        summary: "No verification commands configured.",
+        stdout: "",
+        stderr: ""
+      };
+    }
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    for (const command of input.commands) {
+      try {
+        const { stdout, stderr } = await execFileAsync("/bin/bash", ["-lc", command], {
+          env: process.env,
+          maxBuffer: 10 * 1024 * 1024
+        });
+        stdoutChunks.push(stdout);
+        stderrChunks.push(stderr);
+      } catch (error) {
+        return {
+          status: "failed",
+          summary: `Verification command failed: ${command}`,
+          stdout: stdoutChunks.join("\n"),
+          stderr: error && typeof error === "object" && "stderr" in error ? String(error.stderr ?? "") : String(error),
+          errorCategory: "execution_error"
+        };
+      }
+    }
+    return {
+      status: "completed",
+      summary: `Verification completed for ${input.commands.length} command(s).`,
+      stdout: stdoutChunks.join("\n"),
+      stderr: stderrChunks.join("\n")
+    };
+  }
+}
+function createVerificationAdapter() {
+  return String(
+    process.env.TREESEED_AGENT_VERIFICATION_PROVIDER ?? getTreeseedAgentProviderSelections().verification
+  ).toLowerCase() !== "local" ? new StubVerificationAdapter() : new LocalVerificationAdapter();
+}
+export {
+  LocalVerificationAdapter,
+  StubVerificationAdapter,
+  createVerificationAdapter
+};

package/dist/agents/cli-tools.d.ts

@@ -0,0 +1 @@
+export { normalizeAgentCliOptions, buildCopilotAllowToolArgs } from '@treeseed/sdk/cli-tools';

package/dist/agents/cli-tools.js

@@ -0,0 +1,5 @@
+import { normalizeAgentCliOptions, buildCopilotAllowToolArgs } from "@treeseed/sdk/cli-tools";
+export {
+  buildCopilotAllowToolArgs,
+  normalizeAgentCliOptions
+};

package/dist/agents/cli.d.ts

@@ -0,0 +1,15 @@
+export type TreeseedAgentCliCommandName = 'doctor' | 'run-agent' | 'drain-messages' | 'release-leases' | 'replay-message' | 'start';
+export type TreeseedAgentCliCommandSpec = {
+    name: TreeseedAgentCliCommandName;
+    usage: string;
+    summary: string;
+};
+export type TreeseedAgentCliContext = {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    write?: (output: string, stream?: 'stdout' | 'stderr') => void;
+    outputFormat?: 'human' | 'json';
+};
+export declare function listTreeseedAgentCommands(): TreeseedAgentCliCommandSpec[];
+export declare function renderTreeseedAgentHelp(): string;
+export declare function runTreeseedAgentCli(argv: string[], context?: TreeseedAgentCliContext): Promise<number>;

package/dist/agents/cli.js

@@ -0,0 +1,109 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const AGENT_COMMAND_SPECS = [
+  { name: "doctor", usage: "doctor", summary: "Inspect agent runtime readiness for the current tenant." },
+  { name: "run-agent", usage: "run-agent <slug>", summary: "Run one registered agent handler by slug." },
+  { name: "drain-messages", usage: "drain-messages", summary: "Drain queued agent messages through the local kernel." },
+  { name: "release-leases", usage: "release-leases", summary: "Release active task leases held by the local kernel." },
+  { name: "replay-message", usage: "replay-message <id>", summary: "Replay one message by numeric id." },
+  { name: "start", usage: "start", summary: "Start the local agent kernel loop." }
+];
+function parseArgs(argv) {
+  const [command = "doctor", ...rest] = argv;
+  return {
+    command,
+    args: rest
+  };
+}
+function listTreeseedAgentCommands() {
+  return [...AGENT_COMMAND_SPECS];
+}
+function renderTreeseedAgentHelp() {
+  return [
+    "treeseed agents <command>",
+    "",
+    "Commands:",
+    ...AGENT_COMMAND_SPECS.map((command) => `  ${command.usage.padEnd(24)}${command.summary}`)
+  ].join("\n");
+}
+function defaultWrite(output, stream = "stdout") {
+  if (!output) return;
+  (stream === "stderr" ? process.stderr : process.stdout).write(`${output}
+`);
+}
+function resolveExecutablePath(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return resolve(path);
+  }
+}
+async function runTreeseedAgentCli(argv, context = {}) {
+  const { command, args } = parseArgs(argv);
+  const write = context.write ?? defaultWrite;
+  if (command === "--help" || command === "-h" || command === "help") {
+    write(renderTreeseedAgentHelp(), "stdout");
+    return 0;
+  }
+  const [{ AgentKernel }, { AgentSdk }] = await Promise.all([
+    import("./kernel/agent-kernel.js"),
+    import("@treeseed/sdk/sdk")
+  ]);
+  const repoRoot = context.cwd ?? process.cwd();
+  const env = { ...process.env, ...context.env ?? {} };
+  const sdk = AgentSdk.createLocal({
+    repoRoot,
+    databaseName: env.TREESEED_AGENT_D1_DATABASE ?? "karyon-docs-site-data",
+    persistTo: env.TREESEED_AGENT_D1_PERSIST_TO ?? void 0
+  });
+  const kernel = new AgentKernel(sdk, repoRoot);
+  const emitPayload = async (payload) => {
+    write(JSON.stringify(await payload, null, 2), "stdout");
+    return 0;
+  };
+  if (command === "doctor") {
+    return emitPayload({ ok: true, command, ...await kernel.doctor() });
+  }
+  if (command === "run-agent") {
+    return emitPayload({ ok: true, command, slug: args[0], result: await kernel.runAgent(args[0]) });
+  }
+  if (command === "drain-messages") {
+    return emitPayload({ ok: true, command, results: await kernel.drainMessages() });
+  }
+  if (command === "release-leases") {
+    return emitPayload({ ok: true, command, result: await kernel.releaseLeases() });
+  }
+  if (command === "replay-message") {
+    return emitPayload({ ok: true, command, result: await kernel.replayMessage(Number(args[0])) });
+  }
+  if (command === "start") {
+    write(JSON.stringify({ ok: true, command, status: "starting" }, null, 2), "stdout");
+    await kernel.start();
+    return 0;
+  }
+  throw new Error(`Unknown Treeseed command "${command}".`);
+}
+const currentFile = resolveExecutablePath(fileURLToPath(import.meta.url));
+const entryFile = resolveExecutablePath(process.argv[1] ?? "");
+if (entryFile === currentFile) {
+  runTreeseedAgentCli(process.argv.slice(2)).catch((error) => {
+    defaultWrite(
+      JSON.stringify(
+        {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error)
+        },
+        null,
+        2
+      ),
+      "stderr"
+    );
+    process.exit(1);
+  });
+}
+export {
+  listTreeseedAgentCommands,
+  renderTreeseedAgentHelp,
+  runTreeseedAgentCli
+};

package/dist/agents/contracts/messages.d.ts

@@ -0,0 +1,88 @@
+export interface QuestionPriorityUpdatedMessage {
+    questionId: string;
+    reason: string;
+    plannerRunId: string;
+}
+export interface ObjectivePriorityUpdatedMessage {
+    objectiveId: string;
+    reason: string;
+    plannerRunId: string;
+}
+export interface ArchitectureUpdatedMessage {
+    objectiveId: string;
+    knowledgeId: string;
+    architectRunId: string;
+}
+export interface SubscriberNotifiedMessage {
+    email: string;
+    itemCount: number;
+    notifierRunId: string;
+}
+export interface ResearchStartedMessage {
+    questionId: string;
+    researcherRunId: string;
+}
+export interface ResearchCompletedMessage {
+    questionId: string;
+    knowledgeId: string | null;
+    researcherRunId: string;
+}
+export interface TaskCompleteMessage {
+    branchName: string | null;
+    changedTargets: string[];
+    engineerRunId: string;
+}
+export interface TaskWaitingMessage {
+    blockingReason: string;
+    engineerRunId: string;
+}
+export interface TaskFailedMessage {
+    failureSummary: string;
+    engineerRunId: string;
+}
+export interface TaskVerifiedMessage {
+    branchName: string | null;
+    reviewerRunId: string;
+}
+export interface ReviewFailedMessage {
+    failureSummary: string;
+    reviewerRunId: string;
+}
+export interface ReviewWaitingMessage {
+    blockingReason: string;
+    reviewerRunId: string;
+}
+export interface ReleaseStartedMessage {
+    taskRunId: string | null;
+    releaserRunId: string;
+}
+export interface ReleaseCompletedMessage {
+    releaseSummary: string;
+    releaserRunId: string;
+}
+export interface ReleaseFailedMessage {
+    failureSummary: string;
+    releaserRunId: string;
+}
+export interface AgentMessageContracts {
+    question_priority_updated: QuestionPriorityUpdatedMessage;
+    objective_priority_updated: ObjectivePriorityUpdatedMessage;
+    architecture_updated: ArchitectureUpdatedMessage;
+    subscriber_notified: SubscriberNotifiedMessage;
+    research_started: ResearchStartedMessage;
+    research_completed: ResearchCompletedMessage;
+    task_complete: TaskCompleteMessage;
+    task_waiting: TaskWaitingMessage;
+    task_failed: TaskFailedMessage;
+    task_verified: TaskVerifiedMessage;
+    review_failed: ReviewFailedMessage;
+    review_waiting: ReviewWaitingMessage;
+    release_started: ReleaseStartedMessage;
+    release_completed: ReleaseCompletedMessage;
+    release_failed: ReleaseFailedMessage;
+}
+export type AgentMessageType = keyof AgentMessageContracts;
+export type AgentMessagePayload<TType extends AgentMessageType> = AgentMessageContracts[TType];
+export declare const AGENT_MESSAGE_TYPES: readonly ["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"];
+export declare function parseAgentMessagePayload<TType extends AgentMessageType>(type: TType, payloadJson: string): AgentMessagePayload<TType>;
+export declare function serializeAgentMessagePayload<TType extends AgentMessageType>(type: TType, payload: AgentMessagePayload<TType>): Record<string, unknown>;

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/contracts/run.d.ts

@@ -0,0 +1,21 @@
+export type AgentErrorCategory = 'trigger_resolution_error' | 'permission_error' | 'message_claim_error' | 'lease_error' | 'execution_error' | 'mutation_error' | 'sdk_error';
+export interface AgentRunTrace {
+    [key: string]: unknown;
+    runId: string;
+    agentSlug: string;
+    handlerKind: string;
+    triggerKind: string;
+    triggerSource: string;
+    claimedMessageId: number | null;
+    selectedItemKey: string | null;
+    branchName: string | null;
+    commitSha: string | null;
+    changedPaths: string[];
+    summary: string | null;
+    error: string | null;
+    errorCategory: AgentErrorCategory | null;
+    startedAt: string;
+    finishedAt: string | null;
+    status: string;
+}
+export {};

package/dist/agents/index.d.ts

@@ -0,0 +1 @@
+export { listRegisteredAgentHandlers, resolveAgentHandler } from './registry.ts';

package/dist/agents/index.js

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

package/dist/agents/kernel/agent-kernel.d.ts

@@ -0,0 +1,63 @@
+import type { AgentExecutionAdapter, AgentMutationAdapter, AgentNotificationAdapter, AgentRepositoryInspectionAdapter, AgentResearchAdapter, AgentTriggerInvocation, AgentVerificationAdapter } from '../runtime-types.ts';
+import { AgentSdk } from '@treeseed/sdk/sdk';
+export declare class AgentKernel {
+    private readonly sdk;
+    private readonly repoRoot;
+    private readonly execution;
+    private readonly mutations;
+    private readonly repository;
+    private readonly verification;
+    private readonly notifications;
+    private readonly research;
+    private readonly activeRuns;
+    private readonly lastRunAt;
+    constructor(sdk: AgentSdk, repoRoot: string, options?: {
+        execution?: AgentExecutionAdapter;
+        mutations?: AgentMutationAdapter;
+        repository?: AgentRepositoryInspectionAdapter;
+        verification?: AgentVerificationAdapter;
+        notifications?: AgentNotificationAdapter;
+        research?: AgentResearchAdapter;
+    });
+    doctor(): Promise<{
+        agents: {
+            slug: string;
+            handler: string;
+            enabled: boolean;
+            triggers: ("message" | "follow" | "schedule" | "startup")[];
+        }[];
+        diagnostics: import("../spec-types.ts").AgentSpecDiagnostic[];
+    }>;
+    private sortAgents;
+    private resolveTrigger;
+    private recordRunTrace;
+    private buildTrace;
+    private categorizeError;
+    private executeAgent;
+    runAgent(slug: string, mode?: 'auto' | 'manual', invocation?: AgentTriggerInvocation | null): Promise<{
+        status: string;
+        summary: string;
+    }>;
+    runCycle(): Promise<{
+        slug: string;
+        result: import("../runtime-types.ts").AgentExecutionResult | {
+            status: string;
+            summary: string;
+        };
+    }[]>;
+    start(intervalMs?: number): Promise<void>;
+    drainMessages(): Promise<{
+        slug: string;
+        result: {
+            status: string;
+            summary: string;
+        };
+    }[]>;
+    releaseLeases(): Promise<import("@treeseed/sdk").SdkJsonEnvelope<{
+        count: number;
+    }>>;
+    replayMessage(id: number): Promise<{
+        id: number;
+        status: string;
+    }>;
+}