@nightowlsdev/agent-builder

Pre-built agents

The meta-agent that knows the nightowls agent anatomy end to end: researches external skills, drafts + validates agents/bundles, and, behind a rule-enforced human-approval floor, imports skills and publishes definitions.

What it does

@nightowlsdev/agent-builder ships an agent whose persona encodes the framework's own internals (agent anatomy, the three skill kinds, bundles, the actor model, with a compile-time staleness guard that fails this package's CI if core's shape changes). With no options it is DRAFT-ONLY: it designs and validates agents/bundles through the real defineAgent/defineBundle and a human applies the JSON. Give it providers + repos + a service actor and it gains gated tools: search_skills/preview_skill (never raw provider I/O, the skills package's policy gates run before any fetch; everything third-party arrives fenced), list/get_agent, import_skill/publish_agent/publish_bundle. The mutating tools are hard-coded needsApproval + failClosed AND floored to `ask` by a package-attached enforce-level rule, engine-tested that a permissive host hook cannot downgrade the gate, with your policyGuard running fail-closed before every repo call. The storage actor bar (agents can never mutate definitions) stays fully intact underneath: publishes run with YOUR service actor, only after a human approves that specific call.

Install

pnpm add @nightowlsdev/agent-builder

Key exports

createBuilder (draft-only safe default; capability tools appear with their dependencies)
builderApprovalRule (the enforce-level ask floor on the mutating tools)
AGENT_DRAFT_SCHEMA / BUNDLE_DRAFT_SCHEMA / validateAgentDraft / validateBundleDraft
manifest / BUILDER_CURATED_SKILLS (skill-creator, writing-skills, writing-great-skills, pinned)

Usage

agent-builder.ts

import { createBuilder } from "@nightowlsdev/agent-builder";
import { skillsShProvider } from "@nightowlsdev/skills";

// DRAFT-ONLY by default: designs + validates agents/bundles; a human applies the JSON.
const builder = createBuilder();

// Full capability: gated skill research + human-approved publishing. Every mutating call suspends
// for approval (an enforce-level rule a permissive host hook cannot downgrade), then runs YOUR
// service actor through your policyGuard, the agents-can-never-mutate storage bar stays intact.
const fullBuilder = createBuilder({
  providers: { "skills.sh": skillsShProvider() },
  storage: {
    skills: storage.skills, skillsWritable: storage.skillsWritable,
    agents: storage.agents, agentsWritable: storage.agentsWritable,
    bundles: storage.bundles, bundlesWritable: storage.bundlesWritable, // enables publish_bundle
  },
  actor: { type: "service", serviceId: "builder-host", tenantId },
  policy: { allowAuthors: ["anthropics", "vercel-labs", "coreyhaines31"] },
  policyGuard: (op) => assertOrgAllows(op),   // throw to deny, fail-closed
});

// PREREQUISITE: your host handles suspend/resume (approvals render as question cards).
// The full journey: /docs/adopt-prebuilt-agents