opc-agent 1.3.2 → 1.4.0

package/dist/traces/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OPC Agent Traces — Structured logging for agent actions.
+ *
+ * Collects traces that can be fed to DeepBrain's learn() API.
+ * Inspired by OpenTelemetry spans.
+ */
+export interface Span {
+    traceId: string;
+    spanId: string;
+    name: string;
+    startTime: Date;
+    endTime?: Date;
+    attributes: Record<string, string | number | boolean>;
+    events: SpanEvent[];
+    status: 'ok' | 'error' | 'unset';
+}
+export interface SpanEvent {
+    name: string;
+    timestamp: Date;
+    attributes?: Record<string, string | number | boolean>;
+}
+export interface TraceExporter {
+    export(spans: Span[]): Promise<void>;
+}
+/** In-memory buffer that holds spans until flushed */
+export declare class TraceCollector {
+    private spans;
+    private exporters;
+    private maxBufferSize;
+    constructor(maxBufferSize?: number);
+    addExporter(exporter: TraceExporter): void;
+    startSpan(name: string, attributes?: Record<string, string | number | boolean>): Span;
+    endSpan(span: Span, status?: 'ok' | 'error'): void;
+    addEvent(span: Span, name: string, attributes?: Record<string, string | number | boolean>): void;
+    flush(): Promise<number>;
+    getBufferedSpans(): readonly Span[];
+    get bufferedCount(): number;
+}
+/** Console exporter for development */
+export declare class ConsoleExporter implements TraceExporter {
+    export(spans: Span[]): Promise<void>;
+}
+/** DeepBrain exporter — sends traces to DeepBrain learn() */
+export declare class DeepBrainExporter implements TraceExporter {
+    private learnEndpoint;
+    constructor(deepbrainUrl?: string);
+    export(spans: Span[]): Promise<void>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/traces/index.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * OPC Agent Traces — Structured logging for agent actions.
+ *
+ * Collects traces that can be fed to DeepBrain's learn() API.
+ * Inspired by OpenTelemetry spans.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeepBrainExporter = exports.ConsoleExporter = exports.TraceCollector = void 0;
+/** In-memory buffer that holds spans until flushed */
+class TraceCollector {
+    spans = [];
+    exporters = [];
+    maxBufferSize;
+    constructor(maxBufferSize = 100) {
+        this.maxBufferSize = maxBufferSize;
+    }
+    addExporter(exporter) {
+        this.exporters.push(exporter);
+    }
+    startSpan(name, attributes = {}) {
+        const span = {
+            traceId: crypto.randomUUID(),
+            spanId: crypto.randomUUID().slice(0, 16),
+            name,
+            startTime: new Date(),
+            attributes,
+            events: [],
+            status: 'unset',
+        };
+        this.spans.push(span);
+        if (this.spans.length >= this.maxBufferSize) {
+            this.flush().catch(() => { }); // Best effort
+        }
+        return span;
+    }
+    endSpan(span, status = 'ok') {
+        span.endTime = new Date();
+        span.status = status;
+    }
+    addEvent(span, name, attributes) {
+        span.events.push({ name, timestamp: new Date(), attributes });
+    }
+    async flush() {
+        const toExport = [...this.spans];
+        this.spans = [];
+        for (const exporter of this.exporters) {
+            await exporter.export(toExport);
+        }
+        return toExport.length;
+    }
+    getBufferedSpans() {
+        return this.spans;
+    }
+    get bufferedCount() {
+        return this.spans.length;
+    }
+}
+exports.TraceCollector = TraceCollector;
+/** Console exporter for development */
+class ConsoleExporter {
+    async export(spans) {
+        for (const span of spans) {
+            const duration = span.endTime
+                ? `${span.endTime.getTime() - span.startTime.getTime()}ms`
+                : 'ongoing';
+            console.log(`[TRACE] ${span.name} (${duration}) [${span.status}]`);
+        }
+    }
+}
+exports.ConsoleExporter = ConsoleExporter;
+/** DeepBrain exporter — sends traces to DeepBrain learn() */
+class DeepBrainExporter {
+    learnEndpoint;
+    constructor(deepbrainUrl = 'http://localhost:3333') {
+        this.learnEndpoint = `${deepbrainUrl}/api/learn`;
+    }
+    async export(spans) {
+        for (const span of spans) {
+            try {
+                await fetch(this.learnEndpoint, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        action: span.name,
+                        result: span.status === 'ok' ? 'success' : 'error',
+                        context: {
+                            ...span.attributes,
+                            duration: span.endTime ? span.endTime.getTime() - span.startTime.getTime() : null,
+                            events: span.events.map(e => e.name),
+                        },
+                    }),
+                });
+            }
+            catch {
+                // Best effort — don't break agent if brain is down
+            }
+        }
+    }
+}
+exports.DeepBrainExporter = DeepBrainExporter;
+//# sourceMappingURL=index.js.map

package/docs/.vitepress/config.ts

@@ -1,103 +1,103 @@
-import { defineConfig } from 'vitepress';
-
-export default defineConfig({
-  title: 'OPC Agent',
-  description: 'Open Agent Framework - Build, test, and run AI Agents for business workstations',
-  
-  locales: {
-    root: {
-      label: 'English',
-      lang: 'en',
-      themeConfig: {
-        nav: [
-          { text: 'Guide', link: '/guide/getting-started' },
-          { text: 'API', link: '/api/oad-schema' },
-          { text: 'GitHub', link: 'https://github.com/Deepleaper/opc-agent' },
-        ],
-        sidebar: {
-          '/guide/': [
-            {
-              text: 'Introduction',
-              items: [
-                { text: 'Getting Started', link: '/guide/getting-started' },
-                { text: 'Core Concepts', link: '/guide/concepts' },
-              ],
-            },
-            {
-              text: 'Usage',
-              items: [
-                { text: 'Templates', link: '/guide/templates' },
-                { text: 'Configuration', link: '/guide/configuration' },
-                { text: 'Testing', link: '/guide/testing' },
-                { text: 'Deployment', link: '/guide/deployment' },
-              ],
-            },
-          ],
-          '/api/': [
-            {
-              text: 'Reference',
-              items: [
-                { text: 'OAD Schema', link: '/api/oad-schema' },
-                { text: 'CLI Commands', link: '/api/cli' },
-                { text: 'SDK', link: '/api/sdk' },
-              ],
-            },
-          ],
-        },
-      },
-    },
-    zh: {
-      label: '中文',
-      lang: 'zh-CN',
-      description: '开放智能体框架 — 构建、测试、运行企业级 AI 智能体',
-      themeConfig: {
-        nav: [
-          { text: '指南', link: '/zh/guide/getting-started' },
-          { text: 'API', link: '/zh/api/oad-schema' },
-          { text: 'GitHub', link: 'https://github.com/Deepleaper/opc-agent' },
-        ],
-        sidebar: {
-          '/zh/guide/': [
-            {
-              text: '入门',
-              items: [
-                { text: '快速开始', link: '/zh/guide/getting-started' },
-                { text: '核心概念', link: '/zh/guide/concepts' },
-              ],
-            },
-            {
-              text: '使用',
-              items: [
-                { text: '模板', link: '/zh/guide/templates' },
-                { text: '配置', link: '/zh/guide/configuration' },
-                { text: '测试', link: '/zh/guide/testing' },
-                { text: '部署', link: '/zh/guide/deployment' },
-              ],
-            },
-          ],
-          '/zh/api/': [
-            {
-              text: '参考',
-              items: [
-                { text: 'OAD Schema', link: '/zh/api/oad-schema' },
-                { text: 'CLI 命令', link: '/zh/api/cli' },
-                { text: 'SDK', link: '/zh/api/sdk' },
-              ],
-            },
-          ],
-        },
-      },
-    },
-  },
-
-  themeConfig: {
-    logo: '/logo.svg',
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/Deepleaper/opc-agent' },
-    ],
-    footer: {
-      message: 'Released under the Apache-2.0 License.',
-      copyright: 'Copyright © 2025 Deepleaper 跃盟科技',
-    },
-  },
-});
+import { defineConfig } from 'vitepress';
+
+export default defineConfig({
+  title: 'OPC Agent',
+  description: 'Open Agent Framework - Build, test, and run AI Agents for business workstations',
+  
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en',
+      themeConfig: {
+        nav: [
+          { text: 'Guide', link: '/guide/getting-started' },
+          { text: 'API', link: '/api/oad-schema' },
+          { text: 'GitHub', link: 'https://github.com/Deepleaper/opc-agent' },
+        ],
+        sidebar: {
+          '/guide/': [
+            {
+              text: 'Introduction',
+              items: [
+                { text: 'Getting Started', link: '/guide/getting-started' },
+                { text: 'Core Concepts', link: '/guide/concepts' },
+              ],
+            },
+            {
+              text: 'Usage',
+              items: [
+                { text: 'Templates', link: '/guide/templates' },
+                { text: 'Configuration', link: '/guide/configuration' },
+                { text: 'Testing', link: '/guide/testing' },
+                { text: 'Deployment', link: '/guide/deployment' },
+              ],
+            },
+          ],
+          '/api/': [
+            {
+              text: 'Reference',
+              items: [
+                { text: 'OAD Schema', link: '/api/oad-schema' },
+                { text: 'CLI Commands', link: '/api/cli' },
+                { text: 'SDK', link: '/api/sdk' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+    zh: {
+      label: '中文',
+      lang: 'zh-CN',
+      description: '开放智能体框架 — 构建、测试、运行企业级 AI 智能体',
+      themeConfig: {
+        nav: [
+          { text: '指南', link: '/zh/guide/getting-started' },
+          { text: 'API', link: '/zh/api/oad-schema' },
+          { text: 'GitHub', link: 'https://github.com/Deepleaper/opc-agent' },
+        ],
+        sidebar: {
+          '/zh/guide/': [
+            {
+              text: '入门',
+              items: [
+                { text: '快速开始', link: '/zh/guide/getting-started' },
+                { text: '核心概念', link: '/zh/guide/concepts' },
+              ],
+            },
+            {
+              text: '使用',
+              items: [
+                { text: '模板', link: '/zh/guide/templates' },
+                { text: '配置', link: '/zh/guide/configuration' },
+                { text: '测试', link: '/zh/guide/testing' },
+                { text: '部署', link: '/zh/guide/deployment' },
+              ],
+            },
+          ],
+          '/zh/api/': [
+            {
+              text: '参考',
+              items: [
+                { text: 'OAD Schema', link: '/zh/api/oad-schema' },
+                { text: 'CLI 命令', link: '/zh/api/cli' },
+                { text: 'SDK', link: '/zh/api/sdk' },
+              ],
+            },
+          ],
+        },
+      },
+    },
+  },
+
+  themeConfig: {
+    logo: '/logo.svg',
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Deepleaper/opc-agent' },
+    ],
+    footer: {
+      message: 'Released under the Apache-2.0 License.',
+      copyright: 'Copyright © 2025 Deepleaper 跃盟科技',
+    },
+  },
+});

package/docs/api/cli.md

@@ -1,48 +1,48 @@
-# CLI Commands
-
-## Reference
-
-| Command | Description |
-|---------|-------------|
-| `opc init [name]` | Initialize a new agent project |
-| `opc run` | Start agent with web server |
-| `opc chat` | Interactive CLI chat |
-| `opc test` | Run agent tests |
-| `opc analytics` | Show usage analytics |
-| `opc info` | Show agent info from OAD |
-| `opc build` | Validate OAD |
-| `opc dev` | Hot-reload development mode |
-| `opc create <name>` | Create agent from template |
-| `opc deploy` | Deploy to OpenClaw or Hermes |
-| `opc publish` | Package for distribution |
-| `opc install <source>` | Install agent from package |
-| `opc search <query>` | Search OPC Registry |
-| `opc stats` | Show runtime stats |
-| `opc kb add <file>` | Add file to knowledge base |
-| `opc kb search <query>` | Search knowledge base |
-| `opc tool list` | List MCP tools |
-| `opc workflow run <name>` | Run a workflow |
-| `opc version-mgmt list` | List saved versions |
-
-## Common Options
-
-- `-f, --file <file>` — OAD file path (default: `oad.yaml`)
-- `-t, --template <name>` — Template name
-- `-p, --port <port>` — Port override
-- `--json` — JSON output (for test/analytics)
-
-## Examples
-
-```bash
-# Create a new project
-opc init my-bot -t teacher
-
-# Run tests
-opc test --json
-
-# View analytics
-opc analytics
-
-# Deploy
-opc deploy --target openclaw --install
-```
+# CLI Commands
+
+## Reference
+
+| Command | Description |
+|---------|-------------|
+| `opc init [name]` | Initialize a new agent project |
+| `opc run` | Start agent with web server |
+| `opc chat` | Interactive CLI chat |
+| `opc test` | Run agent tests |
+| `opc analytics` | Show usage analytics |
+| `opc info` | Show agent info from OAD |
+| `opc build` | Validate OAD |
+| `opc dev` | Hot-reload development mode |
+| `opc create <name>` | Create agent from template |
+| `opc deploy` | Deploy to OpenClaw or Hermes |
+| `opc publish` | Package for distribution |
+| `opc install <source>` | Install agent from package |
+| `opc search <query>` | Search OPC Registry |
+| `opc stats` | Show runtime stats |
+| `opc kb add <file>` | Add file to knowledge base |
+| `opc kb search <query>` | Search knowledge base |
+| `opc tool list` | List MCP tools |
+| `opc workflow run <name>` | Run a workflow |
+| `opc version-mgmt list` | List saved versions |
+
+## Common Options
+
+- `-f, --file <file>` — OAD file path (default: `oad.yaml`)
+- `-t, --template <name>` — Template name
+- `-p, --port <port>` — Port override
+- `--json` — JSON output (for test/analytics)
+
+## Examples
+
+```bash
+# Create a new project
+opc init my-bot -t teacher
+
+# Run tests
+opc test --json
+
+# View analytics
+opc analytics
+
+# Deploy
+opc deploy --target openclaw --install
+```

package/docs/api/oad-schema.md

@@ -1,64 +1,64 @@
-# OAD Schema v1 Specification
-
-**OAD** (Open Agent Definition) is a declarative YAML/JSON format for defining AI agents.
-
-## Full Schema
-
-```yaml
-apiVersion: opc/v1          # Required. Must be "opc/v1"
-kind: Agent                  # Required. Must be "Agent"
-
-metadata:
-  name: string               # Required. Agent identifier
-  version: string            # Semver. Default: "1.0.0"
-  description: string        # Optional. Human-readable description
-  author: string             # Optional. Author name
-  license: string            # Default: "Apache-2.0"
-  marketplace:               # Optional. Marketplace settings
-    certified: boolean       # Default: false
-    category: string         # e.g., "customer-service"
-
-spec:
-  provider:                  # LLM provider configuration
-    default: string          # Default provider. Default: "deepseek"
-    allowed: string[]        # Allowed providers. Default: ["openai", "deepseek", "qwen"]
-  model: string              # Model name. Default: "deepseek-chat"
-  systemPrompt: string       # System prompt for the agent
-
-  skills:                    # List of skills
-    - name: string           # Skill identifier
-      description: string    # What the skill does
-      config: object         # Optional skill-specific config
-
-  channels:                  # Communication channels
-    - type: web|websocket|cli
-      port: number           # Port for web channels
-      config: object         # Optional channel config
-
-  memory:
-    shortTerm: boolean       # Enable conversation memory. Default: true
-    longTerm: boolean        # Enable persistent memory. Default: false
-    provider: string         # Memory backend (optional)
-
-  dtv:
-    trust:
-      level: sandbox|verified|certified|listed  # Default: "sandbox"
-    value:
-      metrics: string[]      # Metrics to track. Default: []
-```
-
-## Validation
-
-OAD files are validated using Zod schemas. Use the CLI to validate:
-
-```bash
-opc build -f oad.yaml
-```
-
-Or programmatically:
-
-```typescript
-import { validateOAD } from 'opc-agent';
-
-const config = validateOAD(yamlData);
-```
+# OAD Schema v1 Specification
+
+**OAD** (Open Agent Definition) is a declarative YAML/JSON format for defining AI agents.
+
+## Full Schema
+
+```yaml
+apiVersion: opc/v1          # Required. Must be "opc/v1"
+kind: Agent                  # Required. Must be "Agent"
+
+metadata:
+  name: string               # Required. Agent identifier
+  version: string            # Semver. Default: "1.0.0"
+  description: string        # Optional. Human-readable description
+  author: string             # Optional. Author name
+  license: string            # Default: "Apache-2.0"
+  marketplace:               # Optional. Marketplace settings
+    certified: boolean       # Default: false
+    category: string         # e.g., "customer-service"
+
+spec:
+  provider:                  # LLM provider configuration
+    default: string          # Default provider. Default: "deepseek"
+    allowed: string[]        # Allowed providers. Default: ["openai", "deepseek", "qwen"]
+  model: string              # Model name. Default: "deepseek-chat"
+  systemPrompt: string       # System prompt for the agent
+
+  skills:                    # List of skills
+    - name: string           # Skill identifier
+      description: string    # What the skill does
+      config: object         # Optional skill-specific config
+
+  channels:                  # Communication channels
+    - type: web|websocket|cli
+      port: number           # Port for web channels
+      config: object         # Optional channel config
+
+  memory:
+    shortTerm: boolean       # Enable conversation memory. Default: true
+    longTerm: boolean        # Enable persistent memory. Default: false
+    provider: string         # Memory backend (optional)
+
+  dtv:
+    trust:
+      level: sandbox|verified|certified|listed  # Default: "sandbox"
+    value:
+      metrics: string[]      # Metrics to track. Default: []
+```
+
+## Validation
+
+OAD files are validated using Zod schemas. Use the CLI to validate:
+
+```bash
+opc build -f oad.yaml
+```
+
+Or programmatically:
+
+```typescript
+import { validateOAD } from 'opc-agent';
+
+const config = validateOAD(yamlData);
+```