@bluefly/openstandardagents 0.4.9 → 0.5.1

package/dist/types/index.js

@@ -10,7 +10,7 @@ export * from './task.js';
 export { createTaskManifest, isOssaTask } from './task.js';
 // Export Workflow types (v0.3.0)
 export * from './workflow.js';
-export { createStep, createWorkflowManifest, expr, isOssaWorkflow } from './workflow.js';
+export { createStep, createWorkflowManifest, expr, isOssaWorkflow, } from './workflow.js';
 // Export Messaging types (v0.3.0)
 export * from './messaging.js';
 // Export Identity & Adapter types (v0.3.6)
@@ -21,8 +21,12 @@ export * from './architect.js';
 export * from './security.js';
 // Export Skill types (AgentSkills / OSSA skills)
 export { isOssaSkill } from './skill.js';
+// Export Role types (v0.5 — IDE operator contexts)
+export { createRoleManifest, isOssaRole } from './role.js';
 // Export MCP server manifest types
 export { isOssaMCPServer } from './mcp-server-manifest.js';
-// Export Protocol Declaration types (v0.5)
+// Export Cognition types (v0.4 — CAOE)
+export * from './cognition.zod.js';
+// v0.5: Protocol Declarations
 export * from './protocols.js';
 //# sourceMappingURL=index.js.map

package/dist/types/personality.zod.d.ts

@@ -165,9 +165,9 @@ export declare const ExpertiseEntrySchema: z.ZodObject<{
     specializations: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const UncertaintyHandlingSchema: z.ZodEnum<{
+    defer: "defer";
     acknowledge: "acknowledge";
     investigate: "investigate";
-    defer: "defer";
     estimate: "estimate";
 }>;
 export declare const ErrorResponseSchema: z.ZodEnum<{
@@ -202,9 +202,9 @@ export declare const RiskToleranceSchema: z.ZodEnum<{
 }>;
 export declare const BehavioralTraitsSchema: z.ZodObject<{
     uncertainty_handling: z.ZodOptional<z.ZodEnum<{
+        defer: "defer";
         acknowledge: "acknowledge";
         investigate: "investigate";
-        defer: "defer";
         estimate: "estimate";
     }>>;
     error_response: z.ZodOptional<z.ZodEnum<{
@@ -403,9 +403,9 @@ export declare const PersonalitySpecSchema: z.ZodObject<{
     description: z.ZodOptional<z.ZodString>;
     traits: z.ZodOptional<z.ZodObject<{
         uncertainty_handling: z.ZodOptional<z.ZodEnum<{
+            defer: "defer";
             acknowledge: "acknowledge";
             investigate: "investigate";
-            defer: "defer";
             estimate: "estimate";
         }>>;
         error_response: z.ZodOptional<z.ZodEnum<{

package/dist/types/role.d.ts

@@ -0,0 +1,126 @@
+/**
+ * OSSA Role Manifest Types
+ * Type definitions for role.ossa.yaml manifests (kind: Role)
+ *
+ * Roles define behavioral overlays for IDE/CLI agents (Claude Code, Cursor, etc.)
+ * Unlike Agents (autonomous loops), Roles configure operator context — instructions,
+ * tool access, hooks, MCP connections, and activation conditions.
+ */
+export interface OssaRole {
+    apiVersion: string;
+    kind: 'Role';
+    metadata: RoleMetadata;
+    spec: RoleSpec;
+    extensions?: Record<string, unknown>;
+}
+export interface RoleMetadata {
+    /** DNS-style role name (lowercase, hyphens) */
+    name: string;
+    /** Semantic version */
+    version?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Key-value labels for filtering and categorization */
+    labels?: Record<string, string>;
+    /** Non-identifying metadata */
+    annotations?: Record<string, string>;
+}
+export interface RoleSpec {
+    /** System prompt / persona definition */
+    role?: string;
+    /** Behavioral instructions */
+    instructions?: RoleInstructions;
+    /** Tool access configuration */
+    tools?: RoleTools;
+    /** Lifecycle hooks */
+    hooks?: RoleHooks;
+    /** Context injection */
+    context?: RoleContext;
+    /** Protocol connections */
+    protocols?: RoleProtocols;
+    /** Role composition — inherit from other roles */
+    extends?: RoleExtension[];
+    /** Activation conditions */
+    activation?: RoleActivation;
+}
+export interface RoleInstructions {
+    /** Markdown content prepended to every conversation */
+    preamble?: string;
+    /** Hard rules — MUST/MUST NOT statements */
+    constraints?: string[];
+}
+export interface RoleTools {
+    /** Whitelist of allowed tool names */
+    allowed?: string[];
+    /** Blacklist of denied tool names (overrides allowed) */
+    denied?: string[];
+    /** References to OSSA Skill manifests */
+    skills?: string[];
+}
+export interface RoleHooks {
+    /** Run when role is activated */
+    on_activate?: string;
+    /** Run when switching away from this role */
+    on_deactivate?: string;
+    /** Run before git commits */
+    pre_commit?: string;
+    /** Run after file saves */
+    post_save?: string;
+}
+export interface RoleContext {
+    /** Paths to JSON Schema or OpenAPI spec files */
+    schemas?: string[];
+    /** Files to include in agent context */
+    files?: RoleContextFile[];
+    /** Paths to knowledge base documents */
+    knowledge?: string[];
+}
+export interface RoleContextFile {
+    /** File path or glob pattern */
+    path: string;
+    /** Description of what this file provides */
+    description?: string;
+}
+export interface RoleProtocols {
+    /** MCP server connections */
+    mcp?: RoleMCPConfig;
+}
+export interface RoleMCPConfig {
+    /** MCP servers available when this role is active */
+    servers?: RoleMCPServer[];
+}
+export interface RoleMCPServer {
+    /** Server identifier */
+    name: string;
+    /** Transport type */
+    transport: 'stdio' | 'sse';
+    /** Command to spawn (stdio transport) */
+    command?: string;
+    /** Command arguments (stdio transport) */
+    args?: string[];
+    /** Endpoint URL (SSE transport) */
+    url?: string;
+}
+export interface RoleExtension {
+    /** Name of the parent role to inherit from */
+    role: string;
+    /** If true, child fields replace parent fields; if false, they merge */
+    override?: boolean;
+}
+export interface RoleActivation {
+    /** Glob patterns — activate when matching files are open */
+    file_patterns?: string[];
+    /** CLI command to activate (e.g., "/role drupal") */
+    command?: string;
+    /** Environment variable conditions (all must match) */
+    env?: Record<string, string>;
+}
+/**
+ * Type guard for OssaRole
+ */
+export declare function isOssaRole(obj: unknown): obj is OssaRole;
+/**
+ * Create a minimal OssaRole manifest
+ */
+export declare function createRoleManifest(name: string, description: string, role?: string): OssaRole;
+//# sourceMappingURL=role.d.ts.map

package/dist/types/role.js

@@ -0,0 +1,38 @@
+/**
+ * OSSA Role Manifest Types
+ * Type definitions for role.ossa.yaml manifests (kind: Role)
+ *
+ * Roles define behavioral overlays for IDE/CLI agents (Claude Code, Cursor, etc.)
+ * Unlike Agents (autonomous loops), Roles configure operator context — instructions,
+ * tool access, hooks, MCP connections, and activation conditions.
+ */
+/**
+ * Type guard for OssaRole
+ */
+export function isOssaRole(obj) {
+    if (!obj || typeof obj !== 'object')
+        return false;
+    const o = obj;
+    return (o.kind === 'Role' &&
+        typeof o.apiVersion === 'string' &&
+        o.metadata != null &&
+        o.spec != null);
+}
+/**
+ * Create a minimal OssaRole manifest
+ */
+export function createRoleManifest(name, description, role) {
+    return {
+        apiVersion: 'ossa/v0.5',
+        kind: 'Role',
+        metadata: {
+            name,
+            version: '1.0.0',
+            description,
+        },
+        spec: {
+            ...(role ? { role } : {}),
+        },
+    };
+}
+//# sourceMappingURL=role.js.map

package/dist/utils/http-client.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OSSA HTTP Client — wraps fetch with proxy support and standard user-agent.
+ *
+ * Two usage patterns:
+ * 1. Direct: `import { ossaFetch } from './http-client.js'` — explicit proxy+UA fetch
+ * 2. Global: `import { installGlobalFetch } from './http-client.js'` — patches globalThis.fetch
+ *    so ALL existing fetch() calls automatically get proxy + UA. Call once at startup.
+ */
+export interface OssaFetchOptions extends RequestInit {
+    agentName?: string;
+}
+/**
+ * Proxy-aware fetch with standard OSSA user-agent header.
+ * Drop-in replacement for fetch() — same API, adds proxy + UA automatically.
+ */
+export declare function ossaFetch(url: string | URL, options?: OssaFetchOptions): Promise<Response>;
+/**
+ * Patch globalThis.fetch so ALL fetch() calls in the process get proxy + UA.
+ * Call once at CLI entry point. Safe to call multiple times (idempotent).
+ */
+export declare function installGlobalFetch(): void;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/utils/http-client.js

@@ -0,0 +1,51 @@
+/**
+ * OSSA HTTP Client — wraps fetch with proxy support and standard user-agent.
+ *
+ * Two usage patterns:
+ * 1. Direct: `import { ossaFetch } from './http-client.js'` — explicit proxy+UA fetch
+ * 2. Global: `import { installGlobalFetch } from './http-client.js'` — patches globalThis.fetch
+ *    so ALL existing fetch() calls automatically get proxy + UA. Call once at startup.
+ */
+import { getProxyAgent } from './proxy-resolver.js';
+import { getOssaUserAgent } from './user-agent.js';
+/**
+ * Proxy-aware fetch with standard OSSA user-agent header.
+ * Drop-in replacement for fetch() — same API, adds proxy + UA automatically.
+ */
+export async function ossaFetch(url, options = {}) {
+    const { agentName, ...fetchOpts } = options;
+    const headers = new Headers(fetchOpts.headers);
+    if (!headers.has('user-agent')) {
+        headers.set('user-agent', getOssaUserAgent(agentName));
+    }
+    const dispatcher = getProxyAgent();
+    return fetch(url, {
+        ...fetchOpts,
+        headers,
+        ...(dispatcher ? { dispatcher } : {}),
+    });
+}
+let installed = false;
+/**
+ * Patch globalThis.fetch so ALL fetch() calls in the process get proxy + UA.
+ * Call once at CLI entry point. Safe to call multiple times (idempotent).
+ */
+export function installGlobalFetch() {
+    if (installed)
+        return;
+    installed = true;
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = async function patchedFetch(input, init) {
+        const headers = new Headers(init?.headers);
+        if (!headers.has('user-agent')) {
+            headers.set('user-agent', getOssaUserAgent());
+        }
+        const dispatcher = getProxyAgent();
+        return originalFetch(input, {
+            ...init,
+            headers,
+            ...(dispatcher ? { dispatcher } : {}),
+        });
+    };
+}
+//# sourceMappingURL=http-client.js.map

package/dist/utils/index.d.ts

@@ -6,4 +6,7 @@ export * from './version.js';
 export * from './type-guards.js';
 export * from './constants.js';
 export * from './yaml-parser.js';
+export * from './proxy-resolver.js';
+export * from './user-agent.js';
+export * from './http-client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -6,4 +6,7 @@ export * from './version.js';
 export * from './type-guards.js';
 export * from './constants.js';
 export * from './yaml-parser.js';
+export * from './proxy-resolver.js';
+export * from './user-agent.js';
+export * from './http-client.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/proxy-resolver.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Proxy Resolver — Auto-detect and configure HTTP proxies for all agent HTTP clients.
+ *
+ * Uses proxy-agent to support HTTP, HTTPS, SOCKS4/5, and PAC proxies.
+ * Respects HTTP_PROXY, HTTPS_PROXY, NO_PROXY environment variables.
+ *
+ * Usage:
+ *   import { getProxyAgent } from './proxy-resolver';
+ *   const agent = getProxyAgent();
+ *   fetch(url, { agent });
+ */
+import type { Agent } from 'http';
+/**
+ * Get a proxy-aware HTTP agent. Auto-detects from env vars:
+ * - HTTP_PROXY / http_proxy
+ * - HTTPS_PROXY / https_proxy
+ * - NO_PROXY / no_proxy
+ * - ALL_PROXY / all_proxy
+ *
+ * Returns undefined if no proxy is configured (direct connection).
+ */
+export declare function getProxyAgent(): Agent | undefined;
+/**
+ * Check if a proxy is configured in the environment.
+ */
+export declare function isProxyConfigured(): boolean;
+/**
+ * Get proxy configuration summary for diagnostics/logging.
+ */
+export declare function getProxyInfo(): {
+    configured: boolean;
+    httpProxy?: string;
+    httpsProxy?: string;
+    noProxy?: string;
+};
+//# sourceMappingURL=proxy-resolver.d.ts.map

package/dist/utils/proxy-resolver.js

@@ -0,0 +1,59 @@
+/**
+ * Proxy Resolver — Auto-detect and configure HTTP proxies for all agent HTTP clients.
+ *
+ * Uses proxy-agent to support HTTP, HTTPS, SOCKS4/5, and PAC proxies.
+ * Respects HTTP_PROXY, HTTPS_PROXY, NO_PROXY environment variables.
+ *
+ * Usage:
+ *   import { getProxyAgent } from './proxy-resolver';
+ *   const agent = getProxyAgent();
+ *   fetch(url, { agent });
+ */
+import { ProxyAgent } from 'proxy-agent';
+let cachedAgent;
+/**
+ * Get a proxy-aware HTTP agent. Auto-detects from env vars:
+ * - HTTP_PROXY / http_proxy
+ * - HTTPS_PROXY / https_proxy
+ * - NO_PROXY / no_proxy
+ * - ALL_PROXY / all_proxy
+ *
+ * Returns undefined if no proxy is configured (direct connection).
+ */
+export function getProxyAgent() {
+    const proxyUrl = process.env.HTTP_PROXY ||
+        process.env.http_proxy ||
+        process.env.HTTPS_PROXY ||
+        process.env.https_proxy ||
+        process.env.ALL_PROXY ||
+        process.env.all_proxy;
+    if (!proxyUrl)
+        return undefined;
+    if (!cachedAgent) {
+        cachedAgent = new ProxyAgent();
+    }
+    return cachedAgent;
+}
+/**
+ * Check if a proxy is configured in the environment.
+ */
+export function isProxyConfigured() {
+    return !!(process.env.HTTP_PROXY ||
+        process.env.http_proxy ||
+        process.env.HTTPS_PROXY ||
+        process.env.https_proxy ||
+        process.env.ALL_PROXY ||
+        process.env.all_proxy);
+}
+/**
+ * Get proxy configuration summary for diagnostics/logging.
+ */
+export function getProxyInfo() {
+    return {
+        configured: isProxyConfigured(),
+        httpProxy: process.env.HTTP_PROXY || process.env.http_proxy,
+        httpsProxy: process.env.HTTPS_PROXY || process.env.https_proxy,
+        noProxy: process.env.NO_PROXY || process.env.no_proxy,
+    };
+}
+//# sourceMappingURL=proxy-resolver.js.map

package/dist/utils/user-agent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * User Agent — Consistent identification for all OSSA agent HTTP requests.
+ *
+ * Uses universal-user-agent for cross-runtime compatibility.
+ */
+/**
+ * Get the OSSA user-agent string for HTTP requests.
+ * Format: ossa-cli/{version} ({agentName}) {runtimeUA}
+ */
+export declare function getOssaUserAgent(agentName?: string): string;
+//# sourceMappingURL=user-agent.d.ts.map

package/dist/utils/user-agent.js

@@ -0,0 +1,17 @@
+/**
+ * User Agent — Consistent identification for all OSSA agent HTTP requests.
+ *
+ * Uses universal-user-agent for cross-runtime compatibility.
+ */
+import { getUserAgent } from 'universal-user-agent';
+const BASE_USER_AGENT = getUserAgent();
+/**
+ * Get the OSSA user-agent string for HTTP requests.
+ * Format: ossa-cli/{version} ({agentName}) {runtimeUA}
+ */
+export function getOssaUserAgent(agentName) {
+    const version = process.env.npm_package_version || '0.5.1';
+    const agent = agentName ? ` (${agentName})` : '';
+    return `ossa-cli/${version}${agent} ${BASE_USER_AGENT}`;
+}
+//# sourceMappingURL=user-agent.js.map

package/dist/validation/validator.js

@@ -22,7 +22,7 @@ export class OSSAValidator {
         });
         addFormats(this.ajv);
         // Load schema
-        const defaultSchemaPath = join(__dirname, '../spec/v0.4/agent.schema.json');
+        const defaultSchemaPath = join(__dirname, '../spec/v0.5/agent.schema.json');
         const resolvedPath = schemaPath || defaultSchemaPath;
         try {
             const schemaContent = readFileSync(resolvedPath, 'utf-8');

package/dist/validation/version-compliance.js

@@ -7,7 +7,7 @@ export const MIN_API_VERSION_ALLOWED = {
     'ossa/v0.4': new Set([
         'ossa/v0.4',
         'ossa/v0.4.1',
-        'ossa.bluefly.io/v1alpha1',
+        'ossa/v0.5.1',
     ]),
 };
 /**

package/examples/agents/01-customer-support-bot/agent.ossa.yaml

@@ -1,4 +1,4 @@
-apiVersion: ossa/v0.4.7
+apiVersion: ossa/v0.5
 kind: Agent
 metadata:
   name: customer-support-bot
@@ -26,19 +26,16 @@ spec:
     - Clear and concise explanations
     - Proactive in offering solutions
     - Transparent about limitations
-
   llm:
     provider: openai
     model: gpt-4o
     temperature: 0.7
     maxTokens: 1500
-
   capabilities:
     - search_documentation
     - create_ticket
     - send_email
     - conversation_memory
-
   tools:
     - type: function
       name: search_docs
@@ -55,7 +52,6 @@ spec:
             default: 5
         required:
           - query
-
     - type: function
       name: create_ticket
       description: Create a support ticket for issues requiring human attention
@@ -70,7 +66,11 @@ spec:
             description: Detailed description of the issue
           priority:
             type: string
-            enum: [low, medium, high, urgent]
+            enum:
+              - low
+              - medium
+              - high
+              - urgent
             description: Priority level of the ticket
           category:
             type: string
@@ -79,7 +79,6 @@ spec:
           - title
           - description
           - priority
-
     - type: function
       name: send_email
       description: Send follow-up email to customer
@@ -98,12 +97,14 @@ spec:
           template:
             type: string
             description: Email template to use
-            enum: [follow_up, resolution, escalation]
+            enum:
+              - follow_up
+              - resolution
+              - escalation
         required:
           - to
           - subject
           - body
-
   autonomy:
     level: supervised
     approval_required: false
@@ -112,7 +113,6 @@ spec:
         action: notify_human
       - condition: ticket_count > 3
         action: escalate
-
   memory:
     enabled: true
     type: conversation_buffer
@@ -121,7 +121,6 @@ spec:
       enabled: true
       backend: redis
       ttl: 86400
-
   safety:
     input_filters:
       - type: pii_detection
@@ -132,8 +131,9 @@ spec:
       - type: hallucination_check
         threshold: 0.8
       - type: tone_analysis
-        required_sentiment: [positive, neutral]
-
+        required_sentiment:
+          - positive
+          - neutral
   observability:
     logging:
       level: info
@@ -150,23 +150,16 @@ spec:
     tracing:
       enabled: true
       provider: opentelemetry
-
 extensions:
   langchain:
-    agent_type: react
-    memory_type: conversation_buffer
-    chain_type: conversation
-    tools_mapping:
-      - ossa_capability: search_documentation
-        langchain_tool: search_docs
-        tool_class: CustomSearchTool
-      - ossa_capability: create_ticket
-        langchain_tool: create_ticket
-        tool_class: TicketingTool
-      - ossa_capability: send_email
-        langchain_tool: send_email
-        tool_class: EmailTool
-    export_config:
-      format: python
-      include_dependencies: true
-      output_file: customer_support_agent.py
+    enabled: true
+    chain_type: agent
+    memory:
+      type: buffer
+    tools:
+      - name: search_docs
+        description: Search the knowledge base for relevant documentation
+      - name: create_ticket
+        description: Create a support ticket for issues requiring human attention
+      - name: send_email
+        description: Send follow-up email to customer