@hazeljs/cli 1.0.6 → 2.0.1

package/@template-ai-native/README.md

@@ -36,6 +36,25 @@ A complete AI-native backend application with HazelJS, featuring:
    - Inspector: http://localhost:3000/\_\_hazel
    - Health: http://localhost:3000/health
 
+## Skillgate (optional)
+
+Turn selected REST controllers into governed agent skills:
+
+```bash
+npm install @hazeljs/skillgate @hazeljs/swagger
+```
+
+See `src/examples/skillgate.example.ts` and https://hazeljs.ai/docs/guides/skillgate
+
+Tag controllers with `@ApiTags('agent')` or `@AgentSkill`, then:
+
+```ts
+Skillgate.fromModule(AppModule, { invoke: { baseUrl: 'http://127.0.0.1:3000' } }).register(
+  registry,
+  'api-concierge'
+);
+```
+
 ## Available Endpoints
 
 ### AI Chat

package/@template-ai-native/src/examples/skillgate.example.ts

@@ -0,0 +1,29 @@
+/**
+ * Optional Skillgate example (not imported by AppModule).
+ *
+ * Install: npm install @hazeljs/skillgate @hazeljs/swagger
+ * Then wire `registerApiSkills()` from your bootstrap after the HTTP server listens.
+ *
+ * Docs: https://hazeljs.ai/docs/guides/skillgate
+ */
+
+/*
+import { Skillgate } from '@hazeljs/skillgate';
+import { ToolRegistry } from '@hazeljs/agent';
+import { AppModule } from '../app.module';
+
+export function registerApiSkills(registry: ToolRegistry = new ToolRegistry()) {
+  const gate = Skillgate.fromModule(AppModule, {
+    include: { tags: ['agent'] },
+    swagger: {
+      title: 'AI-native API',
+      servers: [{ url: process.env.API_BASE_URL || 'http://127.0.0.1:3000' }],
+    },
+    invoke: { baseUrl: process.env.API_BASE_URL || 'http://127.0.0.1:3000' },
+  });
+  gate.register(registry, 'api-concierge');
+  return { gate, registry };
+}
+*/
+
+export {};

package/cli-manifest.json

@@ -4,7 +4,7 @@
   "description": "Machine-readable manifest of all CLI commands and options for LLM agent tool-use",
   "cli": {
     "name": "hazel",
-    "version": "1.0.6",
+    "version": "2.0.1",
     "description": "CLI for generating HazelJS components and applications"
   },
   "commands": [
@@ -874,6 +874,87 @@
       "description": "Display information about the current HazelJS project",
       "args": [],
       "options": []
+    },
+    {
+      "name": "store",
+      "usage": "hazel store <subcommand>",
+      "description": "Local Agent OS package registry (publish / install DNA packages)",
+      "subcommands": [
+        {
+          "name": "publish",
+          "usage": "hazel store publish <file> [--registry <dir>]",
+          "description": "Publish marketplace/DNA JSON to ~/.hazel/registry",
+          "args": [
+            {
+              "name": "file",
+              "type": "string",
+              "required": true,
+              "description": "Path to .dna.json or marketplace package JSON"
+            }
+          ],
+          "options": [
+            {
+              "name": "registry",
+              "type": "string",
+              "description": "Override registry root (default: ~/.hazel/registry)"
+            }
+          ]
+        },
+        {
+          "name": "install",
+          "usage": "hazel store install <spec> [--cwd <dir>] [--registry <dir>]",
+          "description": "Install package into project .hazel/agents (file path or name@version from local registry)",
+          "args": [
+            {
+              "name": "spec",
+              "type": "string",
+              "required": true,
+              "description": "File path or package name[@version]"
+            }
+          ],
+          "options": [
+            {
+              "name": "cwd",
+              "type": "string",
+              "default": ".",
+              "description": "Project root"
+            },
+            {
+              "name": "registry",
+              "type": "string",
+              "description": "Override registry root"
+            }
+          ]
+        },
+        {
+          "name": "list",
+          "usage": "hazel store list [query]",
+          "description": "List packages in the local registry"
+        },
+        {
+          "name": "remove",
+          "usage": "hazel store remove <name[@version]>",
+          "description": "Remove a package from the local registry"
+        },
+        {
+          "name": "doctor",
+          "usage": "hazel store doctor",
+          "description": "Check local registry health"
+        }
+      ]
+    },
+    {
+      "name": "install",
+      "usage": "hazel install <spec> [--cwd <dir>] [--registry <dir>]",
+      "description": "Alias for hazel store install",
+      "args": [
+        {
+          "name": "spec",
+          "type": "string",
+          "required": true,
+          "description": "File path or package name[@version]"
+        }
+      ]
     }
   ],
   "globalOptions": [

package/dist/commands/agent-templates.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent OS project templates for `hazel agent new`.
+ *
+ * DNA ≈ OpenAPI for agents (contract). App code = real tool implementations.
+ * `hazel agent run` on DNA alone uses stubs — production needs the app tools.
+ */
+export type AgentTemplateId = 'bare' | 'agent-os' | 'skillgate';
+export interface AgentTemplateMeta {
+    id: AgentTemplateId;
+    label: string;
+    description: string;
+}
+export declare const AGENT_TEMPLATES: AgentTemplateMeta[];
+export declare function listAgentTemplates(): AgentTemplateMeta[];
+export declare function resolveAgentTemplate(id: string): AgentTemplateId;
+export interface ScaffoldAgentProjectOptions {
+    name: string;
+    destDir: string;
+    template: AgentTemplateId;
+    force?: boolean;
+}
+export interface ScaffoldAgentProjectResult {
+    path: string;
+    template: AgentTemplateId;
+    files: string[];
+}
+export declare function scaffoldAgentProject(options: ScaffoldAgentProjectOptions): ScaffoldAgentProjectResult;

package/dist/commands/agent-templates.js

@@ -0,0 +1,480 @@
+"use strict";
+/**
+ * Agent OS project templates for `hazel agent new`.
+ *
+ * DNA ≈ OpenAPI for agents (contract). App code = real tool implementations.
+ * `hazel agent run` on DNA alone uses stubs — production needs the app tools.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TEMPLATES = void 0;
+exports.listAgentTemplates = listAgentTemplates;
+exports.resolveAgentTemplate = resolveAgentTemplate;
+exports.scaffoldAgentProject = scaffoldAgentProject;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.AGENT_TEMPLATES = [
+    {
+        id: 'bare',
+        label: 'Bare DNA package',
+        description: 'Marketplace DNA only — publish/install/run with stub tools (packaging smoke)',
+    },
+    {
+        id: 'agent-os',
+        label: 'Agent OS mini-app',
+        description: 'DNA + real @Agent/@Tool TypeScript app (HITL refund demo) + store lock',
+    },
+    {
+        id: 'skillgate',
+        label: 'Skillgate concierge',
+        description: 'DNA + Skillgate fromOpenApi sample + register sketch for API concierge',
+    },
+];
+function listAgentTemplates() {
+    return [...exports.AGENT_TEMPLATES];
+}
+function resolveAgentTemplate(id) {
+    const found = exports.AGENT_TEMPLATES.find((t) => t.id === id);
+    if (!found) {
+        throw new Error(`Unknown agent template "${id}". Available: ${exports.AGENT_TEMPLATES.map((t) => t.id).join(', ')}`);
+    }
+    return found.id;
+}
+function writeFile(root, rel, content) {
+    const full = path.join(root, rel);
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content.endsWith('\n') ? content : content + '\n');
+}
+function sanitizeNpmName(name) {
+    return (name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-_]/g, '-')
+        .replace(/^-+|-+$/g, '') || 'my-agent');
+}
+function agentDnaName(projectName) {
+    return sanitizeNpmName(projectName).replace(/-/g, '_').slice(0, 48) || 'my_agent';
+}
+function marketplacePackage(projectName, opts) {
+    const dnaName = agentDnaName(projectName);
+    const pkg = {
+        name: `@local/${sanitizeNpmName(projectName)}-agent`,
+        version: '1.0.0',
+        description: opts.description,
+        dna: {
+            format: 'hazeljs.agent.dna',
+            version: '1.0.0',
+            name: dnaName,
+            description: opts.description,
+            systemPrompt: opts.systemPrompt,
+            tools: opts.tools,
+            policies: opts.policies ?? [],
+            contracts: [{ name: `${dnaName}-slo`, maxLatencyMs: 30000 }],
+            exportedAt: new Date().toISOString(),
+        },
+        readme: opts.description,
+        keywords: opts.keywords,
+    };
+    return JSON.stringify(pkg, null, 2);
+}
+function bareFiles(projectName) {
+    const pkgJson = marketplacePackage(projectName, {
+        description: `${projectName} — DNA-only agent package`,
+        systemPrompt: `You are ${projectName}. Be concise. Use tools when available; otherwise explain what you would do.`,
+        tools: [
+            { name: 'ping', description: 'Health ping (stub in CLI run)' },
+            { name: 'echo', description: 'Echo input (stub in CLI run)' },
+        ],
+        keywords: ['agent-os', 'dna', 'bare'],
+    });
+    return {
+        'package.json': JSON.stringify({
+            name: sanitizeNpmName(projectName),
+            version: '1.0.0',
+            private: true,
+            description: `DNA package for ${projectName}`,
+            scripts: {
+                'agent:run': 'hazel agent run dna/agent.marketplace.json',
+                'store:publish': 'hazel store publish dna/agent.marketplace.json',
+                'store:install': 'hazel store install dna/agent.marketplace.json',
+            },
+            keywords: ['hazeljs', 'agent-os', 'dna'],
+            license: 'Apache-2.0',
+        }, null, 2),
+        'dna/agent.marketplace.json': pkgJson,
+        'README.md': `# ${projectName}
+
+Bare **Agent DNA** package (contract only — like OpenAPI for an agent).
+
+## Commands
+
+\`\`\`bash
+# Smoke-run (Agent OS engine + stub tools + mock/real LLM)
+npx hazel agent run dna/agent.marketplace.json "hello"
+
+# Publish to local registry, then install into a project
+npx hazel store publish dna/agent.marketplace.json
+npx hazel store install @local/${sanitizeNpmName(projectName)}-agent --cwd /path/to/app
+\`\`\`
+
+## Important
+
+\`hazel agent run\` executes the **runtime** with **stub** tool handlers.
+Wire real \`@Tool\` / Skillgate handlers in your Hazel app for production behavior.
+`,
+    };
+}
+function agentOsFiles(projectName) {
+    const dnaName = agentDnaName(projectName);
+    const npm = sanitizeNpmName(projectName);
+    const marketplace = marketplacePackage(projectName, {
+        description: `${projectName} — Agent OS support-style agent with real tools`,
+        systemPrompt: `You are ${projectName}, a support desk agent.
+Use lookupOrder for facts. Call processRefund only after lookup. Be concise.`,
+        tools: [
+            { name: 'lookupOrder', description: 'Look up an order by id' },
+            {
+                name: 'processRefund',
+                description: 'Process a refund (requires approval)',
+                requiresApproval: true,
+            },
+        ],
+        policies: [
+            {
+                id: 'refund-needs-approval',
+                tool: 'processRefund',
+                effect: 'require_approval',
+                priority: 20,
+            },
+        ],
+        keywords: ['agent-os', 'hitl', 'support'],
+    });
+    return {
+        'package.json': JSON.stringify({
+            name: npm,
+            version: '1.0.0',
+            private: true,
+            description: `Agent OS mini-app: ${projectName}`,
+            scripts: {
+                build: 'tsc',
+                start: 'node dist/main.js',
+                dev: 'ts-node --transpile-only src/main.ts',
+                'agent:run': 'hazel agent run dna/agent.marketplace.json',
+                'store:publish': 'hazel store publish dna/agent.marketplace.json',
+                'store:install': 'hazel store install dna/agent.marketplace.json --cwd .',
+            },
+            dependencies: {
+                '@hazeljs/agent': '^1.0.6',
+                'reflect-metadata': '^0.2.2',
+            },
+            devDependencies: {
+                '@types/node': '^20.19.39',
+                'ts-node': '^10.9.2',
+                typescript: '^5.9.3',
+            },
+            license: 'Apache-2.0',
+        }, null, 2),
+        'tsconfig.json': JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'commonjs',
+                outDir: 'dist',
+                rootDir: 'src',
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+                experimentalDecorators: true,
+                emitDecoratorMetadata: true,
+            },
+            include: ['src/**/*'],
+        }, null, 2),
+        'dna/agent.marketplace.json': marketplace,
+        'src/orders.ts': `export type Order = { id: string; status: string; totalUsd: number };
+
+const ORDERS: Record<string, Order> = {
+  'ORD-1001': { id: 'ORD-1001', status: 'shipped', totalUsd: 128 },
+  'ORD-1002': { id: 'ORD-1002', status: 'delivered', totalUsd: 64 },
+};
+
+export function getOrder(id: string): Order | undefined {
+  return ORDERS[id.toUpperCase()];
+}
+`,
+        'src/support.agent.ts': `import 'reflect-metadata';
+import { Agent, Tool } from '@hazeljs/agent';
+import { getOrder } from './orders';
+
+@Agent({
+  name: '${dnaName}',
+  description: '${projectName} support agent',
+  systemPrompt: \`You are ${projectName}. Use lookupOrder for facts. Use processRefund only after lookup.\`,
+  maxSteps: 8,
+})
+export class SupportAgent {
+  @Tool({
+    name: 'lookupOrder',
+    description: 'Look up an order by id (e.g. ORD-1001)',
+    parameters: [{ name: 'orderId', type: 'string', required: true }],
+  })
+  async lookupOrder({ orderId }: { orderId: string }) {
+    const order = getOrder(orderId);
+    if (!order) return { found: false, error: \`No order \${orderId}\` };
+    return { found: true, order };
+  }
+
+  @Tool({
+    name: 'processRefund',
+    description: 'Process a refund — requires human approval',
+    requiresApproval: true,
+    parameters: [
+      { name: 'orderId', type: 'string', required: true },
+      { name: 'amount', type: 'number', required: true },
+    ],
+  })
+  async processRefund({ orderId, amount }: { orderId: string; amount: number }) {
+    const order = getOrder(orderId);
+    if (!order) return { ok: false, error: \`No order \${orderId}\` };
+    return { ok: true, orderId: order.id, amount, status: 'refunded' };
+  }
+}
+`,
+        'src/main.ts': `/**
+ * Mini Agent OS app — real tools (not DNA stubs).
+ * DNA in dna/ can be hot-reloaded / store-installed for prompt+policy overlays.
+ */
+import 'reflect-metadata';
+import {
+  AgentRuntime,
+  AgentEventType,
+  createMockLlmProvider,
+  type AgentEvent,
+} from '@hazeljs/agent';
+import { SupportAgent } from './support.agent';
+
+async function main() {
+  const input = process.argv.slice(2).join(' ') || 'Where is ORD-1001?';
+  // Demo uses mock LLM. Wire OpenAI (or another provider) in production apps.
+  const llm = createMockLlmProvider(
+    'Used real @Tool handlers on AgentRuntime. (Replace createMockLlmProvider with your LLM.)'
+  );
+
+  const runtime = new AgentRuntime({
+    llmProvider: llm,
+    enableRetry: false,
+    enableCircuitBreaker: false,
+  });
+
+  runtime.registerAgent(SupportAgent);
+  runtime.registerAgentInstance('${dnaName}', new SupportAgent());
+
+  // Auto-approve refunds unless HITL=1
+  if (process.env.HITL !== '1') {
+    runtime.on(AgentEventType.TOOL_APPROVAL_REQUESTED, (event) => {
+      const data = (event as AgentEvent<{ requestId?: string }>).data;
+      if (data?.requestId) runtime.approveToolExecution(data.requestId, 'demo');
+    });
+  }
+
+  // DNA file is for store publish/install + CLI smoke.
+  // Do not installAgentPackage here if it would re-register tools without handlers.
+  // Use DNA overlay for prompt/policies in production only when tools are wired.
+
+  const result = await runtime.execute('${dnaName}', input, { maxSteps: 8 });
+  console.log(JSON.stringify({ response: result.response, state: result.state, steps: result.steps.length }, null, 2));
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+`,
+        'README.md': `# ${projectName}
+
+**Agent OS mini-app** — DNA contract + **real** \`@Tool\` implementations.
+
+| Path | Role |
+| --- | --- |
+| \`dna/agent.marketplace.json\` | DNA / marketplace package (OpenAPI-for-agents) |
+| \`src/support.agent.ts\` | Real tool handlers |
+| \`src/main.ts\` | AgentRuntime bootstrap + optional DNA overlay |
+
+## Quick start
+
+\`\`\`bash
+npm install
+npm run dev
+npm run dev -- I want a refund for ORD-1002
+
+# DNA smoke (stubs — not the same as npm run dev)
+npx hazel agent run dna/agent.marketplace.json "hello"
+
+# Package+Store
+npm run store:publish
+npm run store:install
+\`\`\`
+
+Set \`HITL=1\` to pause on \`processRefund\` approvals.
+`,
+    };
+}
+function skillgateFiles(projectName) {
+    const npm = sanitizeNpmName(projectName);
+    const marketplace = marketplacePackage(projectName, {
+        description: `${projectName} — API concierge (Skillgate-governed REST skills)`,
+        systemPrompt: `You are an API concierge. Prefer read skills first. Writes need approval.`,
+        tools: [
+            { name: 'getOrder', description: 'GET order by id (Skillgate read)' },
+            {
+                name: 'createRefund',
+                description: 'POST refund (Skillgate write + approval)',
+                requiresApproval: true,
+            },
+        ],
+        keywords: ['skillgate', 'agent-os', 'openapi'],
+    });
+    return {
+        'package.json': JSON.stringify({
+            name: npm,
+            version: '1.0.0',
+            private: true,
+            description: `Skillgate agent starter: ${projectName}`,
+            scripts: {
+                build: 'tsc',
+                report: 'ts-node --transpile-only src/report.ts',
+                'agent:run': 'hazel agent run dna/agent.marketplace.json',
+                'store:publish': 'hazel store publish dna/agent.marketplace.json',
+            },
+            dependencies: {
+                '@hazeljs/agent': '^1.0.6',
+                '@hazeljs/skillgate': '^1.0.6',
+            },
+            devDependencies: {
+                '@types/node': '^20.19.39',
+                'ts-node': '^10.9.2',
+                typescript: '^5.9.3',
+            },
+            license: 'Apache-2.0',
+        }, null, 2),
+        'tsconfig.json': JSON.stringify({
+            compilerOptions: {
+                target: 'ES2022',
+                module: 'commonjs',
+                outDir: 'dist',
+                rootDir: 'src',
+                strict: true,
+                esModuleInterop: true,
+                skipLibCheck: true,
+            },
+            include: ['src/**/*'],
+        }, null, 2),
+        'dna/agent.marketplace.json': marketplace,
+        'openapi/sample.openapi.json': JSON.stringify({
+            openapi: '3.0.3',
+            info: { title: `${projectName} API`, version: '1.0.0' },
+            servers: [{ url: 'http://127.0.0.1:3000' }],
+            paths: {
+                '/orders/{id}': {
+                    get: {
+                        operationId: 'getOrder',
+                        tags: ['agent'],
+                        summary: 'Fetch an order by id',
+                        parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+                        'x-hazel-skill': { readOnly: true, class: 'read' },
+                    },
+                },
+                '/refunds': {
+                    post: {
+                        operationId: 'createRefund',
+                        tags: ['agent'],
+                        summary: 'Create a refund',
+                        'x-hazel-skill': { requiresApproval: true, class: 'write' },
+                    },
+                },
+            },
+        }, null, 2),
+        'src/report.ts': `import * as fs from 'fs';
+import * as path from 'path';
+import { Skillgate, type OpenApiLike } from '@hazeljs/skillgate';
+import { ToolRegistry } from '@hazeljs/agent';
+
+const specPath = path.join(__dirname, '..', 'openapi', 'sample.openapi.json');
+const spec = JSON.parse(fs.readFileSync(specPath, 'utf8')) as OpenApiLike;
+
+const gate = Skillgate.fromOpenApi(spec, {
+  include: { tags: ['agent'] },
+  classify: { writeRequiresApproval: true },
+  invoke: { baseUrl: process.env.API_BASE_URL || 'http://127.0.0.1:3000' },
+});
+
+const registry = new ToolRegistry();
+gate.register(registry, 'api-concierge');
+
+console.log(JSON.stringify(gate.report(), null, 2));
+console.log('Registered tools:', registry.getAgentTools('api-concierge').map((t) => t.name));
+`,
+        'README.md': `# ${projectName}
+
+**Skillgate** starter — OpenAPI → governed agent skills + DNA package.
+
+\`\`\`bash
+npm install
+npm run report          # Skillgate included/denied report
+npx hazel agent run dna/agent.marketplace.json
+npx hazel store publish dna/agent.marketplace.json
+\`\`\`
+
+See also: full showcase \`hazeljs-skillgate-agent-starter\` in the monorepo.
+`,
+    };
+}
+function scaffoldAgentProject(options) {
+    const template = resolveAgentTemplate(options.template);
+    const root = path.resolve(options.destDir);
+    if (fs.existsSync(root) && fs.readdirSync(root).length > 0 && !options.force) {
+        throw new Error(`Destination not empty: ${root} (pass force to overwrite)`);
+    }
+    const files = template === 'bare'
+        ? bareFiles(options.name)
+        : template === 'skillgate'
+            ? skillgateFiles(options.name)
+            : agentOsFiles(options.name);
+    fs.mkdirSync(root, { recursive: true });
+    const written = [];
+    for (const [rel, content] of Object.entries(files)) {
+        writeFile(root, rel, content);
+        written.push(rel);
+    }
+    return { path: root, template, files: written };
+}

package/dist/commands/agent.d.ts

@@ -1,6 +1,10 @@
 import { Command } from 'commander';
 /**
+ * `hazel agent new` — scaffold Agent OS / DNA templates (G2 template unification).
  * `hazel agent install <file.dna.json>` — validate / print marketplace install plan.
- * Live hot-reload happens in-process via AgentRuntime.installAgentPackage().
+ * `hazel agent run` — live execute from DNA (AOS-011).
+ * `hazel agent apply|get|describe|delete|reconcile|events` — declarative platform resources (local control plane).
+ * `hazel agent logs` / `doctor` — timeline + environment checks.
+ * `hazel agent runs list|inspect|cancel|resume|approve` — durable store ops.
  */
 export declare function registerAgentCommand(program: Command): void;