@modootoday/pmcp 0.14.1 → 0.15.0

package/dist/tui-worker.js

@@ -71,9 +71,24 @@ var tuiOptions = [
   },
   {
     name: "config",
-    describe: "Optional mailbox pmcp.toml",
+    describe: "Project pmcp.toml (or mailbox config for create)",
     placeholder: "<file>"
   },
+  {
+    name: "runtime",
+    describe: "Main native runtime ID for launch",
+    placeholder: "<runtime>"
+  },
+  {
+    name: "yes",
+    describe: "Confirm the first native runtime start",
+    boolean: true
+  },
+  {
+    name: "new",
+    describe: "Create a workspace after the previous group is stopped",
+    boolean: true
+  },
   {
     name: "actor-file",
     describe: "Optional private mailbox observer credential",
@@ -81,6 +96,8 @@ var tuiOptions = [
   }
 ];
 var allowed = {
+  launch: ["config", "runtime", "yes", "new"],
+  plan: ["config", "runtime"],
   doctor: [],
   create: ["group-file", "columns", "rows", "config", "actor-file"],
   inspect: ["view"],
@@ -101,7 +118,8 @@ var allowed = {
   check: ["view"]
 };
 function parseTui(args) {
-  const [action, ...extra] = args.positional;
+  let [action, ...extra] = args.positional;
+  if (action === void 0) action = one(args, "view") ? "open" : "launch";
   const options = action ? allowed[action] : void 0;
   if (!action || !options || extra.length)
     throw new ArgumentError("Provide one supported TUI operation");
@@ -121,6 +139,17 @@ function parseTui(args) {
     return Number(value);
   };
   if (action === "doctor") return { action, input: {} };
+  if (action === "launch" || action === "plan")
+    return {
+      action,
+      input: {},
+      startup: {
+        config: one(args, "config"),
+        runtime: one(args, "runtime"),
+        fresh: args.flags.has("new"),
+        confirmed: args.flags.has("yes")
+      }
+    };
   if (action === "create") {
     const config = one(args, "config");
     const actorFile = one(args, "actor-file");
@@ -677,9 +706,9 @@ async function attachNative(spec, renew) {
   }, 2e4) : void 0;
   let exitCode;
   try {
-    exitCode = await new Promise((resolve4, reject) => {
+    exitCode = await new Promise((resolve5, reject) => {
       client.once("error", reject);
-      client.once("exit", (code) => resolve4(code ?? 1));
+      client.once("exit", (code) => resolve5(code ?? 1));
     });
   } finally {
     if (timer) clearInterval(timer);
@@ -1594,7 +1623,7 @@ var DockerEngine = class {
     if (!/^1\.\d+$/.test(version))
       throw new Error("invalid_docker_api_version");
     const payload = JSON.stringify(configuration);
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve5, reject) => {
       const req = request(
         {
           socketPath: new URL(endpoint).pathname,
@@ -1629,7 +1658,7 @@ var DockerEngine = class {
               );
               if (!/^[a-f0-9]{64}$/.test(id2))
                 throw new Error("invalid_container_id");
-              resolve4(id2);
+              resolve5(id2);
             } catch (error) {
               reject(error);
             }
@@ -2709,7 +2738,7 @@ async function watchSession(operation) {
       )
     });
     if (index + 1 < count)
-      await new Promise((resolve4) => setTimeout(resolve4, intervalMs));
+      await new Promise((resolve5) => setTimeout(resolve5, intervalMs));
   }
   return {
     schemaVersion: 1,
@@ -3398,6 +3427,13 @@ var CommonHarness = class {
 // src/tui/application/feedback.ts
 import { join as join20 } from "path";
 var hints = {
+  startup_requires_recovery: "Inspect the saved group with pmcp tui plan and pmcp harness recovery inspect. No runtime was restarted.",
+  startup_group_paused: "The saved group is paused. Resume it explicitly through the harness CLI before reopening.",
+  startup_main_unavailable: "Inspect the saved main and recovery state. Stop the old group explicitly before using pmcp tui --new.",
+  startup_busy: "Another workspace launch is running. Wait and retry.",
+  startup_runtime_conflict: "The saved main uses another runtime. Stop the old group before creating a new workspace.",
+  workspace_already_running: "Reopen the existing workspace, or stop its exact owned group before using --new.",
+  runtime_executable_unavailable: "Install the selected native CLI on PATH, or choose an installed runtime with --runtime.",
   control_connection_lost: "The native writer or lease disappeared. Inspect and release control before reconnecting.",
   control_busy: "Another controller holds the lease. Release it explicitly before retrying.",
   native_writer_active: "A native writer is still attached. Detach that writer before retrying.",
@@ -3573,9 +3609,9 @@ var ViewConnection = class {
       ["-S", this.socket, "attach-session", "-E", "-t", view.session],
       { stdio: "inherit", env }
     );
-    return new Promise((resolve4, reject) => {
+    return new Promise((resolve5, reject) => {
       client.once("error", reject);
-      client.once("exit", (code) => resolve4(code ?? 1));
+      client.once("exit", (code) => resolve5(code ?? 1));
     });
   }
 };
@@ -3880,7 +3916,7 @@ async function waitFor(predicate, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await predicate()) return;
-    await new Promise((resolve4) => setTimeout(resolve4, 50));
+    await new Promise((resolve5) => setTimeout(resolve5, 50));
   }
   throw new Error("writer_not_ready");
 }
@@ -4076,6 +4112,7 @@ function resolveEncoder(model = DEFAULT_MODEL_ID, options = {}) {
 }
 
 // src/config.ts
+var CONFIG_FILE = "pmcp.toml";
 function embeddingSection(path, dir, value) {
   if (value === void 0) return void 0;
   if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -4166,6 +4203,17 @@ var CATALOG_KEYS = /* @__PURE__ */ new Set([
   "scopes",
   "builtin"
 ]);
+function findConfig(start2) {
+  let dir = resolve2(start2);
+  for (; ; ) {
+    const candidate = join23(dir, CONFIG_FILE);
+    if (existsSync10(candidate)) return candidate;
+    if (existsSync10(join23(dir, ".git"))) return null;
+    const parent = dirname5(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
 function stringList(path, key, value) {
   if (!Array.isArray(value) || !value.every((v) => typeof v === "string")) {
     throw new ConfigError(path, `[catalog] ${key} must be a list of strings`);
@@ -5551,7 +5599,7 @@ ${content}
     stopped = true;
   });
   while (!stopped) {
-    await new Promise((resolve4) => setTimeout(resolve4, 1500));
+    await new Promise((resolve5) => setTimeout(resolve5, 1500));
     await draw();
   }
 }
@@ -5880,6 +5928,8 @@ async function createView(input) {
 
 // src/tui/application/invoke.ts
 async function invokeTui(invocation) {
+  if (invocation.action === "launch" || invocation.action === "plan")
+    throw new Error("startup_requires_cli_context");
   if (invocation.action === "doctor")
     return { schemaVersion: 1, ok: true, ...dependencies() };
   if (invocation.action === "create") return createView(invocation.create);
@@ -5917,11 +5967,262 @@ function failedInvocation(action, error) {
   };
 }
 
+// src/tui/startup/workspace.ts
+import { existsSync as existsSync16 } from "fs";
+
+// src/tui/startup/config.ts
+import { realpathSync as realpathSync12 } from "fs";
+import { resolve as resolve4 } from "path";
+var preference = [
+  "codex-cli",
+  "gemini-cli",
+  "antigravity",
+  "grok-cli",
+  "claude-code"
+];
+function startupSettings(request2) {
+  const path = request2.config ? resolve4(request2.cwd, request2.config) : findConfig(request2.cwd);
+  const config = path ? readConfig(path) : void 0;
+  const source2 = config?.raw.tui;
+  const fail = (message) => {
+    throw new ConfigError(path ?? "pmcp.toml", `[tui] ${message}`);
+  };
+  if (source2 !== void 0 && (source2 === null || typeof source2 !== "object" || Array.isArray(source2)))
+    fail("must be a table");
+  const values = source2 ?? {};
+  const allowed2 = /* @__PURE__ */ new Set([
+    "runtime",
+    "memory_mb",
+    "session_memory_mb",
+    "max_active",
+    "group_file"
+  ]);
+  for (const key of Object.keys(values)) {
+    if (!allowed2.has(key)) fail(`unknown key ${key}`);
+  }
+  const string = (key) => {
+    const value = values[key];
+    if (value === void 0) return void 0;
+    if (typeof value !== "string" || !value.trim())
+      fail(`${key} must be a non-empty string`);
+    return value;
+  };
+  const integer2 = (key, fallback, min, max) => {
+    const value = values[key] ?? fallback;
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+      fail(`${key} must be an integer`);
+    if (Number(value) < min || Number(value) > max)
+      fail(`${key} must be between ${min} and ${max}`);
+    return Number(value);
+  };
+  const configuredRuntime = string("runtime");
+  if (configuredRuntime !== void 0 && configuredRuntime !== "auto" && !Object.hasOwn(runtimeExecutables, configuredRuntime))
+    fail("runtime must be auto or a supported runtime ID");
+  const available = preference.filter(
+    (runtime3) => locateExecutable(runtimeExecutables[runtime3], request2.cwd)
+  );
+  let runtime2 = request2.runtime ?? configuredRuntime ?? "auto";
+  if (runtime2 === "auto") runtime2 = available[0] ?? "codex-cli";
+  if (!Object.hasOwn(runtimeExecutables, runtime2))
+    fail("runtime must be a supported runtime ID");
+  const memoryMb = integer2("memory_mb", 2048, 128, 4096);
+  const sessionMemoryMb = integer2("session_memory_mb", 768, 32, 1536);
+  if (sessionMemoryMb > memoryMb)
+    fail("session memory exceeds the group budget");
+  const groupFile = string("group_file");
+  return {
+    projectRoot: realpathSync12(config?.dir ?? request2.cwd),
+    ...config ? { configFile: config.path } : {},
+    runtime: runtime2,
+    allowedRuntimes: [.../* @__PURE__ */ new Set([...available, runtime2])],
+    memoryMb,
+    sessionMemoryMb,
+    maxActive: integer2("max_active", 2, 1, 5),
+    ...groupFile ? { groupFile: resolve4(config?.dir ?? request2.cwd, groupFile) } : {}
+  };
+}
+
+// src/tui/startup/state.ts
+import { createHash as createHash8 } from "crypto";
+import { existsSync as existsSync15, lstatSync as lstatSync8, mkdirSync as mkdirSync6 } from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname as dirname9, join as join30 } from "path";
+function startupFile(projectRoot) {
+  const root = join30(
+    process.env.XDG_STATE_HOME ?? join30(homedir6(), ".local/state"),
+    "pmcp/launcher"
+  );
+  const key = createHash8("sha256").update(projectRoot).digest("hex");
+  return join30(root, `${key}.json`);
+}
+function readStartup(file, projectRoot) {
+  if (!existsSync15(file)) return null;
+  const value = object(readPrivateJson(file));
+  if (value.schemaVersion !== 1 || value.projectRoot !== projectRoot)
+    throw new Error("foreign_startup_state");
+  if (!["creating", "starting", "view-pending", "ready"].includes(
+    String(value.phase)
+  ))
+    throw new Error("invalid_startup_state");
+  text(value.runtime, "runtime");
+  if (value.phase !== "creating") {
+    text(value.groupFile, "group_file");
+    text(value.generation, "generation");
+  }
+  if (value.phase === "ready") text(value.viewFile, "view_file");
+  return value;
+}
+function saveStartup(file, state) {
+  privateJson(file, state);
+}
+
+// src/tui/startup/workspace.ts
+function succeeded(receipt) {
+  if (receipt.ok !== true)
+    throw new Error(String(receipt.error ?? "startup_operation_failed"));
+  return receipt;
+}
+async function prepareWorkspace(request2) {
+  const settings = startupSettings(request2);
+  const file = startupFile(settings.projectRoot);
+  let state = readStartup(file, settings.projectRoot);
+  if (state && !["ready", "view-pending"].includes(state.phase)) {
+    if (!request2.fresh || state.phase === "creating")
+      throw new Error("startup_requires_recovery");
+  }
+  if (state && settings.groupFile && state.groupFile !== settings.groupFile)
+    throw new Error("startup_group_conflict");
+  if (state) {
+    const group = new GroupStore(state.groupFile).state.group;
+    assertGroup(group, settings.projectRoot, state.generation);
+    if (group.state === "paused") throw new Error("startup_group_paused");
+    if (request2.fresh) {
+      if (group.state !== "stopped")
+        throw new Error("workspace_already_running");
+      state = null;
+    } else {
+      if (group.state !== "ready") throw new Error("startup_requires_recovery");
+      if (request2.runtime && request2.runtime !== state.runtime)
+        throw new Error("startup_runtime_conflict");
+    }
+  }
+  if (!state && settings.groupFile) {
+    const store = new GroupStore(settings.groupFile);
+    const group = store.state.group;
+    assertGroup(group, settings.projectRoot);
+    if (group.state !== "ready") throw new Error("startup_group_not_ready");
+    state = {
+      schemaVersion: 1,
+      projectRoot: settings.projectRoot,
+      phase: "view-pending",
+      groupFile: store.path,
+      generation: group.generation,
+      runtime: settings.runtime
+    };
+    saveStartup(file, state);
+  }
+  if (!state) {
+    state = {
+      schemaVersion: 1,
+      projectRoot: settings.projectRoot,
+      phase: "creating",
+      runtime: settings.runtime
+    };
+    saveStartup(file, state);
+    const created = succeeded(
+      await invoke({
+        family: "group",
+        action: "create",
+        input: {
+          projectRoot: settings.projectRoot,
+          allowedRuntimes: [...settings.allowedRuntimes],
+          memoryMb: settings.memoryMb,
+          maxActive: settings.maxActive
+        }
+      })
+    );
+    state.groupFile = String(created.groupFile);
+    state.generation = created.group.generation;
+    state.phase = "starting";
+    saveStartup(file, state);
+    succeeded(
+      await invoke({
+        family: "session",
+        action: "start",
+        groupFile: state.groupFile,
+        generation: state.generation,
+        input: {
+          runtime: settings.runtime,
+          role: "main",
+          memoryMb: settings.sessionMemoryMb
+        }
+      })
+    );
+    state.phase = "view-pending";
+    saveStartup(file, state);
+  }
+  const observed = succeeded(
+    await invoke({
+      family: "session",
+      action: "list",
+      groupFile: state.groupFile
+    })
+  );
+  const sessions = observed.sessions;
+  const main = sessions.find(
+    (session) => session.role === "main" && session.alive
+  );
+  if (!main) throw new Error("startup_main_unavailable");
+  state.runtime = main.runtime;
+  const existing = state.viewFile && existsSync16(state.viewFile) ? readView(state.viewFile).view : void 0;
+  if (existing) {
+    if (existing.groupFile !== state.groupFile || existing.generation !== state.generation)
+      throw new Error("foreign_startup_view");
+  }
+  if (!existing || existing.state === "closed") {
+    const created = await createView({
+      groupFile: state.groupFile,
+      columns: process.stdout.columns ?? Number(process.env.PMCP_TUI_COLUMNS),
+      rows: process.stdout.rows ?? Number(process.env.PMCP_TUI_ROWS)
+    });
+    state.viewFile = created.viewFile;
+  }
+  state.phase = "ready";
+  saveStartup(file, state);
+  return {
+    schemaVersion: 1,
+    ok: true,
+    viewFile: state.viewFile,
+    groupFile: state.groupFile,
+    generation: state.generation,
+    runtime: state.runtime,
+    readOnly: true
+  };
+}
+function assertGroup(group, projectRoot, generation) {
+  if (group.projectRoot !== projectRoot)
+    throw new Error("startup_project_mismatch");
+  if (generation && group.generation !== generation)
+    throw new Error("stale_group_generation");
+}
+
 // src/tui/application/worker.ts
 var [role, ...argv] = process.argv.slice(2);
 var callback2 = argv.includes("--callback");
 try {
-  if (role === "attach") {
+  if (role === "startup") {
+    const [encoded, ...extra] = argv;
+    if (!encoded || extra.length || encoded.length > 16384 || !/^[A-Za-z0-9_-]+$/.test(encoded))
+      throw new Error("invalid_startup_arguments");
+    const request2 = JSON.parse(
+      Buffer.from(encoded, "base64url").toString("utf8")
+    );
+    if (typeof request2.cwd !== "string" || !request2.cwd)
+      throw new Error("invalid_startup_arguments");
+    const result = await prepareWorkspace(request2);
+    process.stdout.write(`${JSON.stringify(result)}
+`);
+  } else if (role === "attach") {
     const [file, sessionId, leaseFile] = argv;
     if (!file || !sessionId) throw new Error("invalid_attachment_arguments");
     await waitFor(() => {
@@ -5953,7 +6254,7 @@ try {
         tuiOptions
       )
     );
-    if (invocation.action === "create" || invocation.action === "doctor")
+    if (["create", "doctor", "launch", "plan"].includes(invocation.action))
       throw new Error("unsupported_worker_operation");
     const result = role === "locked" ? await operate(
       invocation.action,

package/docs/skills.md

@@ -78,12 +78,12 @@ existing URLs and immutable archive bytes remain available.
 For native marketplace commands, follow the [README](../README.md).
 Gemini and Antigravity need their own package formats for selected library plugins;
 do not assume that identically named manifest files accept the same schema.
-After the next npm release, `pmcp marketplace export <plugin> --runtime <tool>
+Since 0.14.0, `pmcp marketplace export <plugin> --runtime <tool>
 --output <new-directory>` materializes a selected package without altering native
 settings or installing it. Use the native manager to review and install that folder.
 Existing export destinations are preserved.
 
-The built-in catalog on repository main is available without remote fetching.
+The built-in catalog is available without remote fetching.
 `--no-builtin` or `[catalog] builtin = false` opts out; library APIs continue to
 read explicitly supplied catalog roots. `--marketplace <directory>` reads installed
 Claude, Codex and Grok local descriptors, rejects path escapes and does not fetch
@@ -91,7 +91,7 @@ remote plugin sources. Add a remote marketplace with its native manager first.
 
 Public npm skill installation uses the bundled catalog, a matching installed
 dependency version and immutable free archive URLs. It verifies archive integrity,
-content-only metadata, instruction digests and installed file bytes. npm or Bun
+content-only metadata, instruction digests and installed file bytes. npm, Bun or pnpm
 changes the project and lockfile only after confirmation, with scripts disabled.
 `--provider hosted` remains a separate service path with its own access policy.
 Native plugin installation does not automatically version-match dependencies:

package/docs/terminal-workspace.md

@@ -13,6 +13,69 @@ retain their existing group budgets and execution profile.
 
 ## Open a workspace
 
+From a supported interactive terminal, run `pmcp` or `pmcp tui`. The first
+launch chooses an installed main in this order: Codex, Gemini, agy, Grok,
+Claude. It displays the selection and asks before starting. Press Enter to
+start or enter q to cancel. No provider request or group creation occurs before
+this confirmation. Use `--runtime` to choose a supported runtime ID explicitly.
+Provider login and folder trust still use the native screen.
+
+```sh
+pmcp
+pmcp tui --runtime codex-cli
+pmcp tui plan
+```
+
+The start creates a private owned group and read-only view, then reconnects to
+that workspace on later launches. Defaults are 2048 MiB for the group, 768 MiB
+for its main and at most two active sessions. Terminal size selects the existing
+A or compact layout. Taking control remains explicit with Ctrl-g then c.
+This launches a native process; the defaults are cooperative host supervision,
+not a Docker isolation policy. Use an explicitly configured Docker group when
+you require that execution profile.
+
+The nearest `pmcp.toml` within the Git repository determines the project root,
+including from nested cwd. A submodule does not inherit its parent's config;
+use `--config` when you explicitly want a different configuration scope.
+Without a config, the current real directory is the project root. Customize only
+the values you need:
+
+```toml
+[tui]
+runtime = "codex-cli"
+memory_mb = 2048
+session_memory_mb = 768
+max_active = 2
+```
+
+runtime defaults to auto. Supported IDs are codex-cli, gemini-cli, antigravity,
+grok-cli and claude-code. CLI `--runtime` overrides the config for a new main.
+An optional group_file points to a deliberately selected existing owned group
+with a live main; relative paths resolve from the config directory. `--config`
+selects a config file explicitly. Unknown keys and invalid budgets are errors.
+Config budget changes apply to a new group; existing groups keep their grants.
+
+`pmcp tui launch --yes` explicitly confirms the first start without the prompt.
+Launch still requires a supported interactive terminal. `pmcp tui plan` reports
+resolved settings and saved paths without writing or invoking a provider.
+The launcher checkpoint lives under XDG_STATE_HOME/pmcp/launcher, or
+~/.local/state/pmcp/launcher, with private file permissions.
+
+Reopening never adopts an unrelated tmux session or restarts a stopped main.
+A paused group, interrupted start or changed generation requires explicit
+harness inspection and recovery. After explicitly stopping the old owned group,
+`pmcp tui --new` creates a new workspace. Detach preserves the existing native
+process and draft. Closing only the view permits a new presentation over the
+same live group. Keep original state when investigating a failed start.
+If a creation checkpoint has no group path yet, keep it for manual inspection;
+the launcher refuses to infer ownership or restart from that incomplete state.
+
+Piped bare launches and leading MCP server options preserve the existing stdio
+contract. Use `pmcp serve` explicitly in MCP configuration. Unsupported
+interactive hosts show help; they do not wait for JSON-RPC input.
+
+## Advanced view operations
+
 First [create a harness group and its sessions](terminal-harness.md). Set GROUP_FILE
 to that group's private state path, then check prerequisites and create a view:
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pmcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "mcpServers": {
     "pmcp": {
       "type": "stdio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modootoday/pmcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "license": "Elastic-2.0",
   "author": "modootoday",
   "description": "Use the skills your packages already ship, and keep your AI tools' project configuration in one place.",
@@ -91,7 +91,8 @@
     "marketplace:check": "bun scripts/build-marketplace.mjs --check",
     "docs:check": "prettier --check --ignore-path /dev/null README.md docs/*.md && npm run marketplace:check && npm run skills:check && npm run site:check",
     "site:deployed": "node scripts/check-deployed.mjs",
-    "prepack": "npm run docs:check && npm run build && npm run typecheck && npm test",
+    "package:verify": "node scripts/verify-package.mjs",
+    "prepack": "npm run docs:check && npm run build && npm run typecheck && npm test && npm run package:verify -- --pack --matrix --report-stderr",
     "format": "prettier --write .",
     "format:check": "prettier --check ."
   },

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pmcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Find package skills and use native runtime project configuration.",
   "author": { "name": "modootoday" },
   "license": "Elastic-2.0",

package/plugins/pmcp/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pmcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Find package skills and use native runtime project configuration.",
   "author": { "name": "modootoday" },
   "license": "Elastic-2.0",

package/plugins/pmcp/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pmcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "mcpServers": {
     "pmcp": {
       "type": "stdio",

package/plugins/pmcp/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "pmcp",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Find package skills and use native runtime project configuration.",
   "author": { "name": "modootoday" },
   "license": "Elastic-2.0",