@dylanpiercey/work 0.2.17 → 0.2.19

package/bin/cli/session.mjs

@@ -0,0 +1,296 @@
+// `work session`: which session this is (an agent's own pane, by
+// WORK_SESSION_ID), its name in the session list, and the workspace's
+// other sessions — starting one, messaging it and waiting on its reply,
+// closing it (server/messages.ts).
+
+/** More sessions than this in one workspace is an agent starting them in
+ * a loop, not a plan: past it, `new` wants --force. */
+const SESSION_CAP = 8;
+
+/** The session a command means: --session's, else this pane's own. */
+function sessionId(ctx) {
+  const id = ctx.flag("--session") || process.env.WORK_SESSION_ID;
+  if (!id)
+    ctx.die(
+      "not in a work session (WORK_SESSION_ID is unset): pass --session <id>",
+    );
+  return id;
+}
+
+/** How long `wait` waits by default: inside an agent's own tool limit
+ * (ten minutes for most), so it ends saying who is still working rather
+ * than being killed. */
+const WAIT_S = 540;
+const POLL_MS = 1500;
+
+/** The workspace's sessions with their state, this pane's marked, each
+ * after the session that started it (as the sidebar lists them). */
+async function sessionsOf(ctx, wsId) {
+  const me = process.env.WORK_SESSION_ID;
+  const list = await ctx.api.get(`/api/workspaces/${wsId}/sessions`);
+  const rows = list.map((s) => ({
+    id: s.id,
+    agent: s.agent,
+    title: s.title || null,
+    phase: s.state?.phase || (s.state?.alive ? "idle" : "off"),
+    parent: s.parent_id || null,
+    waitingOn: s.messages?.waitingOn ?? [],
+    queued: s.messages?.queued ?? 0,
+    self: s.id === me,
+  }));
+  const ids = new Set(rows.map((s) => s.id));
+  const out = [];
+  const walk = (s, depth) => {
+    if (out.some((o) => o.id === s.id)) return;
+    out.push({ ...s, depth });
+    for (const c of rows) if (c.parent === s.id) walk(c, depth + 1);
+  };
+  for (const s of rows) if (!s.parent || !ids.has(s.parent)) walk(s, 0);
+  for (const s of rows) walk(s, 0);
+  return out;
+}
+
+function sessionLine(ctx, s) {
+  const notes = [
+    s.waitingOn.length && `waiting on ${s.waitingOn.join(", ")}`,
+    s.queued && `${s.queued} queued for it`,
+    s.self && "this session",
+  ].filter(Boolean);
+  return `${"  ".repeat(s.depth ?? 0)}${ctx.pad(s.id, 9)} ${ctx.pad(s.agent, 10)} ${ctx.pad(s.phase, 8)} ${s.title || ""}${notes.length ? `  (${notes.join("; ")})` : ""}`;
+}
+
+/** A flag's value, "-" (stdin) included, which ctx.flag takes for a
+ * flag of its own. */
+function valueOf(ctx, flag) {
+  const i = ctx.args.indexOf(flag);
+  if (i >= 0 && ctx.args[i + 1] === "-") return "-";
+  return ctx.flag(flag);
+}
+
+/** The text itself, or stdin's for "-": a heredoc carries a long prompt
+ * with quotes in it, which an argument mangles. */
+async function textOf(value) {
+  if (value !== "-") return value;
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").replace(/\n$/, "");
+}
+
+/** What became of a message, for the sender. */
+function sentText(id, r) {
+  const lines = [
+    r.delivered
+      ? `sent to ${id}`
+      : `queued for ${id} (${r.queued}): typed in once it is at its prompt`,
+  ];
+  if (r.wantsReply)
+    lines.push(
+      `Its last message, as that turn ends, comes back to you as a prompt: end your turn to wait for it, or run \`work session wait ${id}\`.`,
+    );
+  return lines.join("\n");
+}
+
+function printReply(r) {
+  const head =
+    r.kind === "reply" ? `${r.label} replied:` : `${r.label}: ${r.text}`;
+  console.log(head);
+  if (r.kind === "reply") console.log(`${r.text}\n`);
+}
+
+export const commands = [
+  {
+    name: "session",
+    summary: "this session and the workspace's others: title, new, send, kill",
+    help: `work session [--json]
+  This session (WORK_SESSION_ID): its id, agent, name, state, and the
+  workspace it is in (id, name, path) — what a link names (/w/<id>/…).
+work session list [id|name] [--json]
+  The workspace's sessions, this one marked.
+work session title "<name>" [--session <id>]
+  Name a session in the session list (empty clears it).
+work session new [--agent <id>] [--title "<name>"] [--prompt "<text>"|-] [--no-reply] [--workspace <id|name>] [--force]
+  Start a session (the default agent unless --agent, any vendor's; "shell"
+  for a terminal) in a tab of its own, where the user watches it, name it,
+  and hand it a first prompt ("-": read it from stdin). Started from
+  another session it is listed under that one, and the prompt is a
+  message from it (below). Past ${SESSION_CAP} sessions in the workspace it wants --force.
+work session send <id> "<text>"|- [--no-reply]
+  Message an agent session: typed in, headed with who it is from, once
+  it is at its prompt — never into a turn under way, a question it asks,
+  or a draft someone is typing. From an agent's session it wants a reply
+  unless --no-reply: the recipient's last message as that turn ends,
+  typed into this session as a prompt of its own. End your turn to wait
+  for it. A file's path says more than its text pasted in.
+work session wait [<id>...] [--timeout <seconds>]
+  Wait for the replies owed to this session (by those sessions, else by
+  any), printing each as it comes; a reply printed here is not typed in
+  too. Exits 124 if some are still working after --timeout (${WAIT_S} s).
+work session kill <id> --yes
+  Close a session and the process in it (whoever waits on its reply is
+  told).`,
+    async run(ctx) {
+      const [verb, ...rest] = ctx.parse([
+        "--agent",
+        "--title",
+        "--prompt",
+        "--workspace",
+        "--session",
+        "--timeout",
+      ]);
+      switch (verb) {
+        case undefined: {
+          const id = sessionId(ctx);
+          const { ws } = await ctx.resolveWorkspace();
+          const me = (await sessionsOf(ctx, ws.id)).find((s) => s.id === id);
+          if (!me) ctx.die(`no session ${id} in ${ws.name}`);
+          const out = {
+            ...me,
+            depth: undefined,
+            workspace: {
+              id: ws.id,
+              name: ws.name,
+              path: ws.path,
+              branch: ws.branch,
+            },
+          };
+          return ctx.out(out, (s) => {
+            console.log(
+              `${s.id}  ${s.agent}  ${s.phase}${s.title ? `  "${s.title}"` : ""}${s.waitingOn.length ? `  (waiting on ${s.waitingOn.join(", ")})` : ""}`,
+            );
+            console.log(
+              `workspace ${s.workspace.name} (${s.workspace.id})  ${s.workspace.path}`,
+            );
+          });
+        }
+        case "list": {
+          const { ws } = await ctx.resolveWorkspace(rest[0]);
+          const list = await sessionsOf(ctx, ws.id);
+          return ctx.out(list, (l) => {
+            if (!l.length) return console.log("no sessions");
+            for (const s of l) console.log(sessionLine(ctx, s));
+          });
+        }
+        case "title": {
+          const id = sessionId(ctx);
+          const title = rest.join(" ");
+          await ctx.api.patch(`/api/sessions/${id}`, { title });
+          return ctx.out({ id, title: title || null }, () =>
+            console.log(
+              title ? `named ${id} "${title}"` : `cleared ${id}'s name`,
+            ),
+          );
+        }
+        case "new": {
+          const { ws } = await ctx.resolveWorkspace(ctx.flag("--workspace"));
+          const existing = await sessionsOf(ctx, ws.id);
+          if (existing.length >= SESSION_CAP && !ctx.has("--force"))
+            ctx.die(
+              `${ws.name} already has ${existing.length} sessions: pass --force to start another`,
+            );
+          const agent = ctx.flag("--agent");
+          const me = process.env.WORK_SESSION_ID;
+          const prompt = await textOf(valueOf(ctx, "--prompt"));
+          const created = await ctx.api.post(
+            `/api/workspaces/${ws.id}/sessions`,
+            { ...(agent ? { agent } : {}), ...(me ? { parent: me } : {}) },
+          );
+          const title = ctx.flag("--title");
+          if (title)
+            await ctx.api.patch(`/api/sessions/${created.id}`, { title });
+          // Sent, the session starts (detached) with it as its first
+          // prompt; otherwise it starts when someone opens it.
+          const sent = prompt
+            ? await ctx.api.post(`/api/sessions/${created.id}/messages`, {
+                text: prompt,
+                ...(me ? { from: me } : {}),
+                reply: !ctx.has("--no-reply"),
+              })
+            : null;
+          const out = {
+            id: created.id,
+            agent: created.agent,
+            title: title || null,
+            workspace: ws.id,
+            parent: created.parent_id ?? null,
+            prompted: !!sent?.delivered,
+            queued: sent?.queued ?? null,
+            wantsReply: !!sent?.wantsReply,
+            href: `/w/${ws.id}?s=${created.id}`,
+          };
+          return ctx.out(out, (s) => {
+            console.log(
+              `started ${s.id} (${s.agent})${s.prompted ? " with its prompt" : ""}: [${s.title || s.agent}](${s.href})`,
+            );
+            if (s.queued)
+              console.log(`its prompt waits to be typed in: ${s.queued}`);
+            if (s.wantsReply)
+              console.log(
+                `Its last message, as that turn ends, comes back to you as a prompt: end your turn to wait for it, or run \`work session wait ${s.id}\`.`,
+              );
+          });
+        }
+        case "send": {
+          const [id, ...words] = rest;
+          const text = await textOf(words.join(" "));
+          if (!id || !text)
+            ctx.die('usage: work session send <id> "<text>"|- [--no-reply]');
+          const me = process.env.WORK_SESSION_ID;
+          const r = await ctx.api.post(`/api/sessions/${id}/messages`, {
+            text,
+            ...(me ? { from: me } : {}),
+            reply: !ctx.has("--no-reply"),
+          });
+          return ctx.out({ id, ...r }, (r) => console.log(sentText(id, r)));
+        }
+        case "wait": {
+          const me = sessionId(ctx);
+          const raw = ctx.flag("--timeout");
+          const seconds = raw === undefined ? WAIT_S : Number(raw);
+          if (!Number.isFinite(seconds) || seconds < 0)
+            ctx.die("--timeout is a number of seconds");
+          const until = Date.now() + seconds * 1000;
+          const body = rest.length ? { from: rest } : {};
+          const replies = [];
+          let owing = [];
+          for (;;) {
+            const r = await ctx.api.post(`/api/sessions/${me}/replies`, body);
+            replies.push(...r.replies);
+            if (!ctx.json) r.replies.forEach(printReply);
+            owing = r.owing;
+            if (!owing.length || Date.now() >= until) break;
+            await new Promise((res) => setTimeout(res, POLL_MS));
+          }
+          if (ctx.json)
+            console.log(JSON.stringify({ replies, owing }, null, 2));
+          else if (!replies.length && !owing.length)
+            console.log(
+              rest.length
+                ? `nothing owed by ${rest.join(", ")}: a reply already typed in is in your prompt`
+                : "no session owes this one a reply",
+            );
+          if (owing.length) {
+            ctx.warn(
+              `still working: ${owing.map((o) => o.label).join(", ")} (wait again, or end your turn: the reply comes as a prompt)`,
+            );
+            process.exitCode = 124;
+          }
+          return;
+        }
+        case "kill": {
+          const [id] = rest;
+          if (!id) ctx.die("usage: work session kill <id> --yes");
+          if (!ctx.yes)
+            ctx.die(
+              `closing ${id} ends the process in it${id === process.env.WORK_SESSION_ID ? " — this session, the one running this command" : ""}: pass --yes`,
+            );
+          await ctx.api.del(`/api/sessions/${id}`);
+          return ctx.out({ id, killed: true }, () =>
+            console.log(`closed ${id}`),
+          );
+        }
+        default:
+          ctx.die(`no \`work session ${verb}\` (see: work help session)`);
+      }
+    },
+  },
+];

package/bin/cli/skill.mjs

@@ -0,0 +1,99 @@
+// `work skill`: the machine's skills — what every agent CLI here can see —
+// as Settings → Skills lists, adds, updates and removes them.
+import { follow } from "./_progress.mjs";
+
+function printList(snap) {
+  const rows = snap.global || [];
+  if (!snap.available)
+    console.log(
+      "the skills CLI is not installed, so skills can be listed but not added (work setup installs it)",
+    );
+  if (!rows.length) return console.log("no skills installed");
+  const w = Math.max(4, ...rows.map((s) => s.id.length));
+  for (const s of rows) {
+    const from = s.source ? `  ${s.source}` : "";
+    const broken = s.broken ? "  (broken link)" : "";
+    console.log(`${s.id.padEnd(w)}${from}${broken}`);
+    if (s.description) console.log(`${"".padEnd(w)}  ${s.description}`);
+  }
+}
+
+/** One skill action through the route Settings uses, its progress (the
+ * skills CLI's own output) on stderr; the machine's skills after it. */
+function act(ctx, body, op) {
+  return follow(ctx, op, () => ctx.api.post("/api/skills", body));
+}
+
+/** @type {Array<{name: string, summary: string, help: string, run: (ctx: any) => Promise<void>}>} */
+export const commands = [
+  {
+    name: "skill",
+    summary: "machine skills: list | add | rm | update",
+    help: `work skill [list]
+  The skills every agent CLI on this machine can see (Settings → Skills):
+  each one's id, where it came from, and what it does.
+work skill add <source> [--skill <name>]
+  Add skills from a source the skills CLI understands (owner/repo, a git
+  URL, a path): every skill it ships, or the one --skill names.
+work skill rm <id>
+  Remove an installed skill.
+work skill update [<id>]
+  Update one skill from its source, or every skill that has one.`,
+    async run(ctx) {
+      const [verb = "list", arg] = ctx.parse(["--skill"]);
+      if (verb === "list") {
+        const snap = await ctx.api.get("/api/skills");
+        return ctx.out(snap.global || [], () => printList(snap));
+      }
+      if (verb === "add") {
+        if (!arg) ctx.die("name the source: work skill add <owner/repo|url>");
+        const skill = ctx.args.includes("--skill")
+          ? ctx.flag("--skill")
+          : undefined;
+        const snap = await act(
+          ctx,
+          { action: "add", source: arg, skill },
+          `skills:${skill ? `${arg}#${skill}` : arg}`,
+        );
+        return ctx.out(snap.global || [], () =>
+          console.log(
+            `added ${skill ?? "the skills of"} ${skill ? "from " : ""}${arg}`,
+          ),
+        );
+      }
+      if (verb === "rm" || verb === "remove") {
+        if (!arg) ctx.die("name the skill: work skill rm <id>");
+        const snap = await act(
+          ctx,
+          { action: "remove", id: arg },
+          `skills:${arg}`,
+        );
+        return ctx.out(snap.global || [], () => console.log(`removed ${arg}`));
+      }
+      if (verb === "update") {
+        let ids = arg ? [arg] : [];
+        if (!arg) {
+          const snap = await ctx.api.get("/api/skills");
+          ids = (snap.global || [])
+            .filter((s) => s.source && s.source !== "local")
+            .map((s) => s.id);
+          if (!ids.length) {
+            ctx.out([], () =>
+              console.log("no skill has a source to update from"),
+            );
+            return;
+          }
+        }
+        let snap = null;
+        for (const id of ids) {
+          process.stderr.write(`  updating ${id}\n`);
+          snap = await act(ctx, { action: "update", id }, `skills:${id}`);
+        }
+        return ctx.out(snap?.global || [], () =>
+          console.log(`updated ${ids.join(", ")}`),
+        );
+      }
+      ctx.die(`no skill verb ${verb} (list, add, rm, update)`);
+    },
+  },
+];

package/bin/cli/stack.mjs

@@ -0,0 +1,51 @@
+// `work stack`: how to stack branches here, with this workspace's branch
+// in place. Kept out of the workspace AGENTS.md, which every session reads
+// whole: stacking is for when the user asks, and the recipe was a quarter
+// of that file.
+
+function recipe(branch) {
+  return `Stacking ${branch}
+
+Stack only when the user asks, or when a change of several hundred lines
+splits into parts each worth merging alone; never a layer per commit.
+
+- The working branch (${branch}) stays the top; cut layers below it, bottom
+  first, as ${branch}-<layer>:
+    gh stack init --base <base> <layers…> ${branch}
+  (after \`gh stack unstack --local\` if a stack exists).
+- Never check a layer out. Edit one by \`git commit --fixup <sha>\` on the
+  top, then:
+    GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash --update-refs origin/<base>
+- \`gh stack sync\` / \`gh stack rebase\` switch branches: run them in topic
+  worktrees only. Leave the local <base> gh-stack keeps as trunk.
+- Merge a layer with \`gh stack merge <pr> --squash\` or on the web
+  (\`gh pr merge\` refuses it), then, on the top:
+    old=$(git rev-parse origin/${branch})
+    git fetch
+    git branch -f <layer> origin/<layer>     # for each remaining layer
+    git branch -D <merged-layer>
+    git rebase --onto origin/${branch} $old
+- Once the top merges: \`gh stack unstack --local\`.
+- Link a layer for review as [<layer>](/w/<id>/review?section=<repo>@<layer>);
+  \`work branches\` lists every layer with its link.`;
+}
+
+export const commands = [
+  {
+    name: "stack",
+    summary: "how to stack branches in this workspace (prints the recipe)",
+    help: `work stack [id|name]
+  Prints how to stack branches with gh-stack here, with the workspace's
+  branch filled in: when to, cutting layers, editing one without checking
+  it out, merging a layer and rebasing the rest.`,
+    async run(ctx) {
+      let branch = "<workspace-branch>";
+      try {
+        if (ctx.positional[0] || process.env.WORK_SESSION_ID) {
+          branch = (await ctx.resolveWorkspace(ctx.positional[0])).ws.branch;
+        }
+      } catch {}
+      ctx.out({ branch, recipe: recipe(branch) }, (d) => console.log(d.recipe));
+    },
+  },
+];

package/bin/cli/status.mjs

@@ -0,0 +1,86 @@
+// `work status`: the machine and the service in one look — how the server
+// runs (its own config, not the unit file's), the agents, language servers
+// and skills, what `work doctor` would say is missing, and the settings
+// changed from their defaults. One request each, side by side.
+import { shown } from "./config.mjs";
+
+export const commands = [
+  {
+    name: "status",
+    summary: "the service, agents, languages, skills and changed settings",
+    help: `work status [--json]
+    one snapshot of this machine's work: version, address and names it
+    answers to, direct connections, data and work root, agents (installed,
+    switched off, the default), language servers, skills, what is missing
+    (work doctor), and the settings changed from their defaults`,
+    async run(ctx) {
+      const [server, settings, agents, lsp, skills, setup] = await Promise.all([
+        ctx.api.get("/api/config"),
+        ctx.api.get("/api/settings/values"),
+        ctx.api.get("/api/settings"),
+        ctx.api.get("/api/lsp"),
+        ctx.api.get("/api/skills"),
+        ctx.api.get("/api/setup"),
+      ]);
+      const snapshot = {
+        version: server.version,
+        server,
+        agents: {
+          default: agents.preferredAgent,
+          enabled: agents.agents,
+          disabled: agents.disabledAgents,
+          installable: (setup.agents || [])
+            .filter((a) => !a.installed)
+            .map((a) => a.id),
+        },
+        languages: {
+          on: lsp.on,
+          installed: lsp.servers.filter((s) => s.installed).map((s) => s.id),
+          off: lsp.servers.filter((s) => !s.enabled).map((s) => s.id),
+        },
+        skills: [...(skills.global || [])].map((s) => s.id ?? s.name ?? s),
+        doctor: { ready: setup.ready, missing: setup.missing },
+        settings: settings.filter((e) => !e.isDefault),
+      };
+      ctx.out(snapshot, (s) => {
+        const sv = s.server;
+        const list = (xs) => (xs.length ? xs.join(", ") : "none");
+        const rows = [
+          ["work", `${s.version} on ${sv.listen}:${sv.port}`],
+          [
+            "names",
+            sv.allowedHosts.length
+              ? `${sv.allowedHosts.join(", ")} (ports as ${sv.portHosts === "dash" ? "<port>-<name>" : "<port>.<name>"})`
+              : "this machine's own",
+          ],
+          ["proxies", list(sv.trustedProxies)],
+          ["direct", sv.rtc.on ? `on, UDP ${sv.rtc.port}` : "off"],
+          ["root", sv.workRoot],
+          ["data", sv.dataDir],
+          [
+            "agents",
+            `${list(s.agents.enabled)}; default ${s.agents.default}${s.agents.disabled.length ? `; off: ${s.agents.disabled.join(", ")}` : ""}`,
+          ],
+          [
+            "languages",
+            `${s.languages.on ? "on" : "off"}; installed: ${list(s.languages.installed)}${s.languages.off.length ? `; off: ${s.languages.off.join(", ")}` : ""}`,
+          ],
+          ["skills", list(s.skills)],
+          [
+            "machine",
+            s.doctor.ready
+              ? "ready"
+              : `not ready: ${list(s.doctor.missing)} (work doctor)`,
+          ],
+          [
+            "settings",
+            s.settings.length
+              ? s.settings.map((e) => `${e.key}=${shown(e.value)}`).join(", ")
+              : "all at their defaults (work config list)",
+          ],
+        ];
+        for (const [k, v] of rows) console.log(`${ctx.pad(k, 10)} ${v}`);
+      });
+    },
+  },
+];