@agent-creator/cli 0.4.2 → 0.5.0

package/README.md

@@ -1,4 +1,4 @@
-# agent-creator-cli
+# @agent-creator/cli
 
 CLI for creating package or service projects powered by `@agent-creator/core`.
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
-    "name": "agent-creator-cli",
-    "version": "0.4.2",
+    "name": "@agent-creator/cli",
+    "version": "0.5.0",
     "description": "CLI for creating projects powered by @agent-creator/core.",
     "type": "module",
     "bin": {

package/dist/src/capabilities/agent-core/files/base/.env.example

@@ -1,4 +1,6 @@
 LLM_BASE_URL=https://api.openai.com/v1
-OPENAI_API_KEY=
-# Optional. Defaults to gpt-4o-mini in agent.config.ts.
+OPENAI_API_KEY=your-openai-api-key
 LLM_MODEL=gpt-4o-mini
+
+# Optional. Used by context.webhook and the webhook skill adapter.
+WEBHOOK_URL=

package/dist/src/capabilities/agent-core/files/base/README.md

@@ -8,6 +8,38 @@ Config schema: `{{configVersion}}`
 
 This is an independent runnable Agent project powered by `@agent-creator/core`.
 
+## 5 Minute Integration
+
+```bash
+npm install
+cp .env.example .env
+npm run dev
+```
+
+Edit `.env` and set `OPENAI_API_KEY`. Service mode exposes:
+
+```bash
+curl -X POST http://localhost:3000/api/agent \
+  -H "content-type: application/json" \
+  -d '{"input":"Hello agent","sessionId":"demo"}'
+```
+
+TypeScript callers can use the generated HTTP client:
+
+```ts
+import { runAgentHttp } from './src/client.js';
+
+const output = await runAgentHttp({
+  baseUrl: 'http://localhost:3000',
+  input: 'Hello agent',
+  sessionId: 'demo',
+});
+```
+
+After publishing or linking this generated package, consumers can import the client as `{{projectName}}/client`.
+
+See `docs/api.md` for the full HTTP contract, streaming format, optional `AGENT_API_KEY` auth, and production notes.
+
 ## Configure The Agent
 
 Open `agent.config.ts` and set the minimum model configuration:
@@ -29,6 +61,8 @@ export OPENAI_API_KEY=your-key
 export LLM_MODEL=gpt-4o-mini
 ```
 
+The generated `.env.example` contains the same variables. Service mode also supports optional `AGENT_API_KEY` bearer-token authentication.
+
 ## Run
 
 Package mode starts a command-line chat:
@@ -58,6 +92,12 @@ Then open the printed local URL and chat in the browser. Service mode also keeps
 npm run dev:agent
 ```
 
+Health check:
+
+```bash
+curl http://localhost:3000/api/agent/health
+```
+
 ## Customize Capabilities
 
 Add skills and compose the Agent in `src/index.ts`:
@@ -67,3 +107,27 @@ agent add skill calendar
 ```
 
 `src/index.ts` creates the Builder, registers every Skill from `src/skills/index.ts`, and calls `build()`.
+
+Webhook is available as a built-in optional Skill adapter:
+
+```bash
+agent add skill webhook
+```
+
+Then set `WEBHOOK_URL` in `.env`. You can call it directly with `metadata.skill = 'webhook'`, or configure `createAgent({ webhook: { url } })` in `src/index.ts` and call `context.webhook?.notify(...)` from your own Skills.
+
+To call a specific Skill directly through the default planner, pass metadata:
+
+```ts
+await runAgent({
+  input: 'Run calendar search',
+  metadata: {
+    skill: 'calendar',
+    skillInput: { query: 'today' },
+  },
+});
+```
+
+## Production Notes
+
+The default memory provider is process-local in-memory storage. It is useful for development, but production deployments should replace it with a persistent `MemoryProvider`.

package/dist/src/capabilities/agent-core/files/base/agent.config.ts

@@ -21,6 +21,10 @@ const config = {
     timeoutMs: 30000,
     maxRetries: 1,
   },
+  webhook: {
+    url: process.env.WEBHOOK_URL ?? '',
+    timeoutMs: 10000,
+  },
   skills: {
     enabled: [
       // agent-creator:skills

package/dist/src/capabilities/agent-core/files/base/docs/api.md

@@ -0,0 +1,186 @@
+# {{projectName}} API
+
+This project exposes the Agent as both a TypeScript package entrypoint and, in service mode, a small HTTP API.
+
+## Environment
+
+Copy `.env.example` to `.env` and set:
+
+```bash
+LLM_BASE_URL=https://api.openai.com/v1
+OPENAI_API_KEY=your-openai-api-key
+LLM_MODEL=gpt-4o-mini
+```
+
+Service mode also supports optional API authentication:
+
+```bash
+AGENT_API_KEY=replace-with-a-random-secret
+```
+
+When `AGENT_API_KEY` is set, HTTP callers must send:
+
+```http
+Authorization: Bearer replace-with-a-random-secret
+```
+
+## Package Entrypoint
+
+Use `runAgent()` when calling from another TypeScript or Node.js module in the same process:
+
+```ts
+import { runAgent } from './src/index.js';
+
+const output = await runAgent({
+  input: 'Summarize today\'s support tickets',
+  sessionId: 'support-session-1',
+});
+```
+
+The default memory provider is process-local in-memory storage. It is convenient for development, but production deployments should replace it with a persistent `MemoryProvider`.
+
+## POST /api/agent
+
+Runs the Agent and returns the final output as JSON.
+
+Request:
+
+```json
+{
+  "input": "Hello agent",
+  "sessionId": "optional-session-id"
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "intent": "generate_response",
+  "message": "Hello! How can I help?",
+  "data": {},
+  "traceId": "trace_..."
+}
+```
+
+Example:
+
+```bash
+curl -X POST http://localhost:3000/api/agent \
+  -H "content-type: application/json" \
+  -d '{"input":"Hello agent","sessionId":"demo"}'
+```
+
+If `AGENT_API_KEY` is set:
+
+```bash
+curl -X POST http://localhost:3000/api/agent \
+  -H "authorization: Bearer $AGENT_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"input":"Hello agent","sessionId":"demo"}'
+```
+
+## POST /api/agent/stream
+
+Runs the Agent and streams progress as newline-delimited JSON (`application/x-ndjson`).
+
+Each line is one of:
+
+```json
+{ "type": "progress", "event": { "type": "agent.started", "message": "Agent started", "traceId": "trace_...", "at": "..." } }
+```
+
+```json
+{ "type": "final", "output": { "success": true, "intent": "generate_response", "message": "Done", "traceId": "trace_..." } }
+```
+
+Example:
+
+```bash
+curl -N -X POST http://localhost:3000/api/agent/stream \
+  -H "content-type: application/json" \
+  -d '{"input":"Hello agent","sessionId":"demo"}'
+```
+
+## GET /api/agent/health
+
+Returns service readiness metadata without exposing secrets.
+
+Response:
+
+```json
+{
+  "ok": true,
+  "name": "{{projectName}}",
+  "version": "{{capabilityVersion}}",
+  "service": {
+    "enabled": true,
+    "framework": "next"
+  },
+  "model": {
+    "configured": true,
+    "baseUrlConfigured": true,
+    "apiKeyConfigured": true,
+    "model": "gpt-4o-mini"
+  }
+}
+```
+
+`ok` is `false` when required model configuration is missing.
+
+## TypeScript HTTP Client
+
+`src/client.ts` exports helpers for another frontend or backend to call the service:
+
+```ts
+import { runAgentHttp, streamAgentHttp } from './src/client.js';
+
+const output = await runAgentHttp({
+  baseUrl: 'http://localhost:3000',
+  input: 'Hello agent',
+  sessionId: 'demo',
+});
+
+for await (const event of streamAgentHttp({
+  baseUrl: 'http://localhost:3000',
+  input: 'Show progress',
+  sessionId: 'demo',
+})) {
+  console.log(event);
+}
+```
+
+Pass `apiKey` when `AGENT_API_KEY` is enabled.
+
+## Webhook Skill And Runtime Service
+
+Add the optional built-in webhook Skill adapter:
+
+```bash
+agent add skill webhook
+```
+
+Set the target URL in `.env`:
+
+```bash
+WEBHOOK_URL=https://example.com/webhook
+```
+
+Call it directly:
+
+```ts
+await runAgent({
+  input: 'Notify webhook',
+  metadata: {
+    skill: 'webhook',
+    skillInput: {
+      event: 'build.completed',
+      message: 'Build finished',
+      logs: ['npm test passed'],
+    },
+  },
+});
+```
+
+For developer-controlled side effects inside your own Skills, configure the runtime service and call `context.webhook?.notify(...)`. Do not read webhook URLs from user input or model output.

package/dist/src/capabilities/agent-core/files/base/package.json

@@ -11,6 +11,10 @@
     ".": {
       "types": "./dist/src/index.d.ts",
       "import": "./dist/src/index.js"
+    },
+    "./client": {
+      "types": "./dist/src/client.d.ts",
+      "import": "./dist/src/client.js"
     }
   },
   "scripts": {

package/dist/src/capabilities/agent-core/files/base/src/client.ts

@@ -0,0 +1,78 @@
+import type { AgentOutput, AgentProgressEvent } from '@agent-creator/core';
+
+export interface AgentHttpOptions {
+  baseUrl: string;
+  input: string;
+  sessionId?: string;
+  apiKey?: string;
+  fetch?: typeof globalThis.fetch;
+}
+
+export type AgentStreamEvent =
+  | { type: 'progress'; event: AgentProgressEvent }
+  | { type: 'final'; output: AgentOutput };
+
+export async function runAgentHttp(options: AgentHttpOptions): Promise<AgentOutput> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) throw new Error('Global fetch is unavailable. Node.js 18 or newer is required.');
+  const response = await fetchImpl(`${normalizeBaseUrl(options.baseUrl)}/api/agent`, {
+    method: 'POST',
+    headers: requestHeaders(options.apiKey),
+    body: JSON.stringify({ input: options.input, sessionId: options.sessionId }),
+  });
+  if (!response.ok) throw new Error(`agent_request_failed: ${response.status} ${await response.text()}`);
+  return await response.json() as AgentOutput;
+}
+
+export async function* streamAgentHttp(options: AgentHttpOptions): AsyncGenerator<AgentStreamEvent> {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) throw new Error('Global fetch is unavailable. Node.js 18 or newer is required.');
+  const response = await fetchImpl(`${normalizeBaseUrl(options.baseUrl)}/api/agent/stream`, {
+    method: 'POST',
+    headers: requestHeaders(options.apiKey),
+    body: JSON.stringify({ input: options.input, sessionId: options.sessionId }),
+  });
+  if (!response.ok) throw new Error(`agent_stream_failed: ${response.status} ${await response.text()}`);
+  if (!response.body) throw new Error('agent_stream_unavailable: response body is missing');
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() ?? '';
+    for (const line of lines) {
+      const event = parseStreamLine(line);
+      if (event) yield event;
+    }
+  }
+
+  const finalEvent = parseStreamLine(buffer);
+  if (finalEvent) yield finalEvent;
+}
+
+function requestHeaders(apiKey?: string): HeadersInit {
+  return {
+    'content-type': 'application/json',
+    ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+  };
+}
+
+function normalizeBaseUrl(baseUrl: string): string {
+  const normalized = baseUrl.trim().replace(/\/+$/, '');
+  if (!normalized) throw new Error('baseUrl is required.');
+  return normalized;
+}
+
+function parseStreamLine(line: string): AgentStreamEvent | undefined {
+  if (!line.trim()) return undefined;
+  const event = JSON.parse(line) as AgentStreamEvent;
+  if (event.type !== 'progress' && event.type !== 'final') {
+    throw new Error(`agent_stream_invalid_event: ${event.type}`);
+  }
+  return event;
+}

package/dist/src/capabilities/agent-core/files/base/src/index.ts

@@ -6,7 +6,7 @@ let configuredAgent: Agent | undefined;
 
 export function getAgent(): Agent {
   if (configuredAgent) return configuredAgent;
-  const builder = createAgent({ model: config.model });
+  const builder = createAgent({ model: config.model, webhook: config.webhook });
   for (const skill of skills) builder.useSkill(skill);
   configuredAgent = builder.build();
   return configuredAgent;

package/dist/src/capabilities/agent-core/files/service/.env.example

@@ -0,0 +1,10 @@
+LLM_BASE_URL=https://api.openai.com/v1
+OPENAI_API_KEY=your-openai-api-key
+LLM_MODEL=gpt-4o-mini
+
+# Optional. Used by context.webhook and the webhook skill adapter.
+WEBHOOK_URL=
+
+# Optional. When set, HTTP callers must send:
+# Authorization: Bearer <this-value>
+AGENT_API_KEY=

package/dist/src/capabilities/agent-core/files/service/package.json

@@ -2,6 +2,16 @@
   "name": "{{projectName}}",
   "version": "{{capabilityVersion}}",
   "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./client": {
+      "types": "./dist/src/client.d.ts",
+      "import": "./dist/src/client.js"
+    }
+  },
   "scripts": {
     "dev": "next dev",
     "dev:agent": "tsx src/cli.ts",

package/dist/src/capabilities/agent-core/files/service/src/app/api/agent/auth.ts

@@ -0,0 +1,19 @@
+import { NextResponse } from 'next/server';
+
+export function requireAgentApiKey(request: Request): NextResponse | undefined {
+  const expected = process.env.AGENT_API_KEY?.trim();
+  if (!expected) return undefined;
+
+  const authorization = request.headers.get('authorization') ?? '';
+  const actual = authorization.startsWith('Bearer ') ? authorization.slice('Bearer '.length).trim() : '';
+  if (actual === expected) return undefined;
+
+  return NextResponse.json(
+    {
+      success: false,
+      intent: 'unauthorized',
+      message: 'Missing or invalid Agent API key.',
+    },
+    { status: 401 },
+  );
+}

package/dist/src/capabilities/agent-core/files/service/src/app/api/agent/health/route.ts

@@ -0,0 +1,23 @@
+import { NextResponse } from 'next/server';
+import config from '../../../../../agent.config';
+
+export async function GET() {
+  const baseUrlConfigured = Boolean(config.model.baseUrl?.trim());
+  const apiKeyConfigured = Boolean(config.model.apiKey?.trim());
+
+  return NextResponse.json({
+    ok: baseUrlConfigured && apiKeyConfigured,
+    name: config.name,
+    version: config.version,
+    service: {
+      enabled: config.service.enabled,
+      framework: config.service.framework,
+    },
+    model: {
+      configured: baseUrlConfigured && apiKeyConfigured,
+      baseUrlConfigured,
+      apiKeyConfigured,
+      model: config.model.model,
+    },
+  });
+}

package/dist/src/capabilities/agent-core/files/service/src/app/api/agent/route.ts

@@ -1,7 +1,11 @@
 import { NextResponse } from 'next/server';
 import { runAgent } from '../../../index';
+import { requireAgentApiKey } from './auth';
 
 export async function POST(request: Request) {
+  const unauthorized = requireAgentApiKey(request);
+  if (unauthorized) return unauthorized;
+
   const body = await request.json().catch(() => ({})) as Record<string, unknown>;
   const input = typeof body.input === 'string' ? body.input : '';
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId : undefined;

package/dist/src/capabilities/agent-core/files/service/src/app/api/agent/stream/route.ts

@@ -1,11 +1,15 @@
 import type { AgentOutput, AgentProgressEvent } from '@agent-creator/core';
 import { runAgent } from '../../../../index';
+import { requireAgentApiKey } from '../auth';
 
 type StreamEvent =
   | { type: 'progress'; event: AgentProgressEvent }
   | { type: 'final'; output: AgentOutput };
 
 export async function POST(request: Request) {
+  const unauthorized = requireAgentApiKey(request);
+  if (unauthorized) return unauthorized;
+
   const body = await request.json().catch(() => ({})) as Record<string, unknown>;
   const input = typeof body.input === 'string' ? body.input : '';
   const sessionId = typeof body.sessionId === 'string' ? body.sessionId : undefined;

package/dist/src/commands/addSkill.js

@@ -9,19 +9,24 @@ export async function addSkillCommand(skillName, _options = {}) {
     }
     const fileName = toKebabCase(skillName);
     const symbolName = `${toCamelCase(skillName)}Skill`;
-    const dottedName = toToolName(skillName);
+    const isWebhookSkill = toKebabCase(skillName) === 'webhook';
+    const dottedName = isWebhookSkill ? 'webhook' : toToolName(skillName);
     const target = path.join(process.cwd(), 'src/skills', `${fileName}.ts`);
     if (await pathExists(target))
         throw new Error(`Skill already exists: src/skills/${fileName}.ts`);
-    await writeFileEnsured(target, skillFile(symbolName, dottedName));
+    await writeFileEnsured(target, isWebhookSkill ? webhookSkillFile(symbolName) : skillFile(symbolName, dottedName));
     await updateSkillsIndex(fileName, symbolName, dottedName);
     await updateAgentConfig(dottedName);
+    if (isWebhookSkill)
+        await updateEnvExample();
     logger.success(`Added skill ${dottedName}.`);
 }
 function skillFile(symbolName, dottedName) {
     return `import { z } from 'zod';
 import type { Skill } from '@agent-creator/core';
 
+// Call this skill directly by passing:
+// metadata: { skill: '${dottedName}', skillInput: { query: '...' } }
 const inputSchema = z.object({
   query: z.string().min(1),
 });
@@ -42,6 +47,19 @@ export const ${symbolName}: Skill<z.infer<typeof inputSchema>, z.infer<typeof ou
 };
 `;
 }
+function webhookSkillFile(symbolName) {
+    return `import { createWebhookSkill } from '@agent-creator/core';
+
+// Call this skill directly by passing:
+// metadata: {
+//   skill: 'webhook',
+//   skillInput: { event: 'build.completed', message: 'Build finished' }
+// }
+export const ${symbolName} = createWebhookSkill({
+  url: process.env.WEBHOOK_URL ?? '',
+});
+`;
+}
 async function updateSkillsIndex(fileName, symbolName, dottedName) {
     const indexPath = path.join(process.cwd(), 'src/skills/index.ts');
     let text = await readText(indexPath);
@@ -56,3 +74,13 @@ async function updateAgentConfig(dottedName) {
     text = text.replace('// agent-creator:skills', `// agent-creator:skills\n      '${dottedName}',`);
     await writeFileEnsured(configPath, text);
 }
+async function updateEnvExample() {
+    const envPath = path.join(process.cwd(), '.env.example');
+    if (!(await pathExists(envPath)))
+        return;
+    const text = await readText(envPath);
+    if (text.includes('WEBHOOK_URL='))
+        return;
+    const suffix = text.endsWith('\n') ? '' : '\n';
+    await writeFileEnsured(envPath, `${text}${suffix}\n# Optional webhook target used by the webhook skill/runtime service.\nWEBHOOK_URL=\n`);
+}

package/dist/src/commands/validate.js

@@ -75,7 +75,10 @@ async function validateServiceProject(cwd, issues) {
     const required = [
         'src/app/page.tsx',
         'src/app/api/agent/route.ts',
+        'src/app/api/agent/auth.ts',
+        'src/app/api/agent/health/route.ts',
         'src/components/AgentChat.tsx',
+        'docs/api.md',
     ];
     for (const file of required) {
         if (!(await pathExists(path.join(cwd, file)))) {

package/dist/src/schemas/agentConfig.schema.d.ts

@@ -44,6 +44,16 @@ export declare const agentConfigSchema: z.ZodObject<{
         timeoutMs: number;
         maxRetries: number;
     }>;
+    webhook: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        timeoutMs?: number | undefined;
+    }, {
+        url: string;
+        timeoutMs?: number | undefined;
+    }>>;
     skills: z.ZodObject<{
         enabled: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
@@ -75,6 +85,10 @@ export declare const agentConfigSchema: z.ZodObject<{
     skills: {
         enabled: string[];
     };
+    webhook?: {
+        url: string;
+        timeoutMs?: number | undefined;
+    } | undefined;
 }, {
     service: {
         enabled: boolean;
@@ -99,5 +113,9 @@ export declare const agentConfigSchema: z.ZodObject<{
     skills: {
         enabled: string[];
     };
+    webhook?: {
+        url: string;
+        timeoutMs?: number | undefined;
+    } | undefined;
 }>;
 export type AgentConfigShape = z.infer<typeof agentConfigSchema>;

package/dist/src/schemas/agentConfig.schema.js

@@ -20,6 +20,10 @@ export const agentConfigSchema = z.object({
         timeoutMs: z.number().positive(),
         maxRetries: z.number().int().nonnegative(),
     }),
+    webhook: z.object({
+        url: z.string(),
+        timeoutMs: z.number().positive().optional(),
+    }).optional(),
     skills: z.object({
         enabled: z.array(z.string().min(1)),
     }),

package/dist/src/version.d.ts

@@ -1,4 +1,4 @@
 export declare const CLI_VERSION: string;
 export declare const SUPPORTED_CONFIG_VERSIONS: readonly ["0.1"];
 export declare const CURRENT_CONFIG_VERSION = "0.1";
-export declare const AGENT_CORE_CAPABILITY_VERSION = "0.4.2";
+export declare const AGENT_CORE_CAPABILITY_VERSION = "0.5.0";

package/dist/src/version.js

@@ -2,4 +2,4 @@ import packageJson from '../package.json' with { type: 'json' };
 export const CLI_VERSION = packageJson.version;
 export const SUPPORTED_CONFIG_VERSIONS = ['0.1'];
 export const CURRENT_CONFIG_VERSION = '0.1';
-export const AGENT_CORE_CAPABILITY_VERSION = '0.4.2';
+export const AGENT_CORE_CAPABILITY_VERSION = '0.5.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-creator/cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "CLI for creating projects powered by @agent-creator/core.",
   "type": "module",
   "bin": {