@nebutra/agent-runtime 0.2.1 → 2.0.0

package/src/skills.test.ts

@@ -1,277 +0,0 @@
-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

@@ -1,277 +0,0 @@
-/**
- * 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 { estimateTokens as estimatePrimitiveTokens } from "@nebutra/ai-primitives";
-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 REGEX_META_CHARS = new Set([
-  ".",
-  "+",
-  "?",
-  "^",
-  "$",
-  "{",
-  "}",
-  "(",
-  ")",
-  "|",
-  "[",
-  "]",
-  "\\",
-]);
-
-const isFirstParty = (s: SkillRecord): boolean => FIRST_PARTY_TIERS.has(s.sourceTier);
-
-/**
- * Listing budgets preserve the catalog degradation contract: very tight lower-
- * tier budgets should still degrade to names-only before dropping. Context
- * compaction uses the corrected 1.3 estimate; this listing surface deliberately
- * uses the shared primitive with no correction.
- */
-const estimateListingTokens = (text: string): number =>
-  estimatePrimitiveTokens(text, { correction: 1 });
-
-// ── 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>;
-
-/** 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.charAt(i);
-    if (c === "*") {
-      if (glob[i + 1] === "*") {
-        out += ".*";
-        i++;
-      } else {
-        out += "[^/]*";
-      }
-    } else if (REGEX_META_CHARS.has(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 += estimateListingTokens(renderEntry(entry));
-      continue;
-    }
-
-    const full: SkillListingEntry = {
-      name: fm.name,
-      description: fullDesc,
-      whenToUse: fm.whenToUse,
-      degraded: false,
-      firstParty: false,
-    };
-    const fullCost = estimateListingTokens(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 = estimateListingTokens(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,
-  };
-}