opencode-teammate 0.1.0

package/src/tools/i-am-stuck.ts

@@ -0,0 +1,49 @@
+import { tool } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2/client";
+import { assert, dedent } from "radashi";
+
+import * as beads from "../adapters/beads";
+
+export const createIAmStuck = (client: OpencodeClient) =>
+  tool({
+    description: dedent`
+    Inform your manager that you are stuck and cannot proceed with the task. The manager will then jump in to help you out.
+    Use this tool when:
+    - You need human intervention to proceed with the task.
+    - You face an issue that you cannot resolve on your own.
+  `,
+    args: {
+      reason: tool.schema
+        .string()
+        .describe("Describe why you are stuck and what kind of help you need."),
+    },
+    execute: async (args, ctx) => {
+      const session = await client.session.get({
+        sessionID: ctx.sessionID,
+        directory: ctx.directory,
+      });
+      assert(session.data, `Failed to fetch session: ${JSON.stringify(session.error)}`);
+
+      const message = await client.session.message({
+        sessionID: ctx.sessionID,
+        messageID: ctx.messageID,
+        directory: ctx.directory,
+      });
+      assert(message.data, `Failed to fetch session message: ${JSON.stringify(session.error)}`);
+
+      const { info } = message.data;
+
+      await beads.agents.stuck(Bun.$.cwd(session.data.directory), session.data.slug, {
+        reason: args.reason,
+        context: {
+          agent: ctx.agent,
+          model: info.role === "user" ? info.model.modelID : info.modelID,
+          provider: info.role === "user" ? info.model.providerID : info.providerID,
+        },
+      });
+
+      return dedent`
+        Your manager has been notified. Please wait for him to jump in and help you out.
+      `;
+    },
+  });

package/src/tools/index.ts

@@ -0,0 +1,2 @@
+export * from "./i-am-stuck";
+export * from "./i-am-done";

package/src/use-cases/index.ts

@@ -0,0 +1,5 @@
+// export * from "./track-specs";
+// export * from "./sync-teammates";
+export * from "./sync-specifications";
+export * from "./work-on-issue";
+export * from "./inject-beads-issue";

package/src/use-cases/inject-beads-issue.ts

@@ -0,0 +1,97 @@
+import { assert, dedent, first } from "radashi";
+import type { OpencodeClient, TextPartInput } from "@opencode-ai/sdk/v2/client";
+import type { Part } from "@opencode-ai/sdk";
+
+import * as beads from "../adapters/beads/index.js";
+import * as chain from "../utils/chain.js";
+
+const WHITE_LISTED_COMMANDS = new Set(["work", "fake_work"]);
+
+export async function injectBeadsIssue(options: {
+  client: OpencodeClient;
+  directory: string;
+  input: {
+    sessionID: string;
+    command: string;
+    arguments: string;
+  };
+  output: {
+    parts: Part[];
+  };
+}) {
+  const { input } = options;
+
+  assert(
+    !WHITE_LISTED_COMMANDS.has(input.command),
+    chain.createBegnign(`Command '${input.command}' is not withe-listed`),
+  );
+
+  const $ = Bun.$.cwd(options.directory);
+  const log = createLog(input.command);
+
+  const issueId = first(input.arguments.split(" "));
+  assert(issueId, chain.createBegnign(`Issue ID not found`));
+
+  const prefix = await beads.config.issuePrefix($);
+  assert(
+    issueId.startsWith(prefix.value),
+    chain.createBegnign(`Issue ID: ${issueId}, expected to start with '${prefix.value}' prefix`),
+  );
+
+  const alreadyInjected = options.output.parts.some(
+    (part) => part.type === "text" && part.metadata?.["injected_beads_issue_id"] === issueId,
+  );
+  assert(
+    alreadyInjected,
+    chain.createBegnign(`Injection for '${issueId}' already exists, skipped.`),
+  );
+
+  const [error, injection] = await beads.issues.show($, { id: issueId });
+  assert(error === undefined, chain.createError(`Failed to inject issue ${issueId}: ${error}`));
+  assert(injection, chain.createError(`Nothing to inject for issue '${issueId}'`));
+
+  const partToInject = createInjectionPart(issueId, injection);
+
+  // If the user provided only the issue ID, we replace it into the existing message
+  const shouldReplaceOnExistingMessage = options.input.arguments.trim() === issueId;
+
+  if (shouldReplaceOnExistingMessage) {
+    const partToEdit = options.output.parts.find(
+      (part) => part.type === "text" && part.text.includes(issueId),
+    );
+
+    if (partToEdit && partToEdit.type === "text") {
+      partToEdit.text = partToEdit.text.replace(issueId, partToInject.text);
+      partToEdit.metadata = Object.assign({}, partToEdit.metadata, partToInject.metadata);
+
+      log(`Message updated with issue '${issueId}' injection`);
+
+      return;
+    }
+  }
+
+  // fallback on adding a new part on the message
+  options.output.parts.push(partToInject as unknown as Part);
+
+  log(`Message part added with issue '${issueId}' injection`);
+}
+
+function createInjectionPart(issueId: string, content: string): TextPartInput {
+  return {
+    type: "text",
+    text: dedent`
+      <issue>
+      ${content}
+      </issue>
+    `,
+    metadata: {
+      injected_beads_issue_id: issueId,
+    },
+  };
+}
+
+function createLog(command: string) {
+  return (message: string) => {
+    console.log(`[inject:beads_issue:${command}] ${message}`);
+  };
+}

package/src/use-cases/sync-specifications.ts

@@ -0,0 +1,48 @@
+import { dedent, title } from "radashi";
+import * as path from "node:path";
+
+import * as assets from "../adapters/assets";
+import * as beads from "../adapters/beads";
+import * as fm from "../utils/frontmatter";
+
+export async function* syncSpecifications(options: {
+  project: string;
+  source: AsyncGenerator<assets.specifications.Specification>;
+}) {
+  const shell = Bun.$.cwd(options.project);
+
+  for await (const asset of options.source) {
+    const { file, filepath } = asset;
+    const { metadata, content } = fm.extract(await file.text());
+
+    const relative = path.relative(options.project, path.format(filepath));
+    const spec: beads.specifications.SpecificationInput = {
+      file: relative,
+      title: title(filepath.name),
+      description: dedent`
+        Spec: ${relative}
+      `,
+    };
+
+    const result = assets.specifications.Frontmatter.safeParse(metadata);
+    const existing =
+      result.success && result.data.issue
+        ? { id: result.data.issue }
+        : await beads.specifications.find.byExternalRef(shell, spec.file);
+
+    const issue = existing
+      ? await beads.specifications.update(shell, existing, spec)
+      : await beads.specifications.create(shell, spec);
+
+    const frontmatter = Object.assign({}, metadata, {
+      issue: issue.id,
+    });
+
+    await Bun.write(file, fm.apply(content, frontmatter));
+
+    yield {
+      asset,
+      issue,
+    };
+  }
+}

package/src/use-cases/sync-teammates.ts

@@ -0,0 +1,35 @@
+// import type { Event } from "@opencode-ai/sdk";
+// import type { PluginInput } from "@opencode-ai/plugin";
+// import type Bun from "bun";
+
+// import * as beads from "../adapters/beads";
+// import * as teammates from "../adapters/teammates";
+
+// export async function syncTeammates({ $ }: PluginInput, event: Event) {
+//   let teammate: string | undefined;
+//   let status: beads.agents.AgentState | undefined;
+
+//   if (event.type === "session.created") {
+//     teammate = teammates.createFromSession(event.properties.info);
+//     status = "spawning";
+//   } else if (event.type === "session.status") {
+//     teammate = teammates.get(event.properties.sessionID);
+
+//     const { type } = event.properties.status;
+
+//     if (type === "busy") status = "running";
+//     else if (type === "idle") status = "idle";
+//   } else if (event.type === "session.idle") {
+//     teammate = teammates.get(event.properties.sessionID);
+//     status = "idle";
+//   } else if (event.type === "session.deleted") {
+//     teammate = teammates.get(event.properties.info.id);
+//     status = "stopped";
+//   }
+
+//   if (!teammate) return false;
+//   if (!status) return false;
+
+//   await beads.agents.updateState($ as Bun.$, teammate, status);
+//   return true;
+// }

package/src/use-cases/track-specs.ts

@@ -0,0 +1,91 @@
+import { join, relative } from "path";
+import Bun from "bun";
+import type { Event } from "@opencode-ai/sdk";
+import type { PluginInput } from "@opencode-ai/plugin";
+
+import * as beads from "../adapters/beads";
+import { crush, dedent, isObject, isString, set, shake } from "radashi";
+
+export async function trackSpecs({ $, directory }: PluginInput, event: Event) {
+  if (event.type !== "file.edited") return undefined;
+
+  const { file } = event.properties;
+
+  const isSpec = file.startsWith(join(directory, "specs/"));
+  if (!isSpec) return undefined;
+
+  const path = relative(directory, file);
+  const { metadata, content } = extractFrontmatter(await Bun.file(file).text());
+
+  const spec: beads.specifications.SpecificationInput = {
+    file: path,
+    title: getSpecTitle(content) ?? `Untitled: ${path}`,
+    description: dedent`
+      ${getSpecOverview(content)}
+
+      Spec: ${path}
+    `,
+  };
+
+  const existing =
+    metadata && "issue" in metadata && isString(metadata.issue) && metadata.issue
+      ? { id: metadata.issue }
+      : await beads.specifications.find.byExternalRef($ as Bun.$, path);
+
+  const issue = existing
+    ? await beads.specifications.update($ as Bun.$, existing, spec)
+    : await beads.specifications.create($ as Bun.$, spec);
+
+  const issueId = isObject(issue) && "id" in issue ? issue.id : undefined;
+
+  const frontmatter = createFrontmatter({
+    ...metadata,
+    created: issue.created_at,
+    issue: issue.id,
+  });
+
+  await Bun.write(path, `${frontmatter}\n${content}`);
+
+  return issueId;
+}
+
+function getSpecTitle(content: string) {
+  return content.match(/^# Feature Specification: (.+)$/m)?.[1];
+}
+
+function getSpecOverview(content: string) {
+  return content.match(/## Overview\n\n([\s\S]*?)(?=\n## |\n### |$)/)?.[1]?.trim();
+}
+
+function createFrontmatter(metadata: object) {
+  const entries = Object.entries(crush(shake(metadata)));
+  if (entries.length === 0) return "";
+
+  const lines = entries.map(([key, value]) => `${key}: ${value}`);
+  return `---\n${lines.join("\n")}\n---\n`;
+}
+
+function extractFrontmatter(content: string): {
+  metadata: object;
+  content: string;
+} {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!frontmatterMatch) {
+    return { metadata: {}, content };
+  }
+
+  const frontmatterText = frontmatterMatch[1] ?? "";
+  const lines = frontmatterText.split("\n");
+  let result: Record<string, string> = {};
+
+  for (const line of lines) {
+    const [, key, value] = line.match(/^(\w+):\s*(.+)$/) ?? [];
+    if (key && value) {
+      result = set(result, key, value?.trim());
+    }
+  }
+
+  const contentWithoutFrontmatter = content.slice(frontmatterMatch[0].length);
+
+  return { metadata: result, content: contentWithoutFrontmatter };
+}

package/src/use-cases/work-on-issue.ts

@@ -0,0 +1,110 @@
+import { assert, dedent } from "radashi";
+import type { OpencodeClient, TextPartInput } from "@opencode-ai/sdk/v2/client";
+
+import * as beads from "../adapters/beads";
+import * as environments from "../adapters/environments";
+// import * as polling from "#utils/polling.js";
+import * as polling from "../utils/polling.js";
+
+export async function workOnIssue(options: {
+  client: OpencodeClient;
+  directory: string;
+  issue: { id: string } | beads.issues.Issue;
+}) {
+  const log = createLog(options.issue.id);
+
+  log(`Start working on ${options.issue.id}...`);
+
+  await using env = await environments.WorkerEnvironment.init({
+    client: options.client,
+    directory: options.directory,
+    name: options.issue.id,
+  });
+  log(`Environment ready: ${env.worktree.directory}`);
+
+  let issue = await beads.issues.claim(env.$, options.issue);
+  log(`Issue claimed: ${issue.id}`);
+
+  const session = await options.client.session.create({
+    directory: env.worktree.directory,
+    title: `${issue.id}: ${issue.title}`,
+  });
+  assert(session.data, `Failed to start the session: ${JSON.stringify(session.error)}`);
+  log(`Session: ${session.data.id}`);
+
+  const command = await options.client.session.command({
+    sessionID: session.data.id,
+    directory: env.worktree.directory,
+    // agent: "<task_assignee>", // FIXME: assign
+    command: "fake_work", // FIXME: work
+    arguments: `${issue.id}`,
+  });
+  assert(command.data, `Failed to send the /work command: ${JSON.stringify(command.error)}`);
+
+  let agent = await beads.agents.use(env.$, session.data);
+
+  while (agent.agent_state !== "done") {
+    if (agent.agent_state === "stuck") {
+      log(`Agent is stuck: ${agent.title}`);
+
+      await polling.waitFor(
+        async () => {
+          agent = await beads.agents.use(env.$, session.data);
+          return agent.agent_state !== "stuck";
+        },
+        { interval: "1s" },
+      );
+
+      log(`Agent is ready to continue: ${agent.agent_state}`);
+    } else {
+      log(`Agent needs follow up, '${agent.agent_state}'...`);
+
+      // @ts-ignore
+      const followUp = await options.client.session.prompt({
+        sessionID: session.data.id,
+        directory: env.worktree.directory,
+        parts: [createFollowUp(agent.agent_state)],
+      });
+      assert(followUp.data, `Failed to follow up: ${JSON.stringify(followUp.error)}`);
+    }
+
+    agent = await beads.agents.use(env.$, session.data);
+  }
+
+  log(`Agent work is done`);
+
+  const messages = await options.client.session.messages({
+    sessionID: session.data.id,
+    directory: env.worktree.directory,
+  });
+  assert(messages.data, `Failed to fetch session messages: ${messages.error}`);
+
+  log(`Session messages: ${messages.data.length}`);
+
+  issue = await beads.issues.close(env.$, options.issue, {
+    reason: "Completed",
+  });
+  assert(issue, `Failed to close the issue`);
+
+  // TODO: close the envrionment
+
+  return issue;
+}
+
+function createFollowUp(currentState: string) {
+  return {
+    type: "text",
+    text: dedent`
+      You are currently registered as '${currentState}'.
+      - If you are done with the task please notify via the i_am_done tool.
+      - If you are stuck and need human help, please notify via the i_am_stuck tool.
+      - If you need more time to work on the task, please continue working and update your status when needed.
+    `,
+  } satisfies TextPartInput;
+}
+
+function createLog(issueId: string) {
+  return (message: string) => {
+    console.log(`[work:${issueId}] ${message}`);
+  };
+}

package/src/utils/chain.ts

@@ -0,0 +1,60 @@
+type Chainable = () => Promise<void>;
+
+export type ChainOptions = {
+  /** @default true */
+  stopOnFatal?: boolean;
+};
+
+export async function chain(options: ChainOptions, ...fns: Chainable[]) {
+  const { stopOnFatal = true } = options;
+
+  for (const fn of fns) {
+    await fn().catch((error) => {
+      if (error instanceof ChainError) {
+        if (error.severity === "BEGNIGN") return;
+        if (error.severity === "WARNING") console.warn(error);
+        if (error.severity === "ERROR") console.error(error);
+        if (error.severity === "FATAL") {
+          console.error(error);
+
+          if (stopOnFatal) throw error;
+        }
+      } else throw error;
+    });
+  }
+}
+
+export function createBegnign(message: string, options?: ChainErrorOptions) {
+  return new ChainError(message, { severity: "BEGNIGN", ...options });
+}
+
+export function createError(message: string, options?: ChainErrorOptions) {
+  return new ChainError(message, { severity: "ERROR", ...options });
+}
+
+export type ChainErrorSeverity = "BEGNIGN" | "WARNING" | "ERROR" | "FATAL";
+
+export interface ChainErrorOptions {
+  severity?: ChainErrorSeverity;
+  stop?: boolean;
+  cause?: Error;
+}
+
+export class ChainError extends Error {
+  public readonly severity: ChainErrorSeverity;
+  public readonly stop: boolean;
+
+  constructor(
+    message: string,
+    options?: {
+      severity?: ChainErrorSeverity;
+      stop?: boolean;
+      cause?: Error;
+    },
+  ) {
+    super(message, { cause: options?.cause });
+
+    this.severity = options?.severity ?? "BEGNIGN";
+    this.stop = options?.stop ?? false;
+  }
+}