@workser/cli 0.2.2 → 0.2.3

package/dist/index.js

@@ -4090,26 +4090,70 @@ The user can configure **roles** \u2014 named specialists each backed by a local
 (e.g. \`qa\` \u2192 codex, \`designer\` \u2192 claude_code).
 
 \`\`\`
-workser agent list                  # main agent + configured roles (+ which are runnable)
-workser agent run <role> "<task>"   # delegate a focused subtask (runs isolated)
+workser agent list                  # main agent + configured roles + which agents are connected
+workser agent run <role> "<task>"   # delegate to a CONFIGURED role (runs isolated)
+workser agent spawn <agent> "<task>" [--role <label>] [--instructions <text>] [--model <model>]
+                                     # spin up a TEMPORARY teammate on any connected agent CLI
 workser agent main                  # show the configured main agent
 \`\`\`
 
 ## How to use it
 
-Run \`workser agent list --json\` first \u2014 it tells you which roles exist **and** which
-are actually runnable on this machine. Delegating to a role that isn't installed just
-fails.
+Run \`workser agent list --json\` first \u2014 it tells you which roles exist, which are
+actually runnable on this machine, and which agent CLIs are connected at all
+(\`spawnable\`). Delegating to a role that isn't installed, or spawning an agent that
+isn't connected, just fails.
+
+\`workser agent run <role> "<task>" --json\` runs a **configured** role as an isolated
+local subagent and returns \`{role, agent, output, exitCode}\`.
+
+\`workser agent spawn <agent> "<task>" --json\` does the same thing without a
+pre-configured role \u2014 \`<agent>\` is one of \`claude_code|codex|kimi|opencode|grok\`, any
+of which can be connected on this machine. Use it to fan work out in parallel for
+one-off work with no matching role: e.g. spawn \`codex\` to research a topic while you
+keep working, or run a second \`claude_code\` instance on a different part of the same
+task. \`--instructions\` sets that teammate's system prompt for this one run \u2014 give it
+real scope, not just a repeat of the task.
+
+- Hand off focused subtasks \u2014 review this diff, design this screen, research this API \u2014
+  to keep your own context lean and get a specialized second perspective.
+- **A non-zero \`exitCode\` means the run failed.** Surface that; don't quietly treat
+  empty output as success.
+- The subagent doesn't share your context, configured role or spawned. Put everything
+  it needs in the task string (and \`--instructions\` for a spawn); it cannot see the
+  conversation you're in.
+- Never give a subagent \u2014 configured or spawned \u2014 a task that tells it to delegate or
+  spawn further. It has no supervision loop to stop a runaway chain.
+`
+  },
+  {
+    topic: "search",
+    title: "Web search",
+    summary: "Google-grounded web search, run server-side \u2014 the API key never reaches you.",
+    commands: ["search"],
+    source: "skills/workser/reference/search.md",
+    body: `# Web search \u2014 ask the internet, not just the model
 
-\`workser agent run <role> "<task>" --json\` runs the role as an **isolated local
-subagent** with its own context and returns \`{role, agent, output, exitCode}\`.
+\`\`\`
+workser search "<query>" [-n, --max-results <n>]   # Google-grounded web search
+\`\`\`
 
-- Hand off focused subtasks \u2014 review this diff, design this screen \u2014 to keep your own
-  context lean and get a specialized second perspective.
-- **A non-zero \`exitCode\` means the role's run failed.** Surface that; don't quietly
-  treat empty output as success.
-- The subagent doesn't share your context. Put everything it needs in the task
-  string; it cannot see the conversation you're in.
+## Why this exists
+
+A local agent can drive a browser, but it can't "search the web" without a URL
+already in hand \u2014 \`browser\` automation needs somewhere to point. This runs a
+real, grounded Google search server-side (core-api holds the API key; it never
+reaches the daemon, the CLI, or you) and returns a synthesized answer plus the
+source links behind it.
+
+## Using it well
+
+- Prefer this over guessing or asking the user when you need current facts,
+  prices, docs for a library, or anything time-sensitive.
+- The \`answer\` is a synthesized summary \u2014 the \`results\` list is the sources it
+  drew from. Cite or open one of those links if the user needs to verify the
+  claim themselves.
+- Not project-scoped: it's a general research tool, not tied to a project's data.
 `
   },
   {
@@ -5432,6 +5476,7 @@ function maskToken(token) {
 
 // src/commands/agent.ts
 var import_picocolors14 = __toESM(require_picocolors(), 1);
+var SPAWNABLE_AGENTS = ["claude_code", "codex", "kimi", "opencode", "grok"];
 function registerAgent(program3) {
   const agent = program3.command("agent").description("Delegate focused subtasks to your configured agent roles (each runs isolated)");
   agent.command("list").description("List the main agent (+ backup) and the configured subagents").action(
@@ -5448,9 +5493,19 @@ function registerAgent(program3) {
           );
         }
         const roles = cfg?.roles ?? [];
-        if (!roles.length) return line(import_picocolors14.default.dim("No subagents configured. Add them in the Workser Orbit Agents screen."));
-        line(import_picocolors14.default.bold("subagents:"));
-        for (const r of roles) line("  " + formatRole(r));
+        if (!roles.length) {
+          line(import_picocolors14.default.dim("No subagents configured. Add them in the Workser Orbit Agents screen."));
+        } else {
+          line(import_picocolors14.default.bold("subagents:"));
+          for (const r of roles) line("  " + formatRole(r));
+        }
+        const detected = cfg?.detected ?? [];
+        const spawnable = detected.filter(
+          (d) => d?.installed && d?.authed !== false
+        );
+        line(
+          import_picocolors14.default.bold("spawnable (workser agent spawn <agent>):") + " " + (spawnable.length ? spawnable.map((d) => toContractId(d.id)).join(", ") : import_picocolors14.default.dim("none connected"))
+        );
       });
     })
   );
@@ -5484,6 +5539,38 @@ function registerAgent(program3) {
       if (exitCode !== 0) process.exitCode = exitCode;
     })
   );
+  agent.command("spawn <agent> <task...>").description(
+    `Spin up a TEMPORARY teammate on any connected agent CLI (not a saved role) for a one-off task. <agent>: ${SPAWNABLE_AGENTS.join("|")}`
+  ).option("--role <label>", "display label for this run (default: <agent>)").option(
+    "--instructions <text>",
+    "system prompt for this one run \u2014 this teammate's expertise/scope"
+  ).option("--model <model>", "model override for the backing CLI").option("--effort <level>", "reasoning effort, where the backing CLI supports it").action(
+    action(async ({ ctx, args, opts }) => {
+      const spawnAgent = args[0];
+      const task = args[1].join(" ");
+      const res = await api(ctx, "/v1/agents/run", {
+        body: {
+          agent: spawnAgent,
+          task,
+          role: opts.role,
+          instructions: opts.instructions,
+          model: opts.model,
+          effort: opts.effort
+        }
+      });
+      const exitCode = res?.exitCode ?? 0;
+      ok(res, () => {
+        if (res?.output) line(res.output);
+        if (exitCode !== 0) {
+          warn(`Spawned ${spawnAgent} exited with code ${exitCode}.`);
+        }
+      });
+      if (exitCode !== 0) process.exitCode = exitCode;
+    })
+  );
+}
+function toContractId(id) {
+  return id === "claude" ? "claude_code" : id;
 }
 function formatRole(r) {
   const label = import_picocolors14.default.yellow(r.role);
@@ -6118,9 +6205,32 @@ function extract(response) {
   return String(response);
 }
 
+// src/commands/search.ts
+var import_picocolors23 = __toESM(require_picocolors(), 1);
+function registerSearch(program3) {
+  program3.command("search <query>").description("Search the web (Google-grounded, server-side)").option("-n, --max-results <n>", "max results", "5").action(
+    action(async ({ ctx, args, opts }) => {
+      const res = await api(ctx, "/v1/search", {
+        query: { q: args[0], maxResults: opts.maxResults }
+      });
+      ok(res, () => {
+        if (res?.answer) {
+          line(res.answer);
+          line("");
+        }
+        const results = res?.results ?? [];
+        if (!results.length) return line(import_picocolors23.default.dim("No results."));
+        for (const r of results) {
+          line(`${r.title || import_picocolors23.default.dim("(untitled)")}  ${import_picocolors23.default.dim(r.url)}`);
+        }
+      });
+    })
+  );
+}
+
 // src/index.ts
 var pkg = {
-  version: true ? "0.2.2" : "0.0.0-dev"
+  version: true ? "0.2.3" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -6161,4 +6271,5 @@ registerBusiness(program2);
 registerArtifact(program2);
 registerImage(program2);
 registerAsk(program2);
+registerSearch(program2);
 program2.parseAsync(process.argv).catch((e) => fail(e));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/reference/roles.md

@@ -11,23 +11,37 @@ The user can configure **roles** — named specialists each backed by a local CL
 (e.g. `qa` → codex, `designer` → claude_code).
 
 ```
-workser agent list                  # main agent + configured roles (+ which are runnable)
-workser agent run <role> "<task>"   # delegate a focused subtask (runs isolated)
+workser agent list                  # main agent + configured roles + which agents are connected
+workser agent run <role> "<task>"   # delegate to a CONFIGURED role (runs isolated)
+workser agent spawn <agent> "<task>" [--role <label>] [--instructions <text>] [--model <model>]
+                                     # spin up a TEMPORARY teammate on any connected agent CLI
 workser agent main                  # show the configured main agent
 ```
 
 ## How to use it
 
-Run `workser agent list --json` first — it tells you which roles exist **and** which
-are actually runnable on this machine. Delegating to a role that isn't installed just
-fails.
+Run `workser agent list --json` first — it tells you which roles exist, which are
+actually runnable on this machine, and which agent CLIs are connected at all
+(`spawnable`). Delegating to a role that isn't installed, or spawning an agent that
+isn't connected, just fails.
 
-`workser agent run <role> "<task>" --json` runs the role as an **isolated local
-subagent** with its own context and returns `{role, agent, output, exitCode}`.
+`workser agent run <role> "<task>" --json` runs a **configured** role as an isolated
+local subagent and returns `{role, agent, output, exitCode}`.
 
-- Hand off focused subtasks — review this diff, design this screen — to keep your own
-  context lean and get a specialized second perspective.
-- **A non-zero `exitCode` means the role's run failed.** Surface that; don't quietly
-  treat empty output as success.
-- The subagent doesn't share your context. Put everything it needs in the task
-  string; it cannot see the conversation you're in.
+`workser agent spawn <agent> "<task>" --json` does the same thing without a
+pre-configured role — `<agent>` is one of `claude_code|codex|kimi|opencode|grok`, any
+of which can be connected on this machine. Use it to fan work out in parallel for
+one-off work with no matching role: e.g. spawn `codex` to research a topic while you
+keep working, or run a second `claude_code` instance on a different part of the same
+task. `--instructions` sets that teammate's system prompt for this one run — give it
+real scope, not just a repeat of the task.
+
+- Hand off focused subtasks — review this diff, design this screen, research this API —
+  to keep your own context lean and get a specialized second perspective.
+- **A non-zero `exitCode` means the run failed.** Surface that; don't quietly treat
+  empty output as success.
+- The subagent doesn't share your context, configured role or spawned. Put everything
+  it needs in the task string (and `--instructions` for a spawn); it cannot see the
+  conversation you're in.
+- Never give a subagent — configured or spawned — a task that tells it to delegate or
+  spawn further. It has no supervision loop to stop a runaway chain.

package/skills/workser/reference/search.md

@@ -0,0 +1,29 @@
+---
+topic: search
+title: Web search
+summary: Google-grounded web search, run server-side — the API key never reaches you.
+commands: [search]
+---
+
+# Web search — ask the internet, not just the model
+
+```
+workser search "<query>" [-n, --max-results <n>]   # Google-grounded web search
+```
+
+## Why this exists
+
+A local agent can drive a browser, but it can't "search the web" without a URL
+already in hand — `browser` automation needs somewhere to point. This runs a
+real, grounded Google search server-side (core-api holds the API key; it never
+reaches the daemon, the CLI, or you) and returns a synthesized answer plus the
+source links behind it.
+
+## Using it well
+
+- Prefer this over guessing or asking the user when you need current facts,
+  prices, docs for a library, or anything time-sensitive.
+- The `answer` is a synthesized summary — the `results` list is the sources it
+  drew from. Cite or open one of those links if the user needs to verify the
+  claim themselves.
+- Not project-scoped: it's a general research tool, not tied to a project's data.