@treeseed/agent 0.1.2

package/Dockerfile

@@ -0,0 +1,7 @@
+FROM node:20-bookworm-slim
+
+WORKDIR /app
+
+COPY . .
+
+ENTRYPOINT ["node", "./dist/scripts/treeseed-agents.js", "start"]

package/README.md

@@ -0,0 +1,62 @@
+# `@treeseed/agent`
+
+Treeseed agent service runtime package.
+
+This package publishes the `treeseed-agents` CLI and the runtime exports needed to load, inspect, and execute TreeSeed agents in a Treeseed tenant repository.
+
+## Requirements
+
+- Node `>=20`
+- npm
+- a Treeseed tenant repository for runtime commands such as `doctor` and `start`
+
+## Install
+
+```bash
+npm install @treeseed/agent @treeseed/core @treeseed/sdk
+```
+
+## Build And Test
+
+```bash
+npm install
+npm run build
+npm test
+npm run release:verify
+```
+
+`npm test` runs the package smoke test. `npm run release:verify` rebuilds the package, runs the smoke test, and verifies that the packed tarball installs cleanly with the published `treeseed-agents` binary.
+
+## CLI
+
+Run the CLI from a Treeseed tenant repository root, or set `TREESEED_TENANT_ROOT` to point at one.
+
+```bash
+treeseed-agents doctor
+treeseed-agents run-agent planner-agent
+treeseed-agents start
+```
+
+Available commands:
+
+- `doctor`
+- `run-agent <slug>`
+- `drain-messages`
+- `release-leases`
+- `replay-message <id>`
+- `start`
+
+## Package Scripts
+
+- `npm run setup`: install dependencies with `npm install`
+- `npm run setup:ci`: install dependencies with `npm ci`
+- `npm run build`: build the distributable package
+- `npm test`: run the smoke test
+- `npm run release:verify`: verify build, smoke test, and packed-install behavior
+- `npm run release:check-tag -- <tag>`: validate plain semver tags like `0.1.1` against `package.json`
+- `npm run release:publish`: publish to npm
+
+## GitHub Actions
+
+- `.github/workflows/ci.yml` runs `npm ci`, `npm run build`, `npm test`, and `npm run release:verify` on pushes and pull requests.
+- `.github/workflows/publish.yml` runs the same verification steps before publishing on `*.*.*` version tags or manual dispatch.

package/dist/agent-runtime.js

@@ -0,0 +1,111 @@
+import { loadTreeseedPluginRuntime } from "@treeseed/core/plugins/runtime";
+import {
+  CopilotExecutionAdapter,
+  ManualExecutionAdapter,
+  StubExecutionAdapter
+} from "./agents/adapters/execution.js";
+import { LocalBranchMutationAdapter } from "./agents/adapters/mutations.js";
+import { StubNotificationAdapter } from "./agents/adapters/notification.js";
+import { GitRepositoryInspectionAdapter, StubRepositoryInspectionAdapter } from "./agents/adapters/repository.js";
+import { StubResearchAdapter } from "./agents/adapters/research.js";
+import { LocalVerificationAdapter, StubVerificationAdapter } from "./agents/adapters/verification.js";
+let cachedAgentRuntime = null;
+function readPluginRecord(pluginEntry, key) {
+  const value = pluginEntry.plugin[key];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function assertUniqueProvider(registry, id, owner) {
+  if (registry.has(id)) {
+    throw new Error(`Treeseed plugin runtime found duplicate provider "${id}" from ${owner}.`);
+  }
+}
+function collectAgentHandlersFromPlugin(pluginEntry, registry) {
+  const contributedHandlers = readPluginRecord(pluginEntry, "agentHandlers");
+  for (const [id, handler] of Object.entries(contributedHandlers)) {
+    assertUniqueProvider(registry, id, pluginEntry.package);
+    registry.set(id, handler);
+  }
+}
+function buildAgentRuntime() {
+  const runtime = loadTreeseedPluginRuntime();
+  const execution = /* @__PURE__ */ new Map([
+    ["stub", () => new StubExecutionAdapter()],
+    ["manual", () => new ManualExecutionAdapter()],
+    ["copilot", () => new CopilotExecutionAdapter()]
+  ]);
+  const mutation = /* @__PURE__ */ new Map([
+    ["local_branch", (repoRoot) => new LocalBranchMutationAdapter(repoRoot)]
+  ]);
+  const repository = /* @__PURE__ */ new Map([
+    ["stub", () => new StubRepositoryInspectionAdapter()],
+    ["git", () => new GitRepositoryInspectionAdapter()]
+  ]);
+  const verification = /* @__PURE__ */ new Map([
+    ["stub", () => new StubVerificationAdapter()],
+    ["local", () => new LocalVerificationAdapter()]
+  ]);
+  const notification = /* @__PURE__ */ new Map([["stub", () => new StubNotificationAdapter()]]);
+  const research = /* @__PURE__ */ new Map([["stub", () => new StubResearchAdapter()]]);
+  const handlers = /* @__PURE__ */ new Map();
+  for (const pluginEntry of runtime.plugins) {
+    const agentProviders = readPluginRecord(pluginEntry, "agentProviders");
+    for (const [id, factory] of Object.entries(agentProviders.execution ?? {})) {
+      assertUniqueProvider(execution, id, pluginEntry.package);
+      execution.set(id, factory);
+    }
+    for (const [id, factory] of Object.entries(agentProviders.mutation ?? {})) {
+      assertUniqueProvider(mutation, id, pluginEntry.package);
+      mutation.set(id, factory);
+    }
+    for (const [id, factory] of Object.entries(agentProviders.repository ?? {})) {
+      assertUniqueProvider(repository, id, pluginEntry.package);
+      repository.set(id, factory);
+    }
+    for (const [id, factory] of Object.entries(agentProviders.verification ?? {})) {
+      assertUniqueProvider(verification, id, pluginEntry.package);
+      verification.set(id, factory);
+    }
+    for (const [id, factory] of Object.entries(agentProviders.notification ?? {})) {
+      assertUniqueProvider(notification, id, pluginEntry.package);
+      notification.set(id, factory);
+    }
+    for (const [id, factory] of Object.entries(agentProviders.research ?? {})) {
+      assertUniqueProvider(research, id, pluginEntry.package);
+      research.set(id, factory);
+    }
+    collectAgentHandlersFromPlugin(pluginEntry, handlers);
+  }
+  return {
+    providers: { execution, mutation, repository, verification, notification, research },
+    handlers
+  };
+}
+function resolveAgentRuntimeProviders(repoRoot, selections) {
+  if (!cachedAgentRuntime) {
+    cachedAgentRuntime = buildAgentRuntime();
+  }
+  const executionFactory = cachedAgentRuntime.providers.execution.get(selections.execution);
+  const mutationFactory = cachedAgentRuntime.providers.mutation.get(selections.mutation);
+  const repositoryFactory = cachedAgentRuntime.providers.repository.get(selections.repository);
+  const verificationFactory = cachedAgentRuntime.providers.verification.get(selections.verification);
+  const notificationFactory = cachedAgentRuntime.providers.notification.get(selections.notification);
+  const researchFactory = cachedAgentRuntime.providers.research.get(selections.research);
+  if (!executionFactory) throw new Error(`Treeseed agent execution provider "${selections.execution}" is not registered.`);
+  if (!mutationFactory) throw new Error(`Treeseed agent mutation provider "${selections.mutation}" is not registered.`);
+  if (!repositoryFactory) throw new Error(`Treeseed agent repository provider "${selections.repository}" is not registered.`);
+  if (!verificationFactory) throw new Error(`Treeseed agent verification provider "${selections.verification}" is not registered.`);
+  if (!notificationFactory) throw new Error(`Treeseed agent notification provider "${selections.notification}" is not registered.`);
+  if (!researchFactory) throw new Error(`Treeseed agent research provider "${selections.research}" is not registered.`);
+  return {
+    execution: executionFactory(),
+    mutations: mutationFactory(repoRoot),
+    repository: repositoryFactory(),
+    verification: verificationFactory(),
+    notifications: notificationFactory(),
+    research: researchFactory(),
+    handlers: cachedAgentRuntime.handlers
+  };
+}
+export {
+  resolveAgentRuntimeProviders
+};

package/dist/agents/adapters/execution.js

@@ -0,0 +1,90 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizeAgentCliOptions, buildCopilotAllowToolArgs } from "../cli-tools.js";
+import { getTreeseedAgentProviderSelections } from "@treeseed/core/deploy/runtime";
+const execFileAsync = promisify(execFile);
+class StubExecutionAdapter {
+  async runTask(input) {
+    return {
+      status: "completed",
+      summary: `Stubbed Copilot execution for ${input.runId}.`,
+      stdout: [
+        "# Planned Task",
+        "",
+        "1. Inspect the requested architecture context.",
+        "2. Produce a safe local change artifact.",
+        "3. Summarize the implementation intent.",
+        "",
+        `Prompt digest: ${input.prompt.slice(0, 240)}`
+      ].join("\n"),
+      stderr: ""
+    };
+  }
+}
+class CopilotExecutionAdapter {
+  async runTask(input) {
+    const cli = normalizeAgentCliOptions(input.agent.cli);
+    const args = ["copilot", "-p", input.prompt];
+    if (cli.model) {
+      args.push("--model", cli.model);
+    }
+    args.push(...buildCopilotAllowToolArgs(cli.allowTools));
+    args.push(...cli.additionalArgs ?? []);
+    try {
+      const { stdout, stderr } = await execFileAsync("gh", args, {
+        cwd: process.cwd(),
+        env: process.env,
+        maxBuffer: 10 * 1024 * 1024
+      });
+      return {
+        status: "completed",
+        summary: "Copilot task completed.",
+        stdout,
+        stderr
+      };
+    } catch (error) {
+      const stderr = error && typeof error === "object" && "stderr" in error ? String(error.stderr ?? "") : error instanceof Error ? error.message : String(error);
+      return {
+        status: "failed",
+        summary: "Copilot task failed.",
+        stdout: "",
+        stderr
+      };
+    }
+  }
+}
+class ManualExecutionAdapter {
+  async runTask(input) {
+    return {
+      status: "completed",
+      summary: `Manual execution mode is enabled for ${input.runId}.`,
+      stdout: [
+        "# Manual Execution Required",
+        "",
+        "This agent run is configured for manual execution.",
+        "Review the prompt below and complete the work outside the automated adapter.",
+        "",
+        input.prompt
+      ].join("\n"),
+      stderr: ""
+    };
+  }
+}
+function createExecutionAdapter() {
+  const configuredMode = String(
+    process.env.TREESEED_AGENT_EXECUTION_PROVIDER ?? getTreeseedAgentProviderSelections().execution
+  ).toLowerCase();
+  if (configuredMode === "manual") {
+    return new ManualExecutionAdapter();
+  }
+  if (configuredMode !== "copilot") {
+    return new StubExecutionAdapter();
+  }
+  return new CopilotExecutionAdapter();
+}
+export {
+  CopilotExecutionAdapter,
+  ManualExecutionAdapter,
+  StubExecutionAdapter,
+  createExecutionAdapter
+};

package/dist/agents/adapters/mutations.js

@@ -0,0 +1,30 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { GitRuntime } from "../git-runtime.js";
+class LocalBranchMutationAdapter {
+  git;
+  constructor(repoRoot) {
+    this.git = new GitRuntime(
+      repoRoot,
+      process.env.TREESEED_AGENT_DISABLE_GIT === "true"
+    );
+  }
+  async writeArtifact(input) {
+    const branchName = `${input.agent.execution.branchPrefix}/${input.runId}`;
+    const worktreePath = await this.git.ensureWorktree(branchName);
+    const filePath = path.join(worktreePath, input.relativePath);
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, input.content, "utf8");
+    const git = await this.git.commitFileChange(filePath, branchName, input.commitMessage);
+    return {
+      branchName: git.branchName,
+      commitMessage: git.commitMessage,
+      worktreePath: git.worktreePath,
+      commitSha: git.commitSha,
+      changedPaths: git.changedPaths
+    };
+  }
+}
+export {
+  LocalBranchMutationAdapter
+};

package/dist/agents/adapters/notification.js

@@ -0,0 +1,16 @@
+class StubNotificationAdapter {
+  async deliver(input) {
+    return {
+      status: input.recipients.length ? "completed" : "waiting",
+      summary: input.recipients.length ? `Prepared ${input.recipients.length} notification(s).` : "No recipients available for notification.",
+      deliveredCount: input.recipients.length
+    };
+  }
+}
+function createNotificationAdapter() {
+  return new StubNotificationAdapter();
+}
+export {
+  StubNotificationAdapter,
+  createNotificationAdapter
+};

package/dist/agents/adapters/repository.js

@@ -0,0 +1,61 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { getTreeseedAgentProviderSelections } from "@treeseed/core/deploy/runtime";
+const execFileAsync = promisify(execFile);
+class StubRepositoryInspectionAdapter {
+  async inspectBranch(input) {
+    return {
+      branchName: input.branchName,
+      changedPaths: [],
+      commitSha: null,
+      summary: input.branchName ? `Stub repository inspection for ${input.branchName}.` : "No branch to inspect."
+    };
+  }
+}
+class GitRepositoryInspectionAdapter {
+  async inspectBranch(input) {
+    if (!input.branchName) {
+      return {
+        branchName: null,
+        changedPaths: [],
+        commitSha: null,
+        summary: "No branch to inspect."
+      };
+    }
+    try {
+      const { stdout: changedStdout } = await execFileAsync(
+        "git",
+        ["diff", "--name-only", "HEAD~1..HEAD"],
+        { cwd: input.repoRoot, env: process.env }
+      );
+      const { stdout: shaStdout } = await execFileAsync("git", ["rev-parse", "HEAD"], {
+        cwd: input.repoRoot,
+        env: process.env
+      });
+      const changedPaths = changedStdout.split("\n").map((entry) => entry.trim()).filter(Boolean);
+      return {
+        branchName: input.branchName,
+        changedPaths,
+        commitSha: shaStdout.trim() || null,
+        summary: `Inspected ${changedPaths.length} changed path(s) on ${input.branchName}.`
+      };
+    } catch {
+      return {
+        branchName: input.branchName,
+        changedPaths: [],
+        commitSha: null,
+        summary: `Unable to inspect branch ${input.branchName}.`
+      };
+    }
+  }
+}
+function createRepositoryInspectionAdapter() {
+  return String(
+    process.env.TREESEED_AGENT_REPOSITORY_PROVIDER ?? getTreeseedAgentProviderSelections().repository
+  ).toLowerCase() !== "git" ? new StubRepositoryInspectionAdapter() : new GitRepositoryInspectionAdapter();
+}
+export {
+  GitRepositoryInspectionAdapter,
+  StubRepositoryInspectionAdapter,
+  createRepositoryInspectionAdapter
+};

package/dist/agents/adapters/research.js

@@ -0,0 +1,25 @@
+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: []
+    };
+  }
+}
+function createResearchAdapter() {
+  return new StubResearchAdapter();
+}
+export {
+  StubResearchAdapter,
+  createResearchAdapter
+};

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/core/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.js

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

package/dist/agents/cli.js

@@ -0,0 +1,77 @@
+function parseArgs(argv) {
+  const [, , command = "doctor", ...rest] = argv;
+  return {
+    command,
+    args: rest
+  };
+}
+function renderHelp() {
+  return [
+    "treeseed-agents <command>",
+    "",
+    "Commands:",
+    "  doctor",
+    "  run-agent <slug>",
+    "  drain-messages",
+    "  release-leases",
+    "  replay-message <id>",
+    "  start"
+  ].join("\n");
+}
+async function main() {
+  const { command, args } = parseArgs(process.argv);
+  if (command === "--help" || command === "-h" || command === "help") {
+    console.log(renderHelp());
+    return;
+  }
+  const [{ AgentKernel }, { AgentSdk }] = await Promise.all([
+    import("./kernel/agent-kernel.js"),
+    import("./sdk.js")
+  ]);
+  const repoRoot = process.cwd();
+  const sdk = AgentSdk.createLocal({
+    repoRoot,
+    databaseName: process.env.TREESEED_AGENT_D1_DATABASE ?? "karyon-docs-site-data",
+    persistTo: process.env.TREESEED_AGENT_D1_PERSIST_TO ?? void 0
+  });
+  const kernel = new AgentKernel(sdk, repoRoot);
+  if (command === "doctor") {
+    console.log(JSON.stringify({ ok: true, command, ...await kernel.doctor() }, null, 2));
+    return;
+  }
+  if (command === "run-agent") {
+    console.log(JSON.stringify({ ok: true, command, slug: args[0], result: await kernel.runAgent(args[0]) }, null, 2));
+    return;
+  }
+  if (command === "drain-messages") {
+    console.log(JSON.stringify({ ok: true, command, results: await kernel.drainMessages() }, null, 2));
+    return;
+  }
+  if (command === "release-leases") {
+    console.log(JSON.stringify({ ok: true, command, result: await kernel.releaseLeases() }, null, 2));
+    return;
+  }
+  if (command === "replay-message") {
+    console.log(JSON.stringify({ ok: true, command, result: await kernel.replayMessage(Number(args[0])) }, null, 2));
+    return;
+  }
+  if (command === "start") {
+    console.log(JSON.stringify({ ok: true, command, status: "starting" }, null, 2));
+    await kernel.start();
+    return;
+  }
+  throw new Error(`Unknown Treeseed command "${command}".`);
+}
+main().catch((error) => {
+  console.error(
+    JSON.stringify(
+      {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error)
+      },
+      null,
+      2
+    )
+  );
+  process.exit(1);
+});

package/dist/agents/content-store.js

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