@ycodium-ai/plugin-teams 0.1.1

package/README.md

@@ -0,0 +1,66 @@
+# @ycodium-ai/plugin-teams
+
+Run a team of agents on one Ycodium machine: a task board, a roster of roles, a mailbox
+between them, and the rule for who gets sent work next.
+
+## What it does
+
+A **run** is a board of tasks and a roster of roles. Each role is an agent session — it can
+be a different model or provider from the others. The plugin asks the host for ready tasks
+and requests dispatch when tasks or member availability change, and when the plugin loads.
+
+The host checks the current task revision, role, member availability, and turn budget. It
+prepares the role brief, task details, acceptance findings, and unread messages for that run.
+Claiming the task, queuing its turn, and marking those messages delivered commit together.
+The board follows persisted events; a queued request is not proof that the provider started.
+
+What it enforces:
+
+- **One dispatcher at a time.** A task is offered to exactly one role, and not again until
+  that attempt settles.
+- **Admission.** A role is only sent work if the run is active, the role can be woken, it is
+  not already busy, and the run still has budget.
+- **Acceptance.** A delivered task waits for whoever was named to sign it off — another role,
+  or a person on the board.
+- **Budget.** A run has a ceiling on how many turns it may spend, checked before every
+  dispatch.
+
+## Requirements
+
+A Ycodium server with the `teams.dispatch` capability. Older servers cannot activate this
+version of the plugin.
+
+## Install
+
+```
+ycodium plugin add @ycodium-ai/plugin-teams
+```
+
+The plugin requests the **Assign ready team tasks to their members** permission. It can request dispatch of
+existing ready tasks; the host chooses the assigned member and prepares the turn. This
+permission does not allow arbitrary turns on unrelated threads.
+
+## Read this before installing
+
+**This plugin takes over dispatch.** It ships enabled with Ycodium. Disabling it stops new
+task dispatch; work already in progress can still finish. Enabling it scans existing ready
+tasks. The host executes its requests and does not run a second task scheduler.
+
+## Upgrading
+
+```
+ycodium plugin add @ycodium-ai/plugin-teams@<version>
+```
+
+Installing a newer version replaces the running one without restarting the server.
+
+## Developing
+
+Built from the Ycodium repository. The entry file is bundled into one ESM file with no
+runtime imports — the host loads a plugin by absolute path, from a directory that is not
+inside the plugin's own dependency tree, so a bare `import` at runtime would not resolve.
+Types come from `ycodium-plugin-api` and are erased at build time.
+
+## License
+
+UNLICENSED.

package/dist/index.js

@@ -0,0 +1,454 @@
+// src/facts.ts
+var TEAM_FACTS = {
+  /** 批次本身:在跑还是停了、预算多少、用了几轮。 */
+  run: "run",
+  /** 名册变了:谁在这个 run 里、什么角色、挂在哪条线程上。 */
+  member: "member",
+  /** 看板上一张卡的整张快照。卡的每一次变化都发一条,不发增量。 */
+  task: "task",
+  /**
+   * 受理了一次起轮尝试,以及它的结局。
+   *
+   * 这一条是 C4 争了六轮的那格。过去它只活在内存里,于是「排队等启动」和「启动失败」
+   * 只能从会话状态猜——猜错了就把还在排队的成员判成启动失败。当场记下来就没得猜。
+   */
+  startAttempt: "start-attempt",
+  /** 谁收过说明书。按线程记,不按角色:接班线程是新上下文,前任那份没跟过去。 */
+  briefSent: "brief-sent",
+  /** 一张卡正在从谁交到谁手上。 */
+  handoff: "handoff",
+  /** 在等谁回话,等到什么时候。 */
+  wait: "wait",
+  /** 信箱:一条消息进了队。 */
+  messageQueued: "message-queued",
+  /**
+   * 信箱:给收件人排了一次叫醒。**这不等于他取走了。**
+   *
+   * 宿主那套把这两件事塞进同一个事件 `team.message-delivered`,靠 `deliveredAt` 还是
+   * `wakeQueuedAt` 有值来区分——真库里 343 条里有 71 条只是排了叫醒。一个事件装两件事,
+   * 读的人迟早分不清;这里拆开。
+   */
+  messageWakeQueued: "message-wake-queued",
+  /** 信箱:收件人真的取走了。 */
+  messageDelivered: "message-delivered"
+};
+var TEAMS_PLUGIN_ID = "teams";
+
+// src/dispatchAction.ts
+var enqueueReadyTasks = async (ctx, query) => {
+  const tasks = await ctx.teams.listReadyTasks(query);
+  for (const task of tasks) {
+    await ctx.teams.dispatchTask(task);
+  }
+};
+
+// src/state.ts
+var TEAM_STATE_VERSION = 2;
+var TEAM_FOLDED_EVENTS = [
+  "plugin.event-appended",
+  "team.run-started",
+  "team.run-state-changed",
+  "team.member-thread-attached",
+  "team.task-created",
+  "team.task-changed",
+  "team.message-sent",
+  "team.message-delivered",
+  "thread.message-sent"
+];
+var emptyTeamState = () => ({
+  runs: {},
+  members: {},
+  tasks: {},
+  startAttempts: {},
+  briefed: [],
+  messages: {}
+});
+var ourFact = (event) => {
+  if (event.type !== "plugin.event-appended") return null;
+  const payload = event.payload;
+  if (payload === void 0 || payload.pluginId !== TEAMS_PLUGIN_ID) return null;
+  return payload;
+};
+var factName = (full) => full.startsWith(`${TEAMS_PLUGIN_ID}/`) ? full.slice(TEAMS_PLUGIN_ID.length + 1) : full;
+var applyHostTeamEvent = (state, event) => {
+  switch (event.type) {
+    case "team.run-started": {
+      const p = event.payload;
+      return {
+        ...state,
+        runs: {
+          ...state.runs,
+          // 没定过预算就记 null,和宿主投影表一样;默认值在用的时候才套(见 dispatch.ts)。
+          [p.runId]: {
+            runId: p.runId,
+            teamId: p.teamId ?? "",
+            state: "running",
+            turnBudget: p.turnBudget ?? null,
+            turnsUsed: 0
+          }
+        }
+      };
+    }
+    case "team.run-state-changed": {
+      const p = event.payload;
+      const current = state.runs[p.runId];
+      if (current === void 0) return state;
+      return {
+        ...state,
+        runs: {
+          ...state.runs,
+          [p.runId]: {
+            ...current,
+            state: p.state,
+            ...p.turnBudget === void 0 ? {} : { turnBudget: p.turnBudget },
+            // 事件带的是**增量**(每次那一笔),不是全量清单——所以要累加,不能替换。
+            // 第一版写成替换,拿真库一对全都变成 1,当场露馅。
+            turnsUsed: current.turnsUsed + (p.turnConsumption?.length ?? 0)
+          }
+        }
+      };
+    }
+    case "team.member-thread-attached": {
+      const p = event.payload;
+      return {
+        ...state,
+        members: {
+          ...state.members,
+          [p.threadId]: { runId: p.runId, role: p.role, threadId: p.threadId, present: true }
+        }
+      };
+    }
+    case "team.task-created": {
+      const p = event.payload;
+      return {
+        ...state,
+        tasks: {
+          ...state.tasks,
+          [p.taskId]: {
+            runId: p.runId,
+            taskId: p.taskId,
+            title: p.title,
+            state: "pending",
+            assigneeRole: p.assigneeRole,
+            acceptorRole: p.acceptor ?? null,
+            acceptanceRounds: 0,
+            revision: 0,
+            threadId: null,
+            turnId: null,
+            startAttempt: null
+          }
+        }
+      };
+    }
+    case "team.task-changed": {
+      const p = event.payload;
+      const current = state.tasks[p.taskId];
+      if (current === void 0) return state;
+      return {
+        ...state,
+        tasks: {
+          ...state.tasks,
+          [p.taskId]: {
+            ...current,
+            ...p.title === void 0 ? {} : { title: p.title },
+            ...p.state === void 0 ? {} : { state: p.state },
+            ...p.assigneeRole === void 0 ? {} : { assigneeRole: p.assigneeRole },
+            ...p.acceptor === void 0 ? {} : { acceptorRole: p.acceptor },
+            ...p.acceptanceRounds === void 0 ? {} : { acceptanceRounds: p.acceptanceRounds },
+            ...p.revision === void 0 ? {} : { revision: p.revision },
+            ...p.threadId === void 0 ? {} : { threadId: p.threadId },
+            ...p.turnId === void 0 ? {} : { turnId: p.turnId },
+            ...p.startAttempt === void 0 ? {} : { startAttempt: p.startAttempt }
+          }
+        }
+      };
+    }
+    case "thread.message-sent": {
+      const p = event.payload;
+      if (p.carriesRoleBrief !== true || state.briefed.includes(p.threadId)) return state;
+      return { ...state, briefed: [...state.briefed, p.threadId] };
+    }
+    case "team.message-sent": {
+      const p = event.payload;
+      return {
+        ...state,
+        messages: {
+          ...state.messages,
+          [p.messageId]: {
+            runId: p.runId,
+            messageId: p.messageId,
+            fromThreadId: p.fromThreadId,
+            fromRole: p.fromRole,
+            toRole: p.toRole,
+            delivery: p.delivery,
+            wakeQueued: false,
+            delivered: false,
+            readTurnId: null
+          }
+        }
+      };
+    }
+    case "team.message-delivered": {
+      const p = event.payload;
+      const current = state.messages[p.messageId];
+      if (current === void 0) return state;
+      const reallyDelivered = p.deliveredAt !== void 0;
+      return {
+        ...state,
+        messages: {
+          ...state.messages,
+          [p.messageId]: {
+            ...current,
+            wakeQueued: true,
+            delivered: reallyDelivered,
+            // 旧事件没有 readTurnId 这一格。读不出来就是 null,不猜一个出来。
+            readTurnId: reallyDelivered ? p.readTurnId ?? null : current.readTurnId
+          }
+        }
+      };
+    }
+    default:
+      return state;
+  }
+};
+var applyTeamFact = (state, event) => {
+  const payload = ourFact(event);
+  if (payload === null) return applyHostTeamEvent(state, event);
+  switch (factName(payload.name)) {
+    case TEAM_FACTS.run: {
+      const fact = payload.data;
+      return { ...state, runs: { ...state.runs, [fact.runId]: fact } };
+    }
+    case TEAM_FACTS.member: {
+      const fact = payload.data;
+      return { ...state, members: { ...state.members, [fact.threadId]: fact } };
+    }
+    case TEAM_FACTS.task: {
+      const fact = payload.data;
+      return { ...state, tasks: { ...state.tasks, [fact.taskId]: fact } };
+    }
+    case TEAM_FACTS.startAttempt: {
+      const fact = payload.data;
+      return { ...state, startAttempts: { ...state.startAttempts, [fact.threadId]: fact } };
+    }
+    case TEAM_FACTS.briefSent: {
+      const fact = payload.data;
+      if (state.briefed.includes(fact.threadId)) return state;
+      return { ...state, briefed: [...state.briefed, fact.threadId] };
+    }
+    case TEAM_FACTS.messageQueued: {
+      const fact = payload.data;
+      return {
+        ...state,
+        messages: {
+          ...state.messages,
+          [fact.messageId]: { ...fact, wakeQueued: false, delivered: false, readTurnId: null }
+        }
+      };
+    }
+    case TEAM_FACTS.messageWakeQueued: {
+      const fact = payload.data;
+      const current = state.messages[fact.messageId];
+      if (current === void 0) return state;
+      return {
+        ...state,
+        messages: { ...state.messages, [fact.messageId]: { ...current, wakeQueued: true } }
+      };
+    }
+    case TEAM_FACTS.messageDelivered: {
+      const fact = payload.data;
+      const current = state.messages[fact.messageId];
+      if (current === void 0) return state;
+      return {
+        ...state,
+        messages: {
+          ...state.messages,
+          [fact.messageId]: { ...current, delivered: true, readTurnId: fact.readTurnId }
+        }
+      };
+    }
+    // 还没折的事实（交接、等待）先原样跳过:折不了不等于该丢,它们还在日志里,
+    // 补上分支并把 TEAM_STATE_VERSION +1 就能全部重折出来。
+    default:
+      return state;
+  }
+};
+var memberStartPhase = (state, threadId) => {
+  const tasks = Object.values(state.tasks).filter((task) => task.threadId === threadId);
+  const latest = tasks.flatMap((task) => task.startAttempt == null ? [] : [{ task, attempt: task.startAttempt }]).sort((left, right) => right.attempt.acceptedAt.localeCompare(left.attempt.acceptedAt))[0];
+  if (latest !== void 0) {
+    switch (latest.attempt.outcome) {
+      case "pending":
+        return { kind: "pending" };
+      case "in-round":
+        return { kind: "started", turnId: latest.task.turnId ?? null };
+      case "start-failed":
+        return { kind: "failed", reason: latest.attempt.failureReason ?? "\u672A\u8BB0\u5F55\u5931\u8D25\u539F\u56E0" };
+    }
+  }
+  if (tasks.some((task) => task.startAttempt !== void 0)) return { kind: "never-attempted" };
+  const attempt = state.startAttempts[threadId];
+  if (attempt === void 0) return { kind: "never-attempted" };
+  return attempt.outcome;
+};
+var inboxFor = (state, role, runId) => Object.values(state.messages).filter(
+  (m) => m.toRole === role && !m.delivered && (runId === void 0 || m.runId === runId)
+);
+
+// src/view.ts
+var OPEN_STATES = /* @__PURE__ */ new Set(["pending", "ready", "in-progress", "awaiting-acceptance", "blocked"]);
+var memberLine = (state, threadId) => {
+  const member = state.members[threadId];
+  if (member === void 0) return threadId;
+  const phase = memberStartPhase(state, threadId);
+  const phaseText = phase.kind === "never-attempted" ? "\u8D77\u8F6E\u65E0\u8BB0\u5F55" : phase.kind === "pending" ? "\u53D7\u7406\u4E86,\u8FD8\u6CA1\u8D77\u6765" : phase.kind === "started" ? phase.turnId === null ? "\u5DF2\u8D77\u8F6E" : `\u5DF2\u8D77\u8F6E (${phase.turnId})` : `\u8D77\u4E0D\u6765: ${phase.reason}`;
+  const inbox = inboxFor(state, member.role, member.runId).length;
+  const inboxText = inbox === 0 ? "" : `  \u4FE1\u7BB1 ${inbox} \u5C01\u672A\u53D6`;
+  return `${member.present ? "" : "[\u5DF2\u79BB\u573A] "}${member.role}  ${phaseText}${inboxText}`;
+};
+var taskLines = (state, runId) => {
+  const open = Object.values(state.tasks).filter(
+    (task) => OPEN_STATES.has(task.state) && (runId === null || task.runId === runId)
+  );
+  if (open.length === 0) return ["\uFF08\u6CA1\u6709\u5F00\u7740\u7684\u5361\uFF09"];
+  return open.slice().sort((a, b) => a.state.localeCompare(b.state) || a.title.localeCompare(b.title)).map((task) => {
+    const who = task.assigneeRole ?? "\u6CA1\u6D3E\u4EBA";
+    const rounds = task.acceptanceRounds === 0 ? "" : `  \u5DF2\u9A73\u56DE ${task.acceptanceRounds} \u8F6E`;
+    const acceptor = task.state === "awaiting-acceptance" && task.acceptorRole !== null ? `  \u7B49 ${task.acceptorRole} \u9A8C\u6536` : "";
+    return `[${task.state}] ${task.title}  \u2014\u2014 ${who}${acceptor}${rounds}`;
+  });
+};
+var renderBoard = (state, runId) => {
+  const members = Object.keys(state.members).filter((threadId) => runId === null || state.members[threadId]?.runId === runId).sort().map((threadId) => `  ${memberLine(state, threadId)}`);
+  const lines = [
+    "\u6210\u5458",
+    ...members.length === 0 ? ["  \uFF08\u6CA1\u6709\u6210\u5458\uFF09"] : members,
+    "",
+    "\u5F00\u7740\u7684\u5361",
+    ...taskLines(state, runId).map((line) => `  ${line}`)
+  ];
+  return lines.join("\n");
+};
+var renderInbox = (state, role, runId) => {
+  const entries = inboxFor(state, role, runId);
+  if (entries.length === 0) return `${role} \u7684\u4FE1\u7BB1\u662F\u7A7A\u7684\u3002`;
+  return [
+    `${role} \u7684\u4FE1\u7BB1,${entries.length} \u5C01\u672A\u53D6:`,
+    ...entries.map((entry) => {
+      const from = entry.fromRole ?? `${entry.fromThreadId.slice(0, 8)}\u2026`;
+      const wake = entry.wakeQueued ? "\uFF08\u5DF2\u6392\u53EB\u9192\uFF09" : "\uFF08\u53EA\u8FDB\u4FE1\u7BB1\uFF09";
+      return `  \u6765\u81EA ${from}  ${entry.delivery}${wake}`;
+    })
+  ].join("\n");
+};
+
+// src/index.ts
+var index_default = {
+  id: "teams",
+  apiVersion: 1,
+  activate: async (ctx) => {
+    const board = ctx.derivedState({
+      key: "board",
+      version: TEAM_STATE_VERSION,
+      events: [...TEAM_FOLDED_EVENTS],
+      init: emptyTeamState,
+      apply: applyTeamFact
+    });
+    ctx.reactor({
+      name: "teams:dispatch",
+      events: [
+        "team.task-changed",
+        "team.run-state-changed",
+        "team.member-thread-attached",
+        "team.updated",
+        "thread.session-set",
+        "thread.turn-intent-transitioned",
+        "thread.turn-queue-paused"
+      ],
+      handle: async (event) => {
+        const payload = event.payload;
+        switch (event.type) {
+          case "team.task-changed":
+            if ((payload.state === void 0 || payload.state === "ready" || payload.state === "done" || payload.state === "failed" || payload.state === "cancelled" || payload.state === "awaiting-acceptance") && payload.runId !== void 0) {
+              await enqueueReadyTasks(ctx, { runId: payload.runId });
+            }
+            return;
+          case "team.run-state-changed":
+            if (payload.state !== "running" || payload.runId === void 0) return;
+            if (payload.turnConsumption !== void 0 || payload.attention !== void 0 || payload.wakeCursors !== void 0 || payload.briefedRoles !== void 0 || payload.briefedThreads !== void 0)
+              return;
+            await enqueueReadyTasks(ctx, { runId: payload.runId });
+            return;
+          case "team.member-thread-attached":
+            if (payload.runId !== void 0) await enqueueReadyTasks(ctx, { runId: payload.runId });
+            return;
+          case "team.updated":
+            if (payload.teamId !== void 0)
+              await enqueueReadyTasks(ctx, { teamId: payload.teamId });
+            return;
+          case "thread.session-set": {
+            const status = payload.session?.status;
+            if (payload.threadId !== void 0 && status !== void 0 && status !== "starting" && status !== "running") {
+              await enqueueReadyTasks(ctx, { threadId: payload.threadId });
+            }
+            return;
+          }
+          case "thread.turn-intent-transitioned":
+            if (payload.threadId !== void 0 && (payload.status === "completed" || payload.status === "interrupted" || payload.status === "failed" || payload.status === "cancelled" || payload.status === "abandoned")) {
+              await enqueueReadyTasks(ctx, { threadId: payload.threadId });
+            }
+            return;
+          case "thread.turn-queue-paused":
+            if (payload.paused === false && payload.threadId !== void 0) {
+              await enqueueReadyTasks(ctx, { threadId: payload.threadId });
+            }
+            return;
+        }
+      }
+    });
+    ctx.toolkit({
+      name: "teams",
+      tools: [
+        {
+          name: "board",
+          description: "Read the team board: who is on the roster, what each member is doing, and every open card.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              runId: { type: "string", description: "Only this run. Omit for every run." }
+            },
+            additionalProperties: false
+          },
+          handle: async (input) => ({
+            text: renderBoard(await board.get(), input.runId ?? null)
+          })
+        },
+        {
+          name: "inbox",
+          description: "Read one role's unread team messages.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              role: { type: "string" },
+              runId: { type: "string", description: "Only this run. Omit for every run." }
+            },
+            required: ["role"],
+            additionalProperties: false
+          },
+          handle: async (input) => ({
+            text: renderInbox(
+              await board.get(),
+              input.role,
+              input.runId
+            )
+          })
+        }
+      ]
+    });
+    await enqueueReadyTasks(ctx);
+    ctx.log.info("teams plugin active", { facts: Object.keys(TEAM_FACTS).length });
+  }
+};
+export {
+  index_default as default
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ycodium-ai/plugin-teams",
+  "version": "0.1.1",
+  "description": "Teams for Ycodium: the board, the roster, the mailbox, and who gets sent work.",
+  "keywords": [
+    "teams",
+    "ycodium",
+    "ycodium-plugin"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.103",
+    "effect": "4.0.0-beta.103",
+    "esbuild": "0.28.1",
+    "vite-plus": "0.2.2",
+    "ycodium-plugin-api": "0.0.35"
+  },
+  "ycodium": {
+    "plugin": "./dist/index.js",
+    "displayName": "Teams",
+    "icon": "users",
+    "permissions": [
+      {
+        "kind": "teams.dispatch"
+      }
+    ]
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsgo --noEmit",
+    "test": "vp test run"
+  }
+}