Changelog, dev startup, README, AgentHub 0.4.0, model catalog, and landing site (#7)

Branch-length batch covering tooling, the model layer, the Web App and the public surfaces. Highlights: - Changelog: a per-release `changelog/<version>/` tree, grouped by the surface each change touches, with a root CHANGELOG.md holding one line per release. - Dev startup: `scripts/dev-prebuild.mjs` serializes the skills+core prebuild behind a lock and keeps `pnpm install` current; `pnpm dev` runs server+web together. - AgentHub 0.3.3 -> 0.4.0: OmniMessage complete payloads carry one opaque `fidelity` object in place of item-level `signature`/`phase`, threaded verbatim through Trace, replay and resume; malformed classification adapted to the new error types. - Model layer: a model is always referenced by an explicit `(provider, model_id)` pair. The provider is never inferred, guessed or defaulted -- both the catalog inference and the unique-match config resolution are gone, and CLI, SDK, server routes and run_subagent all require the complete pair. Catalog gains the Qwen Token Plan, Qwen Pay-As-You-Go and Fireworks AI gateways, plus an expanded OpenRouter group. - Web App: catalog preset sync and per-group speed test on the Models page, positional slash commands, a markdown renderer, skill-library update reminders, and a vertically centred draft page whose upward menus size themselves to the room available. - Public surfaces: restructured READMEs, the penguin.ooo landing site and blog, refreshed benchmark results for both suites, and the demo videos playing on the landing page. Includes the fixes from a full review of the branch: 23 confirmed findings, among them a provider-inference bug that could send one vendor's API key to another vendor's endpoint, and an Escape handler that destroyed the composer's contents unrecoverably. Verified on the branch head: pnpm test (1127 passing, 7 packages), pnpm typecheck and pnpm format:check clean, Playwright e2e 14/14.
2026-07-21 17:43:31 +08:00
parent abf0a2f248
commit d4faee3a1e
214 changed files with 9406 additions and 1688 deletions
@@ -22,7 +22,7 @@
    "penguin": "tsx src/index.ts"
  },
  "dependencies": {
-    "@prismshadow/agenthub": "^0.3.3",
+    "@prismshadow/agenthub": "^0.4.0",
    "@prismshadow/penguin-core": "workspace:*",
    "@prismshadow/penguin-server": "workspace:*",
    "@prismshadow/penguin-skills": "workspace:*",
@@ -1,12 +1,14 @@
 /**
 * `penguin chat` — interactive REPL.
 *
- *   penguin chat [--model-id <id>] [--provider <group>] [--project-id <id>] [--agent-id <id>]
+ *   penguin chat [--model-id <id> --provider <group>] [--project-id <id>] [--agent-id <id>]
 *                [--workspace <path>] [--approve <allow-all|deny-all|read-only|always-ask>]
 *
 * Each line of input starts one conversation turn; `/compact` proactively compacts the
 * context (reason=manual); `/exit` or `/quit` exits.
- * Uses the current directory when no Workspace is specified.
+ * Uses the current directory when no Workspace is specified. A model reference is always an
+ * explicit `(provider, model_id)` pair, so `--model-id` and `--provider` must be given
+ * together; giving neither uses the Project's default model.
 *
 * Multi-line input: trailing `\` continues the line; when the terminal supports bracketed
 * paste, a multi-line paste is treated as a single message (sent on Enter).
@@ -65,6 +67,17 @@ export function registerChatCommand(program: Command, t: Messages): void {
    .option("--approve <mode>", t.common.approve)
    .option("--resume [sessionId]", t.chat.resume)
    .action(async (opts) => {
+      // The model reference is a pair: commander can only require each option on its own,
+      // so the "both or neither" rule is enforced here. Giving neither is the normal case
+      // and falls back to the Project's default model. Skipped under --resume, which
+      // rejects both options outright further down with a more specific message.
+      // Usage errors go to stderr (as in `run` and `config model add`), unlike this file's
+      // informational messages, which the REPL writes to stdout.
+      if (opts.resume === undefined && Boolean(opts.modelId) !== Boolean(opts.provider)) {
+        process.stderr.write(`${t.error(t.modelRefIncomplete())}\n`);
+        process.exitCode = 1;
+        return;
+      }
      const mode = resolveApprovalMode(opts.approve, t);
      const out = process.stdout;

@@ -2,7 +2,7 @@
 * `penguin config` — manages a Project's model credentials, default model, model list,
 * Agent-level vault environment variables, and UI language.
 *
- *   penguin config model add --model-id <upstream id> [--provider <group>] [--api-key <key>] [--context-window <n>] [--set-default] [--root <dir>]
+ *   penguin config model add --model-id <upstream id> --provider <group> [--api-key <key>] [--context-window <n>] [--set-default] [--root <dir>]
 *   penguin config model default --model-id <upstream id> --provider <group> [--root <dir>]
 *   penguin config model vision --model-id <upstream id> --provider <group> [--root <dir>]
 *   penguin config model list [--root <dir>]
@@ -13,12 +13,12 @@
 *
 * `--model-id` always takes the **upstream id** (the request id sent to AgentHub verbatim),
 * which together with `--provider` forms a `(provider, model_id)` paired reference —
- * **no string concatenation is ever performed**. For `model add`, --provider defaults to
- * an inference from the built-in catalog (falling back to custom when inference fails);
- * a new entry's client_type defaults according to the group's semantics (not set for
- * first-party vendors; openai for custom / self-hosted groups / gateways, with the
- * gateway's endpoint base URL pre-filled). For `model default` / `model vision`,
- * --provider is **required**; core validation raises an error when the reference is not
+ * **no string concatenation is ever performed**. `--provider` is **required** on all three
+ * model subcommands: the group is never guessed, so `--api-key` can never land on a vendor
+ * the user did not name. For `model add`, a new entry's client_type defaults according to
+ * the group's semantics (not set for first-party vendors; openai for custom / self-hosted
+ * groups / gateways, with the gateway's endpoint base URL pre-filled). For `model default`
+ * / `model vision`, core validation raises an error when the reference is not
 * found in models. `--root` specifies the data root directory (priority: option >
 * PENGUIN_HOME > ~/.penguin/data). The UI language is controlled by the PENGUIN_LANG
 * environment variable; `config lang` writes it into the shell startup file and restarts
@@ -39,7 +39,6 @@ import {
  catalogEntryFor,
  formatModelRef,
  getModel,
-  inferProviderForUpstream,
  loadAgentVault,
  loadProjectConfig,
  providerInfo,
@@ -117,7 +116,7 @@ export function registerConfigCommand(program: Command, t: Messages): void {
    .command("add")
    .description(t.config.addDesc)
    .requiredOption("--model-id <id>", t.config.addModelId)
-    .option("--provider <group>", t.config.addProvider)
+    .requiredOption("--provider <group>", t.config.addProvider)
    .option("--api-key <key>", t.config.addApiKey)
    .option("--base-url <url>", t.config.addBaseUrl)
    .option("--context-window <n>", t.config.addContextWindow, parseIntArg)
@@ -133,11 +132,11 @@ export function registerConfigCommand(program: Command, t: Messages): void {
    .option("--root <dir>", t.common.root)
    .action(async (opts) => {
      const root = resolveRootOption(opts.root);
-      // --model-id takes the upstream id, paired with --provider as a reference
-      // (--provider defaults to catalog-based inference, falling back to custom); no
-      // concatenation is performed.
+      // --model-id takes the upstream id, paired with the required --provider as a
+      // reference; the group is never guessed, so --api-key can only ever land on the
+      // vendor the user named. No concatenation is performed.
      const modelId: string = opts.modelId;
-      const provider: string = opts.provider ?? inferProviderForUpstream(modelId);
+      const provider: string = opts.provider;
      const ref: ModelRef = { provider, model_id: modelId };
      const before = await loadProjectConfig(root, opts.projectId);
      const existed = getModel(before, ref) !== undefined;
@@ -1,14 +1,14 @@
 /**
 * `penguin run` — send a single Task in one shot.
 *
- *   penguin run -m <msg> [--model-id <id>] [--provider <group>] [--workspace <path>]
+ *   penguin run -m <msg> [--model-id <id> --provider <group>] [--workspace <path>]
 *               [--project-id <id>] [--agent-id <id>]
 *               [--approve <allow-all|deny-all|read-only|always-ask>]
 *
 * Uses the current directory when Workspace is unspecified; uses the Project's default model
- * when model is unspecified. `--provider` is optional: when omitted, `--model-id` is resolved
- * via resolveModelRef semantics (only matches when the exact value is globally unique in the
- * config; ambiguity is an error). Defaults to interactive per-call approval; `--approve`
+ * when model is unspecified. A model reference is always an explicit `(provider, model_id)`
+ * pair, so `--model-id` and `--provider` must be given together — giving only one of them is
+ * an error, never a lookup. Defaults to interactive per-call approval; `--approve`
 * selects the permission mode.
 * Docs: /docs/cli § "penguin run".
 */
@@ -31,6 +31,14 @@ export function registerRunCommand(program: Command, t: Messages): void {
    .option("--workspace <path>", t.common.workspace)
    .option("--approve <mode>", t.common.approve)
    .action(async (opts) => {
+      // The model reference is a pair: commander can only require each option on its own,
+      // so the "both or neither" rule is enforced here. Giving neither is the normal case
+      // and falls back to the Project's default model.
+      if (Boolean(opts.modelId) !== Boolean(opts.provider)) {
+        process.stderr.write(`${t.error(t.modelRefIncomplete())}\n`);
+        process.exitCode = 1;
+        return;
+      }
      const mode = resolveApprovalMode(opts.approve, t);

      const agent = await createAgent({
@@ -23,7 +23,7 @@ export interface Messages {
    projectId: string;
    agentId: string;
    modelId: string;
-    /** run/chat's --provider: pairs with --model-id; when omitted, resolved by unique match (ambiguity is an error). */
+    /** run/chat's --provider: must be given together with --model-id (the group is never inferred). */
    provider: string;
    /** Data root directory option (priority: --root > PENGUIN_HOME > ~/.penguin/data). */
    root: string;
@@ -113,6 +113,8 @@ export interface Messages {
  approveModeInvalid(value: string): string;
  /** Render label for an approval decision (frontend renders the approval_decision event; one label each for allow/deny). */
  approvalDecision(decision: "allow" | "deny"): string;
+  /** run/chat given only one of --model-id / --provider: a model reference is always an explicit pair, never a lookup. */
+  modelRefIncomplete(): string;
  /** --resume is mutually exclusive with --workspace/--model-id (neither can change once the Session is created). */
  resumeNoOverride(): string;
  /** --resume given without a session id, and the current Agent has no Session at all. */
@@ -156,7 +158,7 @@ const en: Messages = {
    agentId: "Agent id",
    modelId: "Model to use (upstream model id; defaults to the Project default model)",
    provider:
-      "Provider of --model-id; when omitted, the model id must match exactly one configured entry (ambiguity is an error)",
+      "Provider group of --model-id; required whenever --model-id is given (the group is never inferred)",
    root: "Data root directory (overrides PENGUIN_HOME and ~/.penguin/data)",
    workspace: "Workspace directory; must already exist (defaults to the current directory)",
    approve:
@@ -168,11 +170,11 @@ const en: Messages = {
    addDesc: "Add or update a model, optionally writing a credential",
    addModelId: "Upstream model id sent to AgentHub as-is (e.g. claude-sonnet-4-6)",
    addProvider:
-      "Provider group stored alongside model_id; inferred from the builtin catalog when omitted, else custom",
+      "Provider group stored alongside model_id; required, never inferred (use custom for anything without a vendor group)",
    addApiKey: "API key, stored inline in the Project's hidden .project_config.toml",
    addBaseUrl: "Custom base URL",
    addContextWindow: "Context window size (tokens)",
-    addClientType: "AgentHub client type (e.g. openai); inferred from model id when omitted",
+    addClientType: "AgentHub client type (e.g. openai); defaults by provider group when omitted",
    addVision: "Mark the model as supporting image input (vision)",
    addNoVision: "Mark the model as NOT supporting image input; omit both to keep current",
    addPriceCacheRead: "Price per 1M tokens: cache read (USD)",
@@ -235,6 +237,8 @@ const en: Messages = {
  approveModeInvalid: (value) =>
    `Invalid approval mode "${value}". Use allow-all, deny-all, read-only, or always-ask.`,
  approvalDecision: (decision) => (decision === "allow" ? "✓ [approved]" : "× [denied]"),
+  modelRefIncomplete: () =>
+    "--model-id and --provider must be given together: a model reference is always an explicit (provider, model_id) pair. Omit both to use the Project default model.",
  resumeNoOverride: () =>
    "--resume does not accept --workspace, --model-id or --provider: they follow the original Session and cannot change.",
  resumeNoSession: () => "No session to resume: this agent has no recorded sessions yet.",
@@ -268,7 +272,7 @@ const zh: Messages = {
    projectId: "Project id",
    agentId: "Agent id",
    modelId: "本次使用的模型（上游模型 id；默认 Project 默认模型）",
-    provider: "--model-id 的 provider 分组；省略时 model id 须在配置中精确唯一命中（歧义报错）",
+    provider: "--model-id 的 provider 分组；给出 --model-id 时必须一并给出（分组不作任何推断）",
    root: "数据根目录（优先于 PENGUIN_HOME 与 ~/.penguin/data）",
    workspace: "Workspace 目录，须为已存在目录（默认当前目录）",
    approve:
@@ -279,11 +283,11 @@ const zh: Messages = {
    modelDesc: "管理模型 credential 与默认模型",
    addDesc: "新增或更新一个模型，并可写入 credential",
    addModelId: "上游模型 id（如 claude-sonnet-4-6，原样发给 AgentHub）",
-    addProvider: "与 model_id 分列存储的 provider 分组；缺省按内置目录推断，推断不出为 custom",
+    addProvider: "与 model_id 分列存储的 provider 分组；必填，不作推断（无厂商分组时填 custom）",
    addApiKey: "API key，内联存入 Project 的隐藏文件 .project_config.toml",
    addBaseUrl: "自定义 base url",
    addContextWindow: "上下文窗口大小（token 数）",
-    addClientType: "AgentHub 客户端协议（如 openai）；缺省由 model id 推断",
+    addClientType: "AgentHub 客户端协议（如 openai）；缺省按 provider 分组的语义取值",
    addVision: "标注该模型支持图片输入（视觉）",
    addNoVision: "标注该模型不支持图片输入；两者都不给则保留原值",
    addPriceCacheRead: "每百万 token 价格：缓存读取（USD）",
@@ -345,6 +349,8 @@ const zh: Messages = {
  approveModeInvalid: (value) =>
    `无效的审批模式 "${value}"。请使用 allow-all、deny-all、read-only 或 always-ask。`,
  approvalDecision: (decision) => (decision === "allow" ? "✓ [已批准]" : "× [已拒绝]"),
+  modelRefIncomplete: () =>
+    "--model-id 与 --provider 必须成对给出：模型引用始终是显式的 (provider, model_id) 组合。两者都不给则使用 Project 默认模型。",
  resumeNoOverride: () =>
    "--resume 不接受 --workspace、--model-id 与 --provider：均沿用原 Session，创建后不可更换。",
  resumeNoSession: () => "没有可恢复的 Session：当前 Agent 还没有任何会话记录。",
@@ -1,10 +1,10 @@
 /**
 * Integration tests for `penguin config model add|default|vision|list` (run through
 * commander's parseAsync for the full command path): --model-id always takes the
- * upstream id, paired with --provider to form a (provider, model_id) reference (add's
- * --provider defaults to catalog-based inference, falling back to custom when
- * inference fails; default / vision require --provider and raise an error when the
- * reference isn't found in models — no string concatenation is ever performed); --root
+ * upstream id, paired with --provider to form a (provider, model_id) reference
+ * (--provider is required on all three subcommands — the group is never inferred — and
+ * default / vision raise an error when the reference isn't found in models; no string
+ * concatenation is ever performed); --root
 * specifies the data root directory (takes priority over PENGUIN_HOME); persisted to a
 * single hidden .project_config.toml (mode 0600, credentials inline, provider and
 * model_id as separate columns); list displays provider and model_id as separate
@@ -84,13 +84,15 @@ describe("penguin config model add/list (--root plus provider / model_id stored
      "add",
      "--model-id",
      "my-own-model",
+      "--provider",
+      "custom",
      "--api-key",
      "sk-root-secret-1",
      "--root",
      tmpRoot,
    ]);
    expect(add.code).toBe(0);
-    // Catalog inference fails -> falls back to the custom group (provider is a separate field, never concatenated into the id).
+    // The named group is stored as a separate field, never concatenated into the id.
    expect(add.out).toContain("Added model (provider=custom, model_id=my-own-model).");

    const file = projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID);
@@ -119,11 +121,13 @@ describe("penguin config model add/list (--root plus provider / model_id stored
    expect(list.out).not.toContain("sk-root-secret-1");
  });

-  it("built-in catalog infers the grouping: an upstream id matching the catalog lands under that provider; --set-default writes a pair reference", async () => {
+  it("naming an existing pair updates that preset entry in place; --set-default writes a pair reference", async () => {
    const add = await runModel([
      "add",
      "--model-id",
      "claude-sonnet-4-6",
+      "--provider",
+      "anthropic",
      "--set-default",
      "--root",
      tmpRoot,
@@ -168,8 +172,16 @@ describe("penguin config model add/list (--root plus provider / model_id stored
  });

  it("client_type defaults by grouping semantics (PRN-021): custom / self-hosted / gateway get openai, first-party providers get none", async () => {
-    // custom (catalog inference fails) and self-hosted groups (--provider not a catalog value): default to client_type=openai.
-    await runModel(["add", "--model-id", "my-openai-proxy", "--root", tmpRoot]);
+    // The custom group and self-hosted groups (--provider not a catalog value): default to client_type=openai.
+    await runModel([
+      "add",
+      "--model-id",
+      "my-openai-proxy",
+      "--provider",
+      "custom",
+      "--root",
+      tmpRoot,
+    ]);
    await runModel(["add", "--model-id", "in-house-1", "--provider", "mylab", "--root", tmpRoot]);
    // A non-catalog id under a first-party vendor group: client_type is not set (AgentHub auto-routes by upstream id).
    await runModel([
@@ -241,13 +253,29 @@ describe("penguin config model add/list (--root plus provider / model_id stored
  });
 });

-describe("model default/vision: --provider is required, (provider, model_id) pair reference", () => {
+describe("model add/default/vision: --provider is required, (provider, model_id) pair reference", () => {
  it("missing --provider: commander usage error, nonzero exit code", async () => {
    const bad = await runModel(["default", "--model-id", "deepseek-v4-flash", "--root", tmpRoot]);
    expect(bad.code).not.toBe(0);
    expect(bad.err).toContain("--provider");
  });

+  it("add without --provider is a usage error too: the group is never inferred, so no config is written", async () => {
+    const bad = await runModel([
+      "add",
+      "--model-id",
+      "claude-sonnet-4-6",
+      "--api-key",
+      "sk-never-stored",
+      "--root",
+      tmpRoot,
+    ]);
+    expect(bad.code).not.toBe(0);
+    expect(bad.err).toContain("--provider");
+    // The credential must not have landed on a guessed vendor: nothing was persisted at all.
+    await expect(fs.access(projectConfigPath(tmpRoot, DEFAULT_PROJECT_ID))).rejects.toThrow();
+  });
+
  it("dangling reference: the pair is not in models; the error carries the pair reference and a model list hint", async () => {
    const bad = await runModel([
      "default",
@@ -0,0 +1,106 @@
+/**
+ * `penguin run` / `penguin chat`: a model reference is always an explicit
+ * (provider, model_id) pair. Commander can only mark each option required on its own, so
+ * the "both or neither" rule is enforced inside the action — supplying exactly one of
+ * --model-id / --provider is a usage error (never a lookup against the configured models),
+ * while supplying neither falls back to the Project's default model.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Command } from "commander";
+import { registerChatCommand } from "../src/commands/chat.js";
+import { registerRunCommand } from "../src/commands/run.js";
+import { getMessages } from "../src/i18n.js";
+
+// The --resume case below reaches createAgent, which initializes Agent state on disk; point
+// the data root at a throwaway directory so no test ever writes to the real ~/.penguin/data.
+let tmpHome: string;
+let prevHome: string | undefined;
+
+beforeEach(async () => {
+  prevHome = process.env.PENGUIN_HOME;
+  tmpHome = await fs.mkdtemp(path.join(os.tmpdir(), "penguin-cli-pairing-"));
+  process.env.PENGUIN_HOME = tmpHome;
+});
+
+afterEach(async () => {
+  if (prevHome === undefined) delete process.env.PENGUIN_HOME;
+  else process.env.PENGUIN_HOME = prevHome;
+  await fs.rm(tmpHome, { recursive: true, force: true });
+});
+
+/** Runs one command, capturing stdout / stderr and the exit code (without exiting the process). */
+async function runCommand(
+  register: (program: Command, t: ReturnType<typeof getMessages>) => void,
+  args: string[],
+): Promise<{ out: string; err: string; code: number }> {
+  const program = new Command();
+  program.exitOverride();
+  register(program, getMessages("en"));
+  const out: string[] = [];
+  const err: string[] = [];
+  const outSpy = vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+    out.push(String(chunk));
+    return true;
+  });
+  const errSpy = vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+    err.push(String(chunk));
+    return true;
+  });
+  const prevExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await program.parseAsync(["node", "penguin", ...args]);
+    return { out: out.join(""), err: err.join(""), code: Number(process.exitCode ?? 0) };
+  } catch (e) {
+    const exitCode = (e as { exitCode?: number }).exitCode;
+    return { out: out.join(""), err: err.join(""), code: exitCode || 1 };
+  } finally {
+    outSpy.mockRestore();
+    errSpy.mockRestore();
+    process.exitCode = prevExitCode;
+  }
+}
+
+describe("run: --model-id and --provider must be given together", () => {
+  it("--model-id without --provider: error on stderr, exit code 1", async () => {
+    const bad = await runCommand(registerRunCommand, [
+      "run",
+      "-m",
+      "hi",
+      "--model-id",
+      "deepseek-v4-flash",
+    ]);
+    expect(bad.code).toBe(1);
+    expect(bad.err).toContain("--model-id and --provider must be given together");
+  });
+
+  it("--provider without --model-id: same error (the pair is never half-specified)", async () => {
+    const bad = await runCommand(registerRunCommand, ["run", "-m", "hi", "--provider", "deepseek"]);
+    expect(bad.code).toBe(1);
+    expect(bad.err).toContain("--model-id and --provider must be given together");
+  });
+});
+
+describe("chat: --model-id and --provider must be given together", () => {
+  it("--model-id without --provider: error on stderr, exit code 1", async () => {
+    const bad = await runCommand(registerChatCommand, ["chat", "--model-id", "deepseek-v4-flash"]);
+    expect(bad.code).toBe(1);
+    expect(bad.err).toContain("--model-id and --provider must be given together");
+  });
+
+  it("--resume plus a lone --model-id keeps the more specific resume error", async () => {
+    const bad = await runCommand(registerChatCommand, [
+      "chat",
+      "--resume",
+      "sess-1",
+      "--model-id",
+      "deepseek-v4-flash",
+    ]);
+    expect(bad.code).toBe(1);
+    expect(bad.out).toContain("--resume does not accept");
+    expect(`${bad.out}${bad.err}`).not.toContain("must be given together");
+  });
+});