@monster-orange/den 0.4.17 → 0.4.19

package/src/ui/cli/server-agent-ops.ts

@@ -0,0 +1,411 @@
+/**
+ * The server agent's operations (ON-6), on top of the agent ones: what it
+ * is and whether it runs (status), and starting it (start). It is a normal
+ * Den agent in the reserved server scope (shared/agents/server-agent.ts),
+ * id `server`, persona `server`, named "<Product> agent".
+ *
+ * Its runtime: `agents.server_runtime` in user.yml when that one is
+ * installed, else the first installed catalog runtime that carries Den's
+ * tools. Den can tell a runtime is installed, not that it is logged in: a
+ * runtime that isn't asks the person to log in in its own terminal.
+ *
+ * Its model: `agents.server_model` when the runtime offers it, else Sonnet
+ * when the runtime offers Sonnet (DEFAULT_SERVER_MODEL), else the
+ * runtime's own default. Only the runtime's own models are offered.
+ */
+import {
+  AgentError,
+  listAgents,
+  listRuntimes,
+  relaunchAgent,
+  resumeAgent,
+  resumeRefusal,
+  startAgent,
+  type AgentRow,
+  type AgentsResolved,
+  type RuntimeChoice,
+  type Started,
+} from "./agent-ops.js";
+import { readRecord } from "../../shared/agents/records.js";
+import { rotationInfo } from "../../shared/agents/rotation.js";
+import {
+  SERVER_AGENT_ID,
+  SERVER_PERSONA_ID,
+  SERVER_SCOPE,
+  serverAgentName,
+} from "../../shared/agents/server-agent.js";
+import { getRuntime } from "../../shared/agents/runtime.js";
+import {
+  mergeUserConfig,
+  readUserConfig,
+  type UserConfig,
+} from "../../shared/den-config.js";
+import { product } from "../../shared/product.js";
+import { getDistRoot } from "../../shared/paths.js";
+import * as os from "os";
+import * as path from "path";
+
+export interface ServerAgentDeps {
+  /** user.yml's `agents.server_runtime` (the person's choice), if set. */
+  readSetting?: () => string | undefined;
+  /** Save (or, with null, clear) that choice. */
+  saveSetting?: (id: string | null) => void;
+  /** user.yml's `agents.server_model`, if set. */
+  readModel?: () => string | undefined;
+  /** Save (or, with null, clear) it. */
+  saveModel?: (id: string | null) => void;
+  /** A fresh Den: no repo in any workspace yet. */
+  fresh?: () => boolean | Promise<boolean>;
+  /** The product's name for people ("Acme"). */
+  title?: () => string;
+  /** This Den's folder (its distribution root). */
+  root?: () => string;
+}
+
+interface Resolved {
+  readSetting: () => string | undefined;
+  saveSetting: (id: string | null) => void;
+  readModel: () => string | undefined;
+  saveModel: (id: string | null) => void;
+  fresh: () => boolean | Promise<boolean>;
+  title: () => string;
+  root: () => string;
+}
+
+function resolve(s: ServerAgentDeps): Resolved {
+  return {
+    readSetting: s.readSetting ?? readServerRuntimeSetting,
+    saveSetting: s.saveSetting ?? saveServerRuntimeSetting,
+    readModel: s.readModel ?? (() => readAgentsKey("server_model")),
+    saveModel: s.saveModel ?? ((id) => saveAgentsKey("server_model", id)),
+    fresh: s.fresh ?? freshDen,
+    title: s.title ?? (() => product().title),
+    root: s.root ?? getDistRoot,
+  };
+}
+
+/** A string key of user.yml's `agents`, if set. */
+function readAgentsKey(
+  key: "server_runtime" | "server_model",
+): string | undefined {
+  const v = (readUserConfig().agents as Record<string, unknown> | undefined)?.[
+    key
+  ];
+  return typeof v === "string" && v ? v : undefined;
+}
+
+function saveAgentsKey(
+  key: "server_runtime" | "server_model",
+  id: string | null,
+): void {
+  const agents = { ...(readUserConfig().agents ?? {}) } as Record<
+    string,
+    unknown
+  >;
+  if (id === null) delete agents[key];
+  else agents[key] = id;
+  mergeUserConfig({
+    agents: Object.keys(agents).length
+      ? (agents as UserConfig["agents"])
+      : undefined,
+  });
+}
+
+/** user.yml's `agents.server_runtime`. */
+export function readServerRuntimeSetting(): string | undefined {
+  return readAgentsKey("server_runtime");
+}
+
+function saveServerRuntimeSetting(id: string | null): void {
+  saveAgentsKey("server_runtime", id);
+}
+
+/** The server agent's model when the person picked none and its runtime offers it. */
+export const DEFAULT_SERVER_MODEL = "sonnet";
+
+/** The model to run on: the saved one when the runtime offers it, else Sonnet if offered, else none. */
+export function pickModel(
+  models: readonly { id: string }[],
+  saved: string | undefined,
+): string | undefined {
+  if (saved && models.some((m) => m.id === saved)) return saved;
+  return models.some((m) => m.id === DEFAULT_SERVER_MODEL)
+    ? DEFAULT_SERVER_MODEL
+    : undefined;
+}
+
+/** No repo in any workspace yet (workspaces.yml), or no workspaces file. */
+export async function freshDen(): Promise<boolean> {
+  // Imported when asked, like loadAgentWorkspaces: the CLI starts light.
+  const ws = await import("../../shared/environment-manager/workspaces.js");
+  let file: ReturnType<typeof ws.readWorkspacesFile>;
+  try {
+    file = ws.readWorkspacesFile();
+  } catch {
+    return true;
+  }
+  return Object.values(file.workspaces ?? {}).every(
+    (w) => Object.keys(w?.services ?? {}).length === 0,
+  );
+}
+
+/** A runtime the server agent can run on: installed, with Den's tools. */
+function usable(r: RuntimeChoice): boolean {
+  return r.available && r.denTools === true;
+}
+
+/** How to install a catalog runtime, when its catalog says (npm). */
+function installHint(id: string): string | undefined {
+  const pkg = getRuntime(id)?.catalog?.version?.identity?.package;
+  return pkg ? `npm i -g ${pkg}` : undefined;
+}
+
+export interface ServerAgentStatus {
+  /** "<Product> agent". */
+  name: string;
+  id: string;
+  /** The reserved scope it lives in (never a workspace). */
+  scope: string;
+  persona: string;
+  /** No repo in any workspace yet: the first page is this agent. */
+  fresh: boolean;
+  /** The person's choice (user.yml agents.server_runtime), if any. */
+  setting?: string;
+  /** The runtime it runs (or would run) on, or null when none can. */
+  runtime: { id: string; label?: string } | null;
+  /** The runtime it is running on now (its record's), when it runs. */
+  runningRuntime?: string;
+  /** The model it runs (or would run) on, when its runtime names models. */
+  model?: string;
+  /** The runtime's own models, for the picker. */
+  models: { id: string; label?: string }[];
+  /** Every catalog runtime, and whether the server agent can use it. */
+  runtimes: {
+    id: string;
+    label?: string;
+    available: boolean;
+    denTools: boolean;
+    usable: boolean;
+    install?: string;
+  }[];
+  /** none (never started), running, stopping, stopped, exited, interrupted. */
+  state: string;
+  /** Its session, when it has one to open. */
+  sessionId?: string;
+  /** The way without any agent (Humans can do everything agents can). */
+  manual: string[];
+}
+
+/**
+ * The manual path for this Den, which already exists: from its folder,
+ * add a repo and start it, with the Den's own command (`./bin/<cli>`, as
+ * the install skill runs it). `dir` is the Den's folder, shown `~/…`
+ * inside `home`.
+ */
+/** A folder as the person reads it: `~/…` inside `home`. */
+function shownDir(dir: string, home?: string): string {
+  const rel = home ? path.relative(home, dir) : "";
+  if (home && rel === "") return "~";
+  return home && rel && !rel.startsWith("..") && !path.isAbsolute(rel)
+    ? `~/${rel}`
+    : dir;
+}
+
+export function manualPath(cli: string, dir: string, home?: string): string[] {
+  const shown = shownDir(dir, home);
+  const cd = /^[A-Za-z0-9_./~+-]+$/.test(shown)
+    ? shown
+    : `'${shown.replace(/'/g, `'\\''`)}'`;
+  return [`cd ${cd}`, `./bin/${cli} repo add <path>`, `./bin/${cli} up`];
+}
+
+/** The runtime to run on: the person's choice when usable, else the first. */
+export function pickRuntime(
+  rows: RuntimeChoice[],
+  setting: string | undefined,
+): RuntimeChoice | null {
+  const chosen = setting ? rows.find((r) => r.id === setting) : undefined;
+  if (chosen && usable(chosen)) return chosen;
+  return rows.find(usable) ?? null;
+}
+
+export async function serverAgentStatus(
+  d: AgentsResolved,
+  s: ServerAgentDeps = {},
+): Promise<ServerAgentStatus> {
+  const r = resolve(s);
+  const rows = (await listRuntimes(d)).filter((x) => x.denTools !== undefined);
+  const setting = r.readSetting();
+  const rt = pickRuntime(rows, setting);
+  const models = (rt?.models ?? []).map((m) => ({
+    id: m.id,
+    ...(m.label ? { label: m.label } : {}),
+  }));
+  const model = pickModel(models, r.readModel());
+  let row: AgentRow | undefined;
+  try {
+    row = (await listAgents(d, SERVER_SCOPE, { startHost: false })).find(
+      (x) => x.agent === SERVER_AGENT_ID,
+    );
+  } catch {
+    row = undefined;
+  }
+  return {
+    name: serverAgentName(r.title()),
+    id: SERVER_AGENT_ID,
+    scope: SERVER_SCOPE,
+    persona: SERVER_PERSONA_ID,
+    fresh: await r.fresh(),
+    ...(setting ? { setting } : {}),
+    runtime: rt
+      ? { id: rt.id, ...(rt.label ? { label: rt.label } : {}) }
+      : null,
+    ...(row &&
+    (row.state === "running" || row.state === "stopping") &&
+    row.runtime
+      ? { runningRuntime: row.runtime }
+      : {}),
+    ...(model ? { model } : {}),
+    models,
+    runtimes: rows.map((x) => {
+      const install = x.available ? undefined : installHint(x.id);
+      return {
+        id: x.id,
+        ...(x.label ? { label: x.label } : {}),
+        available: x.available,
+        denTools: x.denTools === true,
+        usable: usable(x),
+        ...(install ? { install } : {}),
+      };
+    }),
+    state: row?.state ?? "none",
+    ...(row?.session ? { sessionId: row.session.ref.id } : {}),
+    manual: manualPath(d.cli, r.root(), d.env.HOME ?? os.homedir()),
+  };
+}
+
+/**
+ * The first thing the server agent hears on a fresh Den: it greets and
+ * asks where the repos are in its first turn, with the folder above the
+ * Den's as the default (`reposDefault`), so the person can just say yes.
+ */
+export function onboardingPrompt(title: string, reposDefault?: string): string {
+  const ask = reposDefault
+    ? `"Let's set up ${title}. Where are your repos? I'll look in ${reposDefault} unless you name another folder."`
+    : `"Let's set up ${title}. Where are your repos?"`;
+  return (
+    `Set up ${title} with me. Start with onboard_status, then say ` +
+    `${ask} and wait for my answer.`
+  );
+}
+
+export interface ServerAgentStarted {
+  /** started, resumed, relaunched, or running (it already was). */
+  how: "started" | "resumed" | "relaunched" | "running";
+  sessionId: string;
+  runtime: string;
+  warnings: string[];
+}
+
+/**
+ * Start the server agent, or bring it back: running, it is left as it is;
+ * stopped with a conversation to continue, it resumes (AG-14); rotated, it
+ * relaunches from its handoff; else it starts fresh, and on a fresh Den
+ * with the onboarding prompt.
+ */
+export async function startServerAgent(
+  d: AgentsResolved,
+  req: { runtime?: string } = {},
+  s: ServerAgentDeps = {},
+): Promise<ServerAgentStarted> {
+  const r = resolve(s);
+  const status = await serverAgentStatus(d, s);
+  if (
+    (status.state === "running" || status.state === "stopping") &&
+    status.sessionId
+  )
+    return {
+      how: "running",
+      sessionId: status.sessionId,
+      runtime: readRecord(d.stateDir(), SERVER_AGENT_ID)?.runtime ?? "",
+      warnings: [],
+    };
+  const rec = readRecord(d.stateDir(), SERVER_AGENT_ID);
+  const runtime = req.runtime ?? status.runtime?.id;
+  const model =
+    runtime === status.runtime?.id
+      ? status.model
+      : pickModel(getRuntime(runtime ?? "")?.models?.() ?? [], r.readModel());
+  if (!runtime)
+    throw new AgentError(
+      "no runtime can run the server agent: install one from the runtime catalog",
+      { status: 503, code: "no_runtime", hints: status.manual },
+    );
+  const done = (how: ServerAgentStarted["how"], st: Started) => ({
+    how,
+    sessionId: st.info.ref.id,
+    runtime: st.rec.runtime,
+    warnings: st.warnings,
+  });
+  // The same runtime and model: continue its conversation. Another model
+  // picked since: a fresh start on it.
+  if (
+    rec &&
+    rec.workspace === SERVER_SCOPE &&
+    rec.runtime === runtime &&
+    rec.model === model
+  ) {
+    if (rotationInfo(d.stateDir(), rec)?.ready)
+      return done("relaunched", await relaunchAgent(d, rec.id));
+    if (resumeRefusal(rec) === null)
+      return done("resumed", await resumeAgent(d, rec.id, SERVER_SCOPE));
+  }
+  const title = r.title();
+  const st = await startAgent(
+    d,
+    {
+      workspace: SERVER_SCOPE,
+      persona: SERVER_PERSONA_ID,
+      id: SERVER_AGENT_ID,
+      runtime,
+      ...(model ? { model } : {}),
+      name: serverAgentName(title),
+    },
+    status.fresh
+      ? {
+          firstPrompt: onboardingPrompt(
+            title,
+            shownDir(path.dirname(r.root()), d.env.HOME ?? os.homedir()),
+          ),
+        }
+      : {},
+  );
+  return done("started", st);
+}
+
+/** Save the person's model choice; null clears it. Only the runtime's own. */
+export async function setServerModel(
+  d: AgentsResolved,
+  id: string | null,
+  s: ServerAgentDeps = {},
+): Promise<void> {
+  if (id !== null) {
+    const st = await serverAgentStatus(d, s);
+    if (!st.models.some((m) => m.id === id))
+      throw new AgentError(
+        `${st.runtime?.label ?? st.runtime?.id ?? "this runtime"} has no model "${id}"`,
+        { usage: true },
+      );
+  }
+  resolve(s).saveModel(id);
+}
+
+/** Save the person's runtime choice; null clears it. */
+export function setServerRuntime(
+  id: string | null,
+  s: ServerAgentDeps = {},
+): void {
+  if (id !== null && !getRuntime(id))
+    throw new AgentError(`no runtime "${id}"`, { usage: true });
+  resolve(s).saveSetting(id);
+}

package/src/ui/mcp/server.ts

@@ -6,6 +6,7 @@
  * stdout carries the protocol only: diagnostics go to stderr.
  */
 import { z } from "zod";
+import { isServerScope } from "../../shared/agents/server-agent.js";
 import { randomUUID } from "crypto";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -56,7 +57,9 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
   const log = opts.log ?? ((l: string) => process.stderr.write(`${l}\n`));
   // Scoped, each workspace tool is registered pinned (MCP-2.2): "this
   // workspace only", and no workspace parameter unless there are grants.
-  const tools = toolsFor(opts.cfg, opts.scope);
+  // ON-6: the server agent's scope is the whole Den (its tools unpinned).
+  const toolScope = workspaceScope(opts.scope);
+  const tools = toolsFor(opts.cfg, toolScope);
   const server = new McpServer(
     { name: p.name, version: engineVersion() ?? "0.0.0" },
     {
@@ -67,13 +70,17 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
           ? `Actions enabled: ${opts.cfg.actions.join(", ")}.`
           : "The org has enabled no actions (mcp.actions).") +
         ` The ${approvalsState(opts.cfg)}.` +
-        (opts.scope
-          ? ` Scoped to workspace "${opts.scope.workspace}" as ${opts.scope.actor}: ` +
-            "a call naming another workspace is refused, and lists show this one only, " +
-            "each with a `scope` block saying how much is hidden. org_summary has " +
-            "every workspace and repo (names and status counts), the graph, the " +
-            "edge and the environments: start there for the whole picture."
-          : " org_summary has the whole org at a glance: start there."),
+        (opts.scope && !toolScope
+          ? ` You are this ${p.title}'s own server agent (${opts.scope.actor}): the whole ${p.title}, ` +
+            "no workspace. Each write is held until the person allows it in the browser. " +
+            "onboard_status says what is set up: start there."
+          : opts.scope
+            ? ` Scoped to workspace "${opts.scope.workspace}" as ${opts.scope.actor}: ` +
+              "a call naming another workspace is refused, and lists show this one only, " +
+              "each with a `scope` block saying how much is hidden. org_summary has " +
+              "every workspace and repo (names and status counts), the graph, the " +
+              "edge and the environments: start there for the whole picture."
+            : " org_summary has the whole org at a glance: start there."),
     },
   );
 
@@ -99,7 +106,7 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
     api,
     cfg: opts.cfg,
     cli: opts.cli,
-    ...(opts.scope ? { scope: opts.scope } : {}),
+    ...(toolScope ? { scope: toolScope } : {}),
   };
 
   for (const t of tools) {
@@ -138,6 +145,15 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
   return server;
 }
 
+/**
+ * The scope the tools are pinned to: a workspace's, or none for the
+ * server agent's (ON-6), whose calls still carry its actor and scope in
+ * the audit headers.
+ */
+function workspaceScope(scope: McpScope | undefined): McpScope | undefined {
+  return scope && !isServerScope(scope.workspace) ? scope : undefined;
+}
+
 /** The audit fields a scope adds to every call's headers (none unscoped). */
 function scopeInfo(scope: McpScope | undefined): {
   agent?: string;
@@ -260,7 +276,8 @@ export async function runOneShot(
 ): Promise<number> {
   const out = opts.out ?? ((t: string) => process.stdout.write(t));
   // The tools exactly as the stdio server registers them: pinned when scoped.
-  const tools = toolsFor(opts.cfg, opts.scope);
+  const toolScope = workspaceScope(opts.scope);
+  const tools = toolsFor(opts.cfg, toolScope);
   if (shot.kind === "list") {
     const names = tools.map((t) => t.name);
     out(names.length ? `${names.join("\n")}\n` : "");
@@ -274,7 +291,7 @@ export async function runOneShot(
     api: opts.api,
     cfg: opts.cfg,
     cli: opts.cli,
-    ...(opts.scope ? { scope: opts.scope } : {}),
+    ...(toolScope ? { scope: toolScope } : {}),
   };
   // The stdio server validates arguments against each tool's schema (the
   // SDK does it); a one-shot must too, and strictly: it is typed by hand, so
@@ -286,7 +303,7 @@ export async function runOneShot(
   const tool = tools.find((t) => t.name === shot.tool);
   if (tool) {
     const shape =
-      opts.scope && !("workspace" in tool.shape) && "workspace" in args
+      toolScope && !("workspace" in tool.shape) && "workspace" in args
         ? { ...tool.shape, workspace: z.string().optional() }
         : tool.shape;
     const parsed = z.object(shape).strict().safeParse(args);

package/src/ui/mcp/tools.ts

@@ -1171,7 +1171,9 @@ const APPROVAL_TOOLS: DenTool[] = [
   {
     name: "workspace_create",
     title: "Create a workspace",
-    description: "Create an empty Den workspace named `name`." + HELD,
+    description:
+      "Create an empty Den workspace named `name` and make it active, so service_try can start its services." +
+      HELD,
     action: true,
     shape: {
       name: z
@@ -1245,7 +1247,7 @@ const APPROVAL_TOOLS: DenTool[] = [
     name: "service_try",
     title: "Start one service",
     description:
-      "Start one service locally (`up`, as the Services page does) and report how it went: the exit code and the last lines of output." +
+      "Start one service locally (`up`, as the Services page does) and report how it went: the exit code and the last lines of output. A `workspace` that is not active is activated on the same Allow." +
       HELD,
     action: true,
     shape: {

package/src/ui/server/agent-routes.ts

@@ -183,7 +183,7 @@ const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 /** Never a TTY: a web start's terminal is 80×24. */
 const NO_TTY = { isTTY: false } as NodeJS.WriteStream;
 
-function webDeps(over: AgentsDeps = {}): AgentsResolved {
+export function webDeps(over: AgentsDeps = {}): AgentsResolved {
   return resolveAgentsDeps({
     stateDir: () => getStateDir(),
     workspaceExists: (ws) => Boolean(readWorkspacesFile().workspaces[ws]),
@@ -315,6 +315,8 @@ interface StartBody {
   instruction?: unknown;
   /** AG-10.10: a display name, checked as a rename's is. */
   name?: unknown;
+  /** 0.4.18: the folder it runs in (Start agent here). */
+  folder?: string;
 }
 
 const START_KEYS = [
@@ -327,6 +329,7 @@ const START_KEYS = [
   "allow",
   "instruction",
   "name",
+  "folder",
 ];
 
 async function startBody(req: http.IncomingMessage): Promise<StartBody> {
@@ -374,6 +377,11 @@ async function startBody(req: http.IncomingMessage): Promise<StartBody> {
   if (o.instruction !== undefined) out.instruction = o.instruction;
   if (o.name !== undefined && o.name !== null && o.name !== "")
     out.name = o.name;
+  if (o.folder !== undefined && o.folder !== null && o.folder !== "") {
+    if (typeof o.folder !== "string" || o.folder.length > 4096)
+      throw new AgentError("folder must be a path", { usage: true });
+    out.folder = o.folder;
+  }
   return out as StartBody;
 }
 
@@ -585,6 +593,7 @@ export async function handleAgentRoutes(
           : {}),
         ...(body.allow !== undefined ? { allow: body.allow } : {}),
         ...(body.name !== undefined ? { name: body.name } : {}),
+        ...(body.folder !== undefined ? { folder: body.folder } : {}),
         strict: true,
       });
       const ov = s.rec.overrides?.length

package/src/ui/server/held-actions.ts

@@ -5,13 +5,17 @@
  * copies:
  *
  *   workspace_create  the Workspaces page's create (workspaceCreateRefusal,
- *                     createWorkspace)
+ *                     createWorkspace), then activates it: nothing an
+ *                     agent calls activates a workspace, and service_try
+ *                     needs an active one
  *   repo_add          `repo add --json` (repo-command.ts repoAdd), a local
  *                     folder inside home only, as manifest_draft reads; its
  *                     dry run is the Review
  *   service_try       `up` through the service runner, as
  *                     /api/service/exec and service_up run it
- *                     (lifecycle-exec.ts), until it is ready or exits
+ *                     (lifecycle-exec.ts), until it is ready or exits;
+ *                     an inactive workspace is activated first, on the
+ *                     same Allow, and the Review says so
  */
 import * as path from "path";
 import { checkOnboardPath, type PathRules } from "../cli/onboard-reads.js";
@@ -35,6 +39,8 @@ export interface HeldActionDeps {
   validate: ManifestValidator;
   workspaceCreateRefusal: (name: string | undefined) => string | null;
   createWorkspace: (name: string) => void;
+  activateWorkspace: (name: string) => void;
+  workspaceActive: (name: string) => boolean;
   workspaceExists: (name: string) => boolean;
   /** Where `repo add` puts a repo with no -w: the focused one, else `default`. */
   defaultWorkspace: () => string;
@@ -84,13 +90,16 @@ export function heldActions(d: HeldActionDeps): HeldActions {
         args: { name },
         summary: `create the workspace "${name}"`,
         params: { name },
-        details: [`A new, empty workspace named "${name}".`],
+        details: [
+          `A new, empty workspace named "${name}", made active so its services can start.`,
+        ],
       };
     },
     async run(a) {
       const name = String(a.name);
       d.createWorkspace(name);
-      return { ok: true, name };
+      d.activateWorkspace(name);
+      return { ok: true, name, active: true };
     },
   };
 
@@ -177,21 +186,40 @@ export function heldActions(d: HeldActionDeps): HeldActions {
       if (!service)
         return { ok: false, error: "give service: <repo> or <repo>/<service>" };
       const workspace = str(a.workspace);
+      if (workspace !== undefined && !NAME_RE.test(workspace))
+        return {
+          ok: false,
+          error: `workspace "${workspace}" must use only letters, digits, ".", "_" and "-"`,
+        };
+      if (workspace !== undefined && !d.workspaceExists(workspace))
+        return { ok: false, error: `there is no workspace "${workspace}"` };
       const t = d.serviceTarget(service, workspace);
       if (!t.ok) return { ok: false, error: t.error };
+      const activates =
+        workspace !== undefined && !d.workspaceActive(workspace);
       return {
         ok: true,
         args: { service: t.address, ...(workspace ? { workspace } : {}) },
-        summary: `start ${t.address}${workspace ? ` in workspace "${workspace}"` : ""}`,
-        params: { service: t.address, ...(workspace ? { workspace } : {}) },
+        summary: `start ${t.address}${workspace ? ` in workspace "${workspace}"` : ""}${activates ? ` (this activates ${workspace})` : ""}`,
+        params: {
+          service: t.address,
+          ...(workspace ? { workspace } : {}),
+          ...(activates ? { activates: "1" } : {}),
+        },
         details: [
+          ...(activates
+            ? [`Activates the workspace "${workspace}" first, so it can run.`]
+            : []),
           `Runs the service's local "up", as the Services page's Start does.`,
           `Den reports the exit code and the last lines of its output.`,
         ],
       };
     },
     async run(a) {
-      return d.tryService(String(a.service), str(a.workspace));
+      const workspace = str(a.workspace);
+      if (workspace && !d.workspaceActive(workspace))
+        d.activateWorkspace(workspace);
+      return d.tryService(String(a.service), workspace);
     },
   };