@nebutra/agent-runtime 0.2.0

package/src/skills.test.ts

@@ -0,0 +1,277 @@
+import { describe, expect, it, vi } from "vitest";
+import { DefinitionResolver } from "./definitions";
+import { buildSkillListing, expandSkill, type SkillRecord } from "./skills";
+
+const skill = (
+  over: Partial<SkillRecord> &
+    Pick<SkillRecord, "slug" | "tenantId" | "sourceTier"> & {
+      name?: string;
+      description?: string;
+      whenToUse?: string;
+      allowedTools?: string[];
+      model?: string;
+      effort?: "low" | "medium" | "high";
+      executionMode?: "inline" | "fork";
+      paths?: string[];
+    },
+): SkillRecord => ({
+  bodyRef: over.bodyRef ?? `${over.slug}.body`,
+  ...over,
+  frontmatter: {
+    name: over.name ?? over.slug,
+    description: over.description ?? "",
+    allowedTools: over.allowedTools ?? [],
+    disallowedTools: [],
+    argNames: [],
+    modelInvocable: true,
+    userInvocable: true,
+    executionMode: over.executionMode ?? "inline",
+    paths: over.paths ?? [],
+    whenToUse: over.whenToUse,
+    model: over.model,
+    effort: over.effort,
+  },
+});
+
+describe("buildSkillListing", () => {
+  it("lists only name/description/whenToUse per skill", () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({
+        slug: "deploy",
+        tenantId: "t",
+        sourceTier: "workspace",
+        description: "ship it",
+        whenToUse: "when releasing",
+      }),
+    ]);
+    const out = buildSkillListing(r, { tenantId: "t" });
+    expect(out.entries).toHaveLength(1);
+    expect(out.entries[0]).toMatchObject({
+      name: "deploy",
+      description: "ship it",
+      whenToUse: "when releasing",
+    });
+    expect(out.text).toContain("deploy");
+    expect(out.text).toContain("ship it");
+  });
+
+  it("truncates per-entry description to maxListingDescChars", () => {
+    const long = "x".repeat(500);
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "a", tenantId: "t", sourceTier: "workspace", description: long }),
+    ]);
+    const out = buildSkillListing(r, { tenantId: "t" }, { maxListingDescChars: 10 });
+    expect(out.entries[0]?.description.length).toBeLessThanOrEqual(10);
+  });
+
+  it("first-party (bundled/builtin) is never truncated and always included even past budget", () => {
+    const long = "y".repeat(400);
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "fp", tenantId: "t", sourceTier: "bundled", description: long }),
+      skill({ slug: "lo", tenantId: "t", sourceTier: "workspace", description: long }),
+    ]);
+    const out = buildSkillListing(
+      r,
+      { tenantId: "t" },
+      { contextWindowTokens: 1, budgetPercent: 0.01, maxListingDescChars: 1000 },
+    );
+    const fp = out.entries.find((e) => e.name === "fp");
+    expect(fp).toBeDefined();
+    expect(fp?.description).toBe(long);
+    expect(fp?.degraded).toBe(false);
+  });
+
+  it("lower-tier skills degrade to names-only then drop when budget exceeded", () => {
+    const long = "z".repeat(400);
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "s1", tenantId: "t", sourceTier: "workspace", description: long }),
+      skill({ slug: "s2", tenantId: "t", sourceTier: "workspace", description: long }),
+      skill({ slug: "s3", tenantId: "t", sourceTier: "workspace", description: long }),
+    ]);
+    const tight = buildSkillListing(
+      r,
+      { tenantId: "t" },
+      { contextWindowTokens: 100, budgetPercent: 0.01, maxListingDescChars: 1000 },
+    );
+    // some degrade to names-only (no description)
+    expect(tight.entries.some((e) => e.degraded && e.description === "")).toBe(true);
+
+    const veryTight = buildSkillListing(
+      r,
+      { tenantId: "t" },
+      { contextWindowTokens: 1, budgetPercent: 0.01, maxListingDescChars: 1000 },
+    );
+    // beyond names-only, lower-tier entries drop entirely
+    expect(veryTight.entries.length).toBeLessThan(3);
+    expect(tight.entries.length).toBeGreaterThanOrEqual(veryTight.entries.length);
+  });
+
+  it("suppresses skills whose slug is in ctx.loadedSlugs", () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "loaded", tenantId: "t", sourceTier: "workspace" }),
+      skill({ slug: "fresh", tenantId: "t", sourceTier: "workspace" }),
+    ]);
+    const out = buildSkillListing(r, {
+      tenantId: "t",
+      loadedSlugs: new Set(["loaded"]),
+    });
+    expect(out.entries.map((e) => e.name)).toEqual(["fresh"]);
+  });
+
+  it("path-activated skills hidden until a touched path matches its glob", () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({
+        slug: "gated",
+        tenantId: "t",
+        sourceTier: "workspace",
+        paths: ["src/**/*.ts"],
+      }),
+      skill({ slug: "always", tenantId: "t", sourceTier: "workspace" }),
+    ]);
+    const hidden = buildSkillListing(r, { tenantId: "t" });
+    expect(hidden.entries.map((e) => e.name)).toEqual(["always"]);
+
+    const shown = buildSkillListing(r, { tenantId: "t" }, { touchedPaths: ["src/foo/bar.ts"] });
+    expect(shown.entries.map((e) => e.name).sort()).toEqual(["always", "gated"]);
+  });
+
+  it("glob supports *, ** and exact match", () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "star", tenantId: "t", sourceTier: "workspace", paths: ["*.md"] }),
+      skill({ slug: "exact", tenantId: "t", sourceTier: "workspace", paths: ["a/b.txt"] }),
+    ]);
+    const a = buildSkillListing(r, { tenantId: "t" }, { touchedPaths: ["README.md"] });
+    expect(a.entries.map((e) => e.name)).toEqual(["star"]);
+    const b = buildSkillListing(r, { tenantId: "t" }, { touchedPaths: ["a/b.txt"] });
+    expect(b.entries.map((e) => e.name)).toEqual(["exact"]);
+    const none = buildSkillListing(r, { tenantId: "t" }, { touchedPaths: ["a/c.txt"] });
+    expect(none.entries).toHaveLength(0);
+  });
+
+  it("empty tenant fails closed", () => {
+    const r = new DefinitionResolver<SkillRecord>([]);
+    expect(() => buildSkillListing(r, { tenantId: "" })).toThrow(/tenant/i);
+  });
+
+  it("cross-tenant isolation (resolver enforced)", () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "a", tenantId: "t_a", sourceTier: "workspace" }),
+    ]);
+    expect(buildSkillListing(r, { tenantId: "t_b" }).entries).toHaveLength(0);
+  });
+
+  it("is deterministic — same inputs produce same output", () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "a", tenantId: "t", sourceTier: "workspace", description: "aa" }),
+      skill({ slug: "b", tenantId: "t", sourceTier: "workspace", description: "bb" }),
+    ]);
+    const o1 = buildSkillListing(r, { tenantId: "t" });
+    const o2 = buildSkillListing(r, { tenantId: "t" });
+    expect(o1.text).toBe(o2.text);
+  });
+});
+
+describe("expandSkill", () => {
+  const base = (slug: string) => `/skills/${slug}`;
+
+  it("expands body, prepends resource base line, substitutes args + vars", async () => {
+    const s = skill({
+      slug: "deploy",
+      tenantId: "t",
+      sourceTier: "workspace",
+      allowedTools: ["Bash", "Edit"],
+    });
+    const bodyLoader = vi.fn(async () => "deploy ${env} via ${SESSION}");
+    const out = await expandSkill(s, {
+      tenantId: "t",
+      args: { env: "prod" },
+      vars: { SESSION: "s1" },
+      bodyLoader,
+      skillResourceBase: base,
+    });
+    expect(bodyLoader).toHaveBeenCalledTimes(1);
+    expect(bodyLoader).toHaveBeenCalledWith("deploy.body");
+    const content = out.messages.map((m) => m.content).join("\n");
+    expect(content).toContain("Base directory for this skill: /skills/deploy");
+    expect(content).toContain("deploy prod via s1");
+    expect(out.allowedTools).toEqual(["Bash", "Edit"]);
+    expect(out.executionMode).toBe("inline");
+  });
+
+  it("returns model override + effort + fork mode", async () => {
+    const s = skill({
+      slug: "heavy",
+      tenantId: "t",
+      sourceTier: "workspace",
+      model: "big-model",
+      effort: "high",
+      executionMode: "fork",
+    });
+    const out = await expandSkill(s, {
+      tenantId: "t",
+      args: {},
+      vars: {},
+      bodyLoader: async () => "body",
+      skillResourceBase: base,
+    });
+    expect(out.modelOverride).toBe("big-model");
+    expect(out.effort).toBe("high");
+    expect(out.executionMode).toBe("fork");
+  });
+
+  it("body loader is lazy — only invoked on expand", async () => {
+    const r = new DefinitionResolver<SkillRecord>([
+      skill({ slug: "lazy", tenantId: "t", sourceTier: "workspace" }),
+    ]);
+    const bodyLoader = vi.fn(async () => "b");
+    buildSkillListing(r, { tenantId: "t" });
+    expect(bodyLoader).not.toHaveBeenCalled();
+    await expandSkill(r.resolveOne("lazy", { tenantId: "t" })!, {
+      tenantId: "t",
+      args: {},
+      vars: {},
+      bodyLoader,
+      skillResourceBase: base,
+    });
+    expect(bodyLoader).toHaveBeenCalledTimes(1);
+  });
+
+  it("empty tenant fails closed on expand", async () => {
+    const s = skill({ slug: "x", tenantId: "t", sourceTier: "workspace" });
+    await expect(
+      expandSkill(s, {
+        tenantId: "",
+        args: {},
+        vars: {},
+        bodyLoader: async () => "b",
+        skillResourceBase: base,
+      }),
+    ).rejects.toThrow(/tenant/i);
+  });
+
+  it("cross-tenant expand fails closed", async () => {
+    const s = skill({ slug: "x", tenantId: "t_a", sourceTier: "workspace" });
+    await expect(
+      expandSkill(s, {
+        tenantId: "t_b",
+        args: {},
+        vars: {},
+        bodyLoader: async () => "b",
+        skillResourceBase: base,
+      }),
+    ).rejects.toThrow(/tenant/i);
+  });
+
+  it("does not execute any shell from the body (no command substitution)", async () => {
+    const s = skill({ slug: "x", tenantId: "t", sourceTier: "workspace" });
+    const out = await expandSkill(s, {
+      tenantId: "t",
+      args: {},
+      vars: {},
+      bodyLoader: async () => "literal !`rm -rf /` stays literal",
+      skillResourceBase: base,
+    });
+    const content = out.messages.map((m) => m.content).join("\n");
+    expect(content).toContain("!`rm -rf /`");
+  });
+});

package/src/skills.ts

@@ -0,0 +1,255 @@
+/**
+ * Skills system (WRAP — progressive-disclosure capability).
+ *
+ * Faithful re-expression of the source harness's two-phase skill model:
+ *
+ *   Phase 1 — Listing (cheap, always in context): a budget-bounded catalog
+ *     exposing only {name, description, whenToUse} per skill. First-party
+ *     skills (bundled/builtin tier) are never truncated and never dropped;
+ *     lower-tier skills degrade to names-only, then drop, as the context
+ *     budget is exhausted. Path-activated skills stay hidden until a touched
+ *     file matches one of their globs.
+ *
+ *   Phase 2 — Invocation (lazy, on demand): expand the chosen skill's body
+ *     into turn messages, with arg/var substitution and a merged tool
+ *     allowlist contributed to the permission context.
+ *
+ * A skill IS a `Definition` — the same tenant-scoped layered resolver backs
+ * the command registry and the subagent registry (see ./definitions).
+ *
+ * SECURITY: this re-expression intentionally drops the source's body-side
+ * command-substitution (the upstream "!`…`" inline-shell facility). Skill
+ * bodies are inert text; they NEVER trigger host shell execution here. All
+ * entry points require a non-empty `tenantId` and fail closed; cross-tenant
+ * inputs are rejected by the underlying `DefinitionResolver`. Pure data/logic
+ * — no host filesystem access (resource base is an injected indirection).
+ */
+
+import { z } from "zod";
+import {
+  type Definition,
+  type DefinitionResolver,
+  type ResolveContext,
+  substituteArguments,
+} from "./definitions";
+
+/** A skill is just a resolvable `Definition`. */
+export type SkillRecord = Definition;
+
+/** Tiers treated as first-party (never truncated, never dropped). */
+const FIRST_PARTY_TIERS: ReadonlySet<string> = new Set(["bundled", "builtin"]);
+
+const isFirstParty = (s: SkillRecord): boolean => FIRST_PARTY_TIERS.has(s.sourceTier);
+
+// ── Phase 1: listing ─────────────────────────────────────────────────────────
+
+/** One catalog entry — only the cheap, always-in-context surface. */
+export interface SkillListingEntry {
+  readonly name: string;
+  readonly description: string;
+  readonly whenToUse?: string | undefined;
+  /** True when this entry was degraded to names-only by the budget. */
+  readonly degraded: boolean;
+  readonly firstParty: boolean;
+}
+
+export interface SkillListing {
+  readonly entries: readonly SkillListingEntry[];
+  readonly text: string;
+}
+
+const listingOptionsSchema = z.object({
+  maxListingDescChars: z.number().int().positive().default(250),
+  contextWindowTokens: z.number().int().positive().default(200_000),
+  budgetPercent: z.number().positive().max(1).default(0.01),
+  touchedPaths: z.array(z.string()).default([]),
+});
+export type SkillListingOptions = z.input<typeof listingOptionsSchema>;
+
+/** Cheap, deterministic token estimate (≈4 chars/token). */
+const estimateTokens = (text: string): number => Math.ceil(text.length / 4);
+
+/** Minimal glob: `**` = any chars, `*` = any chars except `/`, else exact. */
+function globToRegExp(glob: string): RegExp {
+  let out = "^";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]!;
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        out += ".*";
+        i++;
+      } else {
+        out += "[^/]*";
+      }
+    } else if (".+?^${}()|[]\\".includes(c)) {
+      out += `\\${c}`;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp(`${out}$`);
+}
+
+const pathMatches = (globs: readonly string[], touched: readonly string[]): boolean =>
+  globs.some((g) => {
+    const re = globToRegExp(g);
+    return touched.some((p) => re.test(p));
+  });
+
+/** Stable order: first-party first, then by slug — deterministic output. */
+function orderSkills(skills: readonly SkillRecord[]): SkillRecord[] {
+  return [...skills].sort((a, b) => {
+    const fa = isFirstParty(a) ? 0 : 1;
+    const fb = isFirstParty(b) ? 0 : 1;
+    if (fa !== fb) return fa - fb;
+    return a.slug.localeCompare(b.slug);
+  });
+}
+
+const truncate = (s: string, max: number): string => (s.length <= max ? s : s.slice(0, max));
+
+function renderEntry(e: SkillListingEntry): string {
+  const head = e.whenToUse ? `- ${e.name} — ${e.whenToUse}` : `- ${e.name}`;
+  return e.description ? `${head}\n  ${e.description}` : head;
+}
+
+/**
+ * Phase 1 — build the always-in-context skill catalog. Pure & deterministic.
+ *
+ * Budget = `contextWindowTokens * budgetPercent`. First-party skills are
+ * emitted in full and do NOT consume budget against being dropped. Each
+ * remaining skill is tried at full description; if it would overflow it is
+ * degraded to names-only; if even that overflows it is dropped. Skills in
+ * `ctx.loadedSlugs` and unactivated path-gated skills are suppressed.
+ */
+export function buildSkillListing(
+  resolver: DefinitionResolver<SkillRecord>,
+  ctx: ResolveContext,
+  options: SkillListingOptions = {},
+): SkillListing {
+  if (!ctx.tenantId) throw new Error("buildSkillListing: tenantId is required");
+  const opts = listingOptionsSchema.parse(options);
+
+  const loaded = ctx.loadedSlugs ?? new Set<string>();
+  const visible = resolver
+    .resolve(ctx)
+    .filter((s) => !loaded.has(s.slug))
+    .filter((s) => {
+      const paths = s.frontmatter.paths;
+      return paths.length === 0 || pathMatches(paths, opts.touchedPaths);
+    });
+
+  const budget = Math.max(1, Math.floor(opts.contextWindowTokens * opts.budgetPercent));
+
+  const entries: SkillListingEntry[] = [];
+  let used = 0;
+
+  for (const s of orderSkills(visible)) {
+    const fp = isFirstParty(s);
+    const fm = s.frontmatter;
+    const fullDesc = fp ? fm.description : truncate(fm.description, opts.maxListingDescChars);
+
+    if (fp) {
+      const entry: SkillListingEntry = {
+        name: fm.name,
+        description: fm.description,
+        whenToUse: fm.whenToUse,
+        degraded: false,
+        firstParty: true,
+      };
+      entries.push(entry);
+      used += estimateTokens(renderEntry(entry));
+      continue;
+    }
+
+    const full: SkillListingEntry = {
+      name: fm.name,
+      description: fullDesc,
+      whenToUse: fm.whenToUse,
+      degraded: false,
+      firstParty: false,
+    };
+    const fullCost = estimateTokens(renderEntry(full));
+    if (used + fullCost <= budget) {
+      entries.push(full);
+      used += fullCost;
+      continue;
+    }
+
+    const nameOnly: SkillListingEntry = {
+      name: fm.name,
+      description: "",
+      whenToUse: undefined,
+      degraded: true,
+      firstParty: false,
+    };
+    const nameCost = estimateTokens(renderEntry(nameOnly));
+    if (used + nameCost <= budget) {
+      entries.push(nameOnly);
+      used += nameCost;
+    }
+    // else: drop entirely.
+  }
+
+  const text = entries.map(renderEntry).join("\n");
+  return { entries, text };
+}
+
+// ── Phase 2: invocation ──────────────────────────────────────────────────────
+
+export interface SkillMessage {
+  readonly role: "system" | "user";
+  readonly content: string;
+}
+
+export interface ExpandedSkill {
+  readonly messages: readonly SkillMessage[];
+  readonly allowedTools: readonly string[];
+  readonly modelOverride?: string | undefined;
+  readonly effort?: "low" | "medium" | "high" | undefined;
+  readonly executionMode: "inline" | "fork";
+}
+
+export interface ExpandContext {
+  readonly tenantId: string;
+  readonly args: Record<string, string>;
+  readonly vars: Record<string, string>;
+  /** Lazy body fetch — host supplies; called only here, only once. */
+  readonly bodyLoader: (bodyRef: string) => Promise<string>;
+  /** Host-injected resource-base indirection (NO host FS access here). */
+  readonly skillResourceBase: (slug: string) => string;
+}
+
+/**
+ * Phase 2 — expand a skill into turn messages. Body is loaded lazily via the
+ * injected `bodyLoader` (never during listing). A `Base directory…` line is
+ * prepended via the injected `skillResourceBase` indirection. Args + vars are
+ * substituted with `substituteArguments`. The skill's `allowedTools` are
+ * returned for the caller to merge into the permission context — this never
+ * mutates global state and never executes anything from the body.
+ */
+export async function expandSkill(skill: SkillRecord, ctx: ExpandContext): Promise<ExpandedSkill> {
+  if (!ctx.tenantId) throw new Error("expandSkill: tenantId is required");
+  if (skill.tenantId !== ctx.tenantId) {
+    throw new Error("expandSkill: cross-tenant skill access rejected");
+  }
+
+  const rawBody = await ctx.bodyLoader(skill.bodyRef);
+  const body = substituteArguments(rawBody, ctx.args, ctx.vars);
+  const baseLine = `Base directory for this skill: ${ctx.skillResourceBase(skill.slug)}`;
+
+  const messages: readonly SkillMessage[] = [
+    { role: "system", content: baseLine },
+    { role: "user", content: body },
+  ];
+
+  const allowedTools = [...skill.frontmatter.allowedTools];
+
+  return {
+    messages,
+    allowedTools,
+    modelOverride: skill.frontmatter.model,
+    effort: skill.frontmatter.effort,
+    executionMode: skill.frontmatter.executionMode,
+  };
+}