@nebutra/agent-runtime 0.2.0

package/src/commands.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tests for the slash-command registry — the unified command model.
+ *
+ * A command IS a Definition. Slash invocation and model invocation are two
+ * front-doors to one expansion. Tier precedence + dual gate are delegated to
+ * DefinitionResolver (asserted to work through the wrapper). Multi-tenant:
+ * tenantId mandatory, fail-closed, cross-tenant impossible.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { CommandRecord } from "./commands";
+import { CommandRegistry, expandCommand } from "./commands";
+import type { Frontmatter, SourceTier } from "./definitions";
+
+function fm(over: Partial<Frontmatter> = {}): Frontmatter {
+  return {
+    name: over.name ?? "cmd",
+    description: "",
+    allowedTools: [],
+    disallowedTools: [],
+    argNames: [],
+    modelInvocable: true,
+    userInvocable: true,
+    executionMode: "inline",
+    paths: [],
+    ...over,
+  };
+}
+
+function rec(over: Partial<CommandRecord> & { slug: string; tenantId: string }): CommandRecord {
+  return {
+    sourceTier: "workspace" as SourceTier,
+    bodyRef: `body:${over.slug}`,
+    frontmatter: fm(over.frontmatter),
+    ...over,
+  };
+}
+
+describe("CommandRegistry — two front-doors to one record", () => {
+  it("resolves the same record via both listForUser and listForModel", () => {
+    const reg = new CommandRegistry([rec({ slug: "deploy", tenantId: "t1" })]);
+    const u = reg.listForUser({ tenantId: "t1" });
+    const m = reg.listForModel({ tenantId: "t1" });
+    expect(u.map((c) => c.slug)).toEqual(["deploy"]);
+    expect(m.map((c) => c.slug)).toEqual(["deploy"]);
+  });
+
+  it("hides userInvocable:false from listForUser but keeps it in listForModel", () => {
+    const reg = new CommandRegistry([
+      rec({ slug: "auto-only", tenantId: "t1", frontmatter: fm({ userInvocable: false }) }),
+    ]);
+    expect(reg.listForUser({ tenantId: "t1" })).toHaveLength(0);
+    expect(reg.listForModel({ tenantId: "t1" }).map((c) => c.slug)).toEqual(["auto-only"]);
+  });
+
+  it("hides modelInvocable:false from listForModel but keeps it in listForUser", () => {
+    const reg = new CommandRegistry([
+      rec({ slug: "human-only", tenantId: "t1", frontmatter: fm({ modelInvocable: false }) }),
+    ]);
+    expect(reg.listForModel({ tenantId: "t1" })).toHaveLength(0);
+    expect(reg.listForUser({ tenantId: "t1" }).map((c) => c.slug)).toEqual(["human-only"]);
+  });
+
+  it("recomputes per call so entitlement/flag changes apply live", () => {
+    const r = rec({ slug: "gated", tenantId: "t1", availabilityPlans: ["pro"] });
+    const reg = new CommandRegistry([r]);
+    expect(reg.listForUser({ tenantId: "t1" })).toHaveLength(0);
+    expect(reg.listForUser({ tenantId: "t1", plan: "pro" }).map((c) => c.slug)).toEqual(["gated"]);
+  });
+});
+
+describe("CommandRegistry — delegated tier precedence + dual gate", () => {
+  it("higher tier overrides lower on slug collision (through the wrapper)", () => {
+    const reg = new CommandRegistry([
+      rec({ slug: "x", tenantId: "t1", sourceTier: "workspace", bodyRef: "low" }),
+      rec({ slug: "x", tenantId: "t1", sourceTier: "policy", bodyRef: "high" }),
+    ]);
+    const [c] = reg.listForUser({ tenantId: "t1" });
+    expect(c?.bodyRef).toBe("high");
+  });
+
+  it("dual gate: enabled:false suppressed through the wrapper", () => {
+    const reg = new CommandRegistry([rec({ slug: "off", tenantId: "t1", enabled: false })]);
+    expect(reg.listForUser({ tenantId: "t1" })).toHaveLength(0);
+    expect(reg.listForModel({ tenantId: "t1" })).toHaveLength(0);
+  });
+
+  it("resolveOne returns highest-precedence gated record", () => {
+    const reg = new CommandRegistry([
+      rec({ slug: "y", tenantId: "t1", sourceTier: "bundled", bodyRef: "lo" }),
+      rec({ slug: "y", tenantId: "t1", sourceTier: "plugin", bodyRef: "hi" }),
+    ]);
+    expect(reg.resolveOne("y", { tenantId: "t1" })?.bodyRef).toBe("hi");
+    expect(reg.resolveOne("missing", { tenantId: "t1" })).toBeUndefined();
+  });
+});
+
+describe("CommandRegistry — multi-tenant fail-closed", () => {
+  it("throws on empty tenantId at every entry point", () => {
+    const reg = new CommandRegistry([rec({ slug: "a", tenantId: "t1" })]);
+    expect(() => reg.listForUser({ tenantId: "" })).toThrow();
+    expect(() => reg.listForModel({ tenantId: "" })).toThrow();
+    expect(() => reg.resolveOne("a", { tenantId: "" })).toThrow();
+  });
+
+  it("never leaks another tenant's commands", () => {
+    const reg = new CommandRegistry([
+      rec({ slug: "secret", tenantId: "t2" }),
+      rec({ slug: "mine", tenantId: "t1" }),
+    ]);
+    expect(reg.listForUser({ tenantId: "t1" }).map((c) => c.slug)).toEqual(["mine"]);
+    expect(reg.resolveOne("secret", { tenantId: "t1" })).toBeUndefined();
+  });
+});
+
+describe("expandCommand — pure prompt expansion", () => {
+  it("splits positional input into argNames and substitutes into the body", async () => {
+    const cmd = rec({
+      slug: "greet",
+      tenantId: "t1",
+      frontmatter: fm({ argNames: ["who", "when"] }),
+    });
+    const loader = vi.fn(async () => "Hi ${who} at ${when} in ${workspace}");
+    const out = await expandCommand(cmd, "alice noon", { workspace: "/repo" }, loader);
+    expect(out.contentBlocks).toEqual([{ role: "user", content: "Hi alice at noon in /repo" }]);
+  });
+
+  it("folds extra positional args into the last declared arg", async () => {
+    const cmd = rec({
+      slug: "echo",
+      tenantId: "t1",
+      frontmatter: fm({ argNames: ["first", "rest"] }),
+    });
+    const loader = vi.fn(async () => "[${first}] [${rest}]");
+    const out = await expandCommand(cmd, "one two three four", {}, loader);
+    expect(out.contentBlocks[0]?.content).toBe("[one] [two three four]");
+  });
+
+  it("uses injected variables, not host env", async () => {
+    process.env.LEAK_SECRET = "should-not-appear";
+    const cmd = rec({ slug: "v", tenantId: "t1" });
+    const loader = vi.fn(async () => "session=${sessionId} leak=${LEAK_SECRET}");
+    const out = await expandCommand(cmd, "", { sessionId: "s-42" }, loader);
+    expect(out.contentBlocks[0]?.content).toBe("session=s-42 leak=");
+    delete process.env.LEAK_SECRET;
+  });
+
+  it("calls the lazy bodyLoader exactly once", async () => {
+    const cmd = rec({ slug: "lazy", tenantId: "t1" });
+    const loader = vi.fn(async () => "static body");
+    await expandCommand(cmd, "", {}, loader);
+    expect(loader).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns declared allowedTools, model override, effort and execution mode", async () => {
+    const cmd = rec({
+      slug: "deploy",
+      tenantId: "t1",
+      frontmatter: fm({
+        allowedTools: ["Bash", "Read"],
+        model: "opus",
+        effort: "high",
+        executionMode: "fork",
+      }),
+    });
+    const out = await expandCommand(cmd, "", {}, async () => "go");
+    expect(out.allowedTools).toEqual(["Bash", "Read"]);
+    expect(out.modelOverride).toBe("opus");
+    expect(out.effort).toBe("high");
+    expect(out.executionMode).toBe("fork");
+  });
+
+  it("omits modelOverride when frontmatter.model is 'inherit' or unset", async () => {
+    const cmd = rec({ slug: "p", tenantId: "t1", frontmatter: fm({ model: "inherit" }) });
+    const out = await expandCommand(cmd, "", {}, async () => "x");
+    expect(out.modelOverride).toBeUndefined();
+  });
+
+  it("returned contentBlocks array is frozen (immutability)", async () => {
+    const cmd = rec({ slug: "f", tenantId: "t1" });
+    const out = await expandCommand(cmd, "", {}, async () => "y");
+    expect(Object.isFrozen(out.contentBlocks)).toBe(true);
+  });
+});

package/src/commands.ts

@@ -0,0 +1,140 @@
+/**
+ * Slash-command registry — faithful re-expression of the unified command model.
+ *
+ * Semantic model:
+ *  - A command and a skill are the SAME underlying type. `CommandRecord` is just
+ *    a `Definition`. The only differences are carried in the record itself:
+ *    `sourceTier`, and the `userInvocable` / `modelInvocable` frontmatter flags.
+ *  - Slash invocation (a human types `/deploy`) and model invocation (the model
+ *    auto-triggers) are two FRONT-DOORS to ONE expansion path.
+ *  - The registry IS a `DefinitionResolver<CommandRecord>` (layered tier merge +
+ *    precedence + dual gate are provided by definitions.ts — reused, not rebuilt).
+ *    `CommandRegistry` is a thin wrapper exposing the two front-doors; both
+ *    recompute per call so entitlement/flag changes apply live.
+ *
+ * Scope note: the source harness also has `local` / `local-jsx` command kinds
+ * that run TUI-side JSX. Those are intentionally DROPPED here — a server runtime
+ * only needs the prompt-expansion path. This module models that path only.
+ *
+ * Multi-tenant: `tenantId` is mandatory at every entry point; an empty tenant
+ * throws (fail-closed); cross-tenant resolution is impossible (the underlying
+ * resolver rejects foreign-tenant records).
+ */
+
+import {
+  type Definition,
+  DefinitionResolver,
+  type ResolveContext,
+  substituteArguments,
+} from "./definitions";
+
+/**
+ * A command IS a Definition. No new fields — the distinction between "command"
+ * and "skill" is purely the `sourceTier` + invocability flags already present.
+ */
+export type CommandRecord = Definition;
+
+/** Lazily loads a command's body text (FS / blob / remote — caller's choice). */
+export type BodyLoader = (cmd: CommandRecord) => Promise<string>;
+
+/** One content block destined for the model turn. */
+export interface ContentBlock {
+  readonly role: "user";
+  readonly content: string;
+}
+
+/** Result of expanding a command — declarative only; no enforcement here. */
+export interface ExpandedCommand {
+  /** Prompt blocks to splice into the turn. */
+  readonly contentBlocks: readonly ContentBlock[];
+  /** Tools the command self-declares for the permission context. */
+  readonly allowedTools: readonly string[];
+  /** Model alias to switch to, if the command pins one (not "inherit"). */
+  readonly modelOverride?: string | undefined;
+  /** Reasoning effort hint, if declared. */
+  readonly effort?: "low" | "medium" | "high" | undefined;
+  /** inline = expand into current turn; fork = isolated child. */
+  readonly executionMode: "inline" | "fork";
+}
+
+/**
+ * Split a positional argument string across declared arg names. Extra tokens
+ * beyond the last declared name are folded into that last argument (matches the
+ * source's "rest goes to the last positional" behaviour). With no declared
+ * names the whole string is exposed as `${ARGUMENTS}` / `$1`.
+ */
+function bindArgs(input: string, argNames: readonly string[]): Record<string, string> {
+  const tokens = input.trim().length > 0 ? input.trim().split(/\s+/) : [];
+  const args: Record<string, string> = {};
+  if (argNames.length === 0) {
+    args.ARGUMENTS = input.trim();
+    args["1"] = input.trim();
+    return args;
+  }
+  argNames.forEach((name, i) => {
+    if (i === argNames.length - 1) {
+      args[name] = tokens.slice(i).join(" ");
+    } else {
+      args[name] = tokens[i] ?? "";
+    }
+  });
+  return args;
+}
+
+/**
+ * Pure expansion. Loads the body lazily (exactly once), substitutes named args
+ * and a tenant-safe variable map (only the explicitly injected `variables` —
+ * never `process.env`), and returns the declarative execution context.
+ */
+export async function expandCommand(
+  cmd: CommandRecord,
+  argInput: string,
+  variables: Readonly<Record<string, string>>,
+  bodyLoader: BodyLoader,
+): Promise<ExpandedCommand> {
+  const body = await bodyLoader(cmd);
+  const args = bindArgs(argInput, cmd.frontmatter.argNames);
+  // Only injected variables are visible — host env is deliberately excluded.
+  const content = substituteArguments(body, args, { ...variables });
+
+  const model = cmd.frontmatter.model;
+  const modelOverride = model && model !== "inherit" ? model : undefined;
+
+  return Object.freeze({
+    contentBlocks: Object.freeze([
+      Object.freeze({ role: "user" as const, content }),
+    ]) as readonly ContentBlock[],
+    allowedTools: Object.freeze([...cmd.frontmatter.allowedTools]),
+    modelOverride,
+    effort: cmd.frontmatter.effort,
+    executionMode: cmd.frontmatter.executionMode,
+  });
+}
+
+/**
+ * Thin tenant-scoped wrapper over `DefinitionResolver<CommandRecord>`. Exposes
+ * the two front-doors. Tier merge / precedence / dual gate / tenant isolation
+ * are delegated to the resolver — this class only filters by invocability.
+ */
+export class CommandRegistry {
+  readonly #resolver: DefinitionResolver<CommandRecord>;
+
+  constructor(commands: readonly CommandRecord[]) {
+    this.#resolver = new DefinitionResolver<CommandRecord>(commands);
+  }
+
+  /** Commands a human may type as a slash command. */
+  listForUser(ctx: ResolveContext): CommandRecord[] {
+    return this.#resolver.resolve(ctx).filter((c) => c.frontmatter.userInvocable !== false);
+  }
+
+  /** Commands the model may auto-trigger. */
+  listForModel(ctx: ResolveContext): CommandRecord[] {
+    return this.#resolver.resolve(ctx).filter((c) => c.frontmatter.modelInvocable !== false);
+  }
+
+  /** Highest-precedence gated record for a slug (no invocability filter). */
+  resolveOne(slug: string, ctx: ResolveContext): CommandRecord | undefined {
+    return this.#resolver.resolveOne(slug, ctx);
+  }
+}

package/src/commit-message.test.ts

@@ -0,0 +1,249 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildCommitPrompt,
+  CommitMessageError,
+  type CompletionModel,
+  DEFAULT_ABORT_MS,
+  DEFAULT_TEMPERATURE,
+  type GitContext,
+  generateCommitMessage,
+  MAX_RETRIES,
+  stripFormatting,
+} from "./commit-message.js";
+
+const ctx: GitContext = {
+  branch: "feat/access-invites",
+  recentCommits: ["feat(web): manage access invites", "chore(web): remove stale helper"],
+  files: [
+    { status: "M", path: "apps/web/src/invites.ts", diff: "@@ -1 +1 @@\n-old\n+new" },
+    { status: "A", path: "apps/web/src/invites.test.ts", diff: "@@ +1 @@\n+added" },
+  ],
+};
+
+/**
+ * Deterministic fake model. `script` yields one resolution per `complete()`
+ * call; an Error value is thrown (a "rejection"), a string is returned. Records
+ * every invocation so prompt/temperature/abort wiring can be asserted.
+ */
+class ScriptedModel implements CompletionModel {
+  #i = 0;
+  readonly calls: Array<{
+    system: string;
+    user: string;
+    temperature: number;
+    abortMs: number;
+  }> = [];
+  constructor(private readonly script: ReadonlyArray<string | Error>) {}
+  async complete(p: {
+    system: string;
+    user: string;
+    temperature: number;
+    abortMs: number;
+  }): Promise<string> {
+    this.calls.push({ ...p });
+    const step = this.script[this.#i] ?? this.script[this.script.length - 1];
+    this.#i += 1;
+    if (step instanceof Error) {
+      throw step;
+    }
+    return step as string;
+  }
+}
+
+describe("buildCommitPrompt", () => {
+  it("encodes the Conventional Commits type list in the system prompt", () => {
+    const { system } = buildCommitPrompt(ctx);
+    for (const t of [
+      "feat",
+      "fix",
+      "docs",
+      "style",
+      "refactor",
+      "perf",
+      "test",
+      "build",
+      "ci",
+      "chore",
+    ]) {
+      expect(system).toContain(t);
+    }
+  });
+
+  it("instructs imperative mood in the system prompt", () => {
+    const { system } = buildCommitPrompt(ctx);
+    expect(system.toLowerCase()).toContain("imperative");
+  });
+
+  it("instructs returning only the commit message (no fences/commentary)", () => {
+    const { system } = buildCommitPrompt(ctx);
+    const lower = system.toLowerCase();
+    expect(lower).toContain("only");
+    expect(lower).toContain("commit message");
+  });
+
+  it("describes the type(scope): subject shape", () => {
+    const { system } = buildCommitPrompt(ctx);
+    expect(system).toContain("type(scope): subject");
+  });
+
+  it("renders the branch into the user prompt", () => {
+    const { user } = buildCommitPrompt(ctx);
+    expect(user).toContain("feat/access-invites");
+  });
+
+  it("renders the recent commits into the user prompt", () => {
+    const { user } = buildCommitPrompt(ctx);
+    expect(user).toContain("feat(web): manage access invites");
+    expect(user).toContain("chore(web): remove stale helper");
+  });
+
+  it("renders per-file status, path, and diff into the user prompt", () => {
+    const { user } = buildCommitPrompt(ctx);
+    expect(user).toContain("M");
+    expect(user).toContain("apps/web/src/invites.ts");
+    expect(user).toContain("@@ -1 +1 @@");
+    expect(user).toContain("A");
+    expect(user).toContain("apps/web/src/invites.test.ts");
+  });
+
+  it("omits a negative-constraint block when no previous message is given", () => {
+    const { user } = buildCommitPrompt(ctx);
+    expect(user.toLowerCase()).not.toContain("already generated and rejected");
+  });
+
+  it("appends a negative-constraint block when previous is provided", () => {
+    const { user } = buildCommitPrompt(ctx, { previous: "feat: do the thing" });
+    expect(user.toLowerCase()).toContain("already generated and rejected");
+    expect(user).toContain("feat: do the thing");
+    expect(user.toLowerCase()).toContain("materially different");
+  });
+
+  it("treats an explicit undefined previous as 'no previous'", () => {
+    const { user } = buildCommitPrompt(ctx, { previous: undefined });
+    expect(user.toLowerCase()).not.toContain("already generated and rejected");
+  });
+});
+
+describe("stripFormatting", () => {
+  it("returns plain text untouched (only trimmed)", () => {
+    expect(stripFormatting("feat: add login")).toBe("feat: add login");
+  });
+
+  it("strips a plain triple-backtick fence", () => {
+    expect(stripFormatting("```\nfeat: add login\n```")).toBe("feat: add login");
+  });
+
+  it("strips a fence with a language tag", () => {
+    expect(stripFormatting("```text\nfeat: add login\n```")).toBe("feat: add login");
+    expect(stripFormatting("```bash\nfix: patch parser\n```")).toBe("fix: patch parser");
+  });
+
+  it("strips surrounding double quotes", () => {
+    expect(stripFormatting('"feat: add login"')).toBe("feat: add login");
+  });
+
+  it("strips surrounding single quotes", () => {
+    expect(stripFormatting("'feat: add login'")).toBe("feat: add login");
+  });
+
+  it("trims surrounding whitespace", () => {
+    expect(stripFormatting("   \n feat: add login \n  ")).toBe("feat: add login");
+  });
+
+  it("strips fence then trims inner content", () => {
+    expect(stripFormatting("```\n\n  fix: trim me  \n\n```")).toBe("fix: trim me");
+  });
+});
+
+describe("generateCommitMessage", () => {
+  it("returns the stripped message on a clean first response", async () => {
+    const model = new ScriptedModel(["```\nfeat(web): add invites\n```"]);
+    const msg = await generateCommitMessage({ ctx, model });
+    expect(msg).toBe("feat(web): add invites");
+    expect(model.calls).toHaveLength(1);
+  });
+
+  it("passes the default temperature and abort budget through to the model", async () => {
+    const model = new ScriptedModel(["feat: ok"]);
+    await generateCommitMessage({ ctx, model });
+    expect(model.calls[0]?.temperature).toBe(DEFAULT_TEMPERATURE);
+    expect(model.calls[0]?.abortMs).toBe(DEFAULT_ABORT_MS);
+    expect(DEFAULT_TEMPERATURE).toBe(0.3);
+    expect(DEFAULT_ABORT_MS).toBe(30000);
+  });
+
+  it("forwards the built prompt to the model", async () => {
+    const model = new ScriptedModel(["feat: ok"]);
+    await generateCommitMessage({ ctx, model });
+    expect(model.calls[0]?.user).toContain("feat/access-invites");
+    expect(model.calls[0]?.system).toContain("feat");
+  });
+
+  it("retries after a rejection then succeeds", async () => {
+    const model = new ScriptedModel([new Error("model unavailable"), "fix: recovered"]);
+    const msg = await generateCommitMessage({ ctx, model });
+    expect(msg).toBe("fix: recovered");
+    expect(model.calls).toHaveLength(2);
+  });
+
+  it("retries after empty/whitespace output then succeeds", async () => {
+    const model = new ScriptedModel(["   \n  ", "feat: now valid"]);
+    const msg = await generateCommitMessage({ ctx, model });
+    expect(msg).toBe("feat: now valid");
+    expect(model.calls).toHaveLength(2);
+  });
+
+  it("treats a fence wrapping only whitespace as empty and retries", async () => {
+    const model = new ScriptedModel(["```\n   \n```", "chore: real"]);
+    const msg = await generateCommitMessage({ ctx, model });
+    expect(msg).toBe("chore: real");
+    expect(model.calls).toHaveLength(2);
+  });
+
+  it("throws CommitMessageError after MAX_RETRIES exhausted (fail closed)", async () => {
+    const model = new ScriptedModel([new Error("down"), new Error("down"), new Error("down")]);
+    await expect(generateCommitMessage({ ctx, model })).rejects.toBeInstanceOf(CommitMessageError);
+    expect(model.calls).toHaveLength(MAX_RETRIES);
+    expect(MAX_RETRIES).toBe(3);
+  });
+
+  it("never returns an empty message — throws when every attempt is blank", async () => {
+    const model = new ScriptedModel(["", "  ", "```\n```"]);
+    await expect(generateCommitMessage({ ctx, model })).rejects.toBeInstanceOf(CommitMessageError);
+    expect(model.calls).toHaveLength(MAX_RETRIES);
+  });
+
+  it("threads the negative constraint through when opts.previous is set", async () => {
+    const model = new ScriptedModel(["feat: a different one"]);
+    await generateCommitMessage({
+      ctx,
+      model,
+      opts: { previous: "feat: the rejected one" },
+    });
+    expect(model.calls[0]?.user.toLowerCase()).toContain("already generated and rejected");
+    expect(model.calls[0]?.user).toContain("feat: the rejected one");
+  });
+
+  it("zod-rejects a context missing branch", async () => {
+    const model = new ScriptedModel(["feat: ok"]);
+    const bad = { recentCommits: [], files: [] } as unknown as GitContext;
+    await expect(generateCommitMessage({ ctx: bad, model })).rejects.toBeDefined();
+  });
+
+  it("zod-rejects a context whose files have the wrong shape", async () => {
+    const model = new ScriptedModel(["feat: ok"]);
+    const bad = {
+      branch: "main",
+      recentCommits: [],
+      files: [{ status: "M" }],
+    } as unknown as GitContext;
+    await expect(generateCommitMessage({ ctx: bad, model })).rejects.toBeDefined();
+  });
+
+  it("CommitMessageError is a typed Error subclass with a name", () => {
+    const err = new CommitMessageError("boom");
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe("CommitMessageError");
+    expect(err.message).toBe("boom");
+  });
+});