@nebutra/agent-runtime 0.2.0 → 0.2.2

package/src/commands.test.ts

@@ -1,184 +0,0 @@
-/**
- * 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

@@ -1,140 +0,0 @@
-/**
- * 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

@@ -1,249 +0,0 @@
-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");
-  });
-});