Expose a high-level execution surface in the SDK (PmClient / runAction) #439

Problem (current behavior)

The public SDK (@unbrained/pm-cli/sdk and /sdk/runtime) is overwhelmingly extension/package-authoring focused (defineExtension, composeExtension, manifest synthesis, capability reconciliation, test harness). The only command run* exports are runSearch, runNormalize, runReindex, runContracts, runCalendar, runGuide, and audit helpers. There is no runCreate / runUpdate / runGet / runList / runClose / runContext / runComments, and no generic pmRun(action, options) executor — even though the MCP server's pm_run tool is exactly such a dispatch entry over PM_TOOL_ACTIONS.

So an agent wanting a programmatic integration (CI script, custom bot, embedded runtime) can validate intent with the SDK but cannot actually perform a mutation without spawning a pm process and re-parsing its text/JSON output.

Proposed improvement

Export a high-level, typed execution surface, e.g.:

import { PmClient } from "@unbrained/pm-cli/sdk/runtime";
const pm = new PmClient({ pmRoot, author });
await pm.create({ title, type, status });
await pm.list({ status: "open", limit: 20, projection: "brief" });
await pm.get(id, { depth: "brief" });
await pm.update(id, { status: "in_progress" });
await pm.close(id, reason);
await pm.context({ depth: "brief" });

…backed by the same handlers the CLI/MCP use, returning the same typed results (and the same lean defaults as the MCP server). At minimum, export a single runAction(action, options, globalOptions) that mirrors pm_run.

Agent benefit

Unlocks true programmatic integrations (no shell-out, no text parsing, no per-flag quoting), with shared types end-to-end. Lets agents embed pm as a library in tooling, eval harnesses, and custom MCP servers.