@bluefly/openstandardagents 0.2.8 → 0.3.0

package/dist/spec/v0.2.9/types.ts

@@ -0,0 +1,522 @@
+/**
+ * OSSA Type System v0.2.9
+ *
+ * Canonical TypeScript type definitions for OSSA runtime interoperability.
+ * These types define the contract between OSSA manifests and runtime implementations.
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Core Identity Types
+// =============================================================================
+
+/** UUID v4 string format */
+export type UUID = string;
+
+/** ISO 8601 timestamp */
+export type ISO8601Timestamp = string;
+
+/** Semantic version string */
+export type SemVer = string;
+
+/** Agent identity at runtime */
+export interface AgentIdentity {
+  /** Agent definition ID from manifest metadata.name */
+  agent_id: string;
+  /** Agent version from manifest metadata.version */
+  agent_version: SemVer;
+  /** Runtime instance UUID (stable per pod/process) */
+  instance_id: UUID;
+  /** Session UUID (stable per conversation) */
+  session_id: UUID;
+  /** Interaction UUID (unique per turn) */
+  interaction_id: UUID;
+  /** Turn number within session */
+  turn_number: number;
+}
+
+// =============================================================================
+// Message Types
+// =============================================================================
+
+/** Message roles in conversation */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+
+/** Text content part */
+export interface TextPart {
+  type: 'text';
+  text: string;
+}
+
+/** Image content part */
+export interface ImagePart {
+  type: 'image';
+  source: {
+    type: 'base64' | 'url';
+    media_type: string;
+    data: string;
+  };
+}
+
+/** File content part */
+export interface FilePart {
+  type: 'file';
+  name: string;
+  content: string;
+  media_type: string;
+}
+
+/** Union of all content part types */
+export type ContentPart = TextPart | ImagePart | FilePart;
+
+/** Base message interface */
+export interface BaseMessage {
+  role: MessageRole;
+  metadata?: MessageMetadata;
+}
+
+/** User message */
+export interface UserMessage extends BaseMessage {
+  role: 'user';
+  content: string | ContentPart[];
+}
+
+/** Assistant/Agent message */
+export interface AssistantMessage extends BaseMessage {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: ToolCallRequest[];
+}
+
+/** System message */
+export interface SystemMessage extends BaseMessage {
+  role: 'system';
+  content: string;
+}
+
+/** Tool result message */
+export interface ToolMessage extends BaseMessage {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+}
+
+/** Union of all message types */
+export type Message = UserMessage | AssistantMessage | SystemMessage | ToolMessage;
+
+/** Message metadata */
+export interface MessageMetadata {
+  source: 'user' | 'api' | 'delegation';
+  original_format?: string;
+  normalized_at?: ISO8601Timestamp;
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Tool Types
+// =============================================================================
+
+/** Tool transport mechanisms */
+export type ToolTransport = 'function' | 'http' | 'mcp' | 'grpc';
+
+/** Tool source definition */
+export type ToolSource =
+  | { type: 'manifest'; tool_index: number }
+  | { type: 'mcp'; server_uri: string; capability: string }
+  | { type: 'delegation'; agent_id: string }
+  | { type: 'function'; handler: string };
+
+/** Resolved tool at runtime */
+export interface ResolvedTool {
+  name: string;
+  description: string;
+  input_schema: JSONSchema;
+  source: ToolSource;
+  transport: ToolTransport;
+  timeout_ms: number;
+  retry_policy?: RetryPolicy;
+}
+
+/** Tool call request from LLM */
+export interface ToolCallRequest {
+  id: string;
+  name: string;
+  arguments: string; // JSON string
+}
+
+/** Parsed tool call */
+export interface ToolCall {
+  id: string;
+  capability: string;
+  input: Record<string, unknown>;
+  transport?: ToolTransport;
+}
+
+/** Tool execution result */
+export type ToolResult =
+  | { status: 'success'; output: unknown }
+  | { status: 'error'; error: ToolError }
+  | { status: 'timeout'; partial_output?: unknown };
+
+/** Tool error details */
+export interface ToolError {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  retryable: boolean;
+}
+
+/** Tool execution record */
+export interface ToolExecution {
+  call_id: string;
+  tool_name: string;
+  input: unknown;
+  started_at: ISO8601Timestamp;
+  completed_at: ISO8601Timestamp;
+  result: ToolResult;
+  retries: number;
+  duration_ms: number;
+}
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+/** OSSA error codes taxonomy */
+export type ErrorCode =
+  // Input Errors (4xx equivalent)
+  | 'VALIDATION_ERROR'
+  | 'SCHEMA_VIOLATION'
+  | 'CONTENT_FILTERED'
+  | 'POLICY_VIOLATION'
+  // Execution Errors (5xx equivalent)
+  | 'TOOL_ERROR'
+  | 'TOOL_TIMEOUT'
+  | 'LLM_ERROR'
+  | 'LLM_TIMEOUT'
+  | 'STATE_ERROR'
+  // Resource Errors
+  | 'RATE_LIMITED'
+  | 'QUOTA_EXCEEDED'
+  | 'CIRCUIT_OPEN'
+  // Agent Errors
+  | 'MAX_TURNS_EXCEEDED'
+  | 'MAX_TOKENS_EXCEEDED'
+  | 'DELEGATION_FAILED'
+  | 'ESCALATION_REQUIRED';
+
+/** Structured OSSA error */
+export interface OSSAError {
+  code: ErrorCode;
+  message: string;
+  details?: Record<string, unknown>;
+  recoverable: boolean;
+  retry_after_ms?: number;
+  escalation?: EscalationAction;
+  cause?: Error;
+}
+
+/** Recovery strategies */
+export type RecoveryStrategy =
+  | 'retry'
+  | 'fallback'
+  | 'skip'
+  | 'escalate'
+  | 'abort';
+
+/** Escalation action */
+export interface EscalationAction {
+  type: 'human' | 'supervisor' | 'alert';
+  target?: string;
+  context?: Record<string, unknown>;
+}
+
+/** Error handler configuration */
+export interface ErrorHandler {
+  error_codes: ErrorCode[];
+  strategy: RecoveryStrategy;
+  max_retries?: number;
+  fallback_value?: unknown;
+  escalation_target?: string;
+}
+
+// =============================================================================
+// State Types
+// =============================================================================
+
+/** State isolation levels */
+export type IsolationLevel =
+  | 'read_uncommitted'
+  | 'read_committed'
+  | 'repeatable_read'
+  | 'serializable';
+
+/** State persistence modes */
+export type StateMode = 'none' | 'session' | 'persistent';
+
+/** State storage backends */
+export type StateStorageType =
+  | 'memory'
+  | 'redis'
+  | 'postgres'
+  | 'dynamodb'
+  | 'vector-db'
+  | 'custom';
+
+/** State change operation */
+export interface StateChange {
+  key: string;
+  previous_value: unknown | null;
+  new_value: unknown;
+  operation: 'set' | 'delete' | 'append';
+  timestamp: ISO8601Timestamp;
+}
+
+/** State transaction */
+export interface StateTransaction {
+  id: string;
+  started_at: ISO8601Timestamp;
+  changes: StateChange[];
+  status: 'pending' | 'committed' | 'rolled_back';
+}
+
+/** State operations interface */
+export interface StateOperations {
+  get<T>(key: string): Promise<T | null>;
+  getMany<T>(keys: string[]): Promise<Map<string, T>>;
+  exists(key: string): Promise<boolean>;
+  set<T>(key: string, value: T, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  append<T>(key: string, value: T): Promise<void>;
+  checkpoint(): Promise<string>;
+  rollback(checkpoint?: string): Promise<void>;
+}
+
+// =============================================================================
+// LLM Types
+// =============================================================================
+
+/** LLM provider identifiers */
+export type LLMProvider =
+  | 'openai'
+  | 'anthropic'
+  | 'google'
+  | 'azure'
+  | 'aws'
+  | 'mistral'
+  | 'groq'
+  | 'ollama'
+  | 'custom';
+
+/** LLM request parameters */
+export interface LLMParameters {
+  temperature?: number;
+  max_tokens?: number;
+  top_p?: number;
+  top_k?: number;
+  stop_sequences?: string[];
+  presence_penalty?: number;
+  frequency_penalty?: number;
+}
+
+/** LLM inference request */
+export interface InferenceRequest {
+  model: string;
+  messages: Message[];
+  tools?: ResolvedTool[];
+  system_prompt?: string;
+  parameters: LLMParameters;
+}
+
+/** LLM inference response */
+export interface InferenceResponse {
+  id: string;
+  content: string | null;
+  tool_calls: ToolCallRequest[];
+  finish_reason: FinishReason;
+  usage: TokenUsage;
+  model: string;
+}
+
+/** LLM finish reasons */
+export type FinishReason =
+  | 'stop'
+  | 'length'
+  | 'tool_use'
+  | 'content_filter'
+  | 'error';
+
+/** Token usage statistics */
+export interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+  cache_read_tokens?: number;
+  cache_write_tokens?: number;
+}
+
+// =============================================================================
+// Observability Types
+// =============================================================================
+
+/** W3C Trace Context */
+export interface W3CTraceContext {
+  traceparent: string;
+  tracestate?: string;
+}
+
+/** W3C Baggage */
+export interface W3CBaggage {
+  entries: Map<string, string>;
+}
+
+/** Log severity levels */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+
+/** Structured log entry */
+export interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: ISO8601Timestamp;
+  trace_id?: string;
+  span_id?: string;
+  attributes?: Record<string, unknown>;
+}
+
+/** CloudEvent for activity streams */
+export interface CloudEvent<T = unknown> {
+  specversion: '1.0';
+  type: string;
+  source: string;
+  id: string;
+  time: ISO8601Timestamp;
+  datacontenttype?: string;
+  data?: T;
+  subject?: string;
+}
+
+/** OSSA-specific CloudEvent types */
+export type OSSAEventType =
+  | 'io.ossa.agent.turn.started'
+  | 'io.ossa.agent.turn.completed'
+  | 'io.ossa.agent.turn.failed'
+  | 'io.ossa.tool.called'
+  | 'io.ossa.tool.completed'
+  | 'io.ossa.tool.failed'
+  | 'io.ossa.state.changed'
+  | 'io.ossa.delegation.started'
+  | 'io.ossa.delegation.completed';
+
+// =============================================================================
+// Delegation Types
+// =============================================================================
+
+/** Delegation patterns */
+export type DelegationType = 'handoff' | 'parallel' | 'supervisor';
+
+/** Delegation request */
+export interface DelegationRequest {
+  type: DelegationType;
+  target_agent: string;
+  input: unknown;
+  context_propagation: ContextPropagation;
+  timeout_ms: number;
+  on_failure: RecoveryStrategy;
+}
+
+/** Context propagation config */
+export interface ContextPropagation {
+  include_session_id: boolean;
+  include_history: boolean;
+  include_state: boolean;
+  custom_context?: Record<string, unknown>;
+}
+
+/** Delegation result */
+export interface DelegationResult {
+  agent_id: string;
+  status: 'success' | 'error' | 'timeout';
+  output?: unknown;
+  error?: OSSAError;
+  duration_ms: number;
+}
+
+// =============================================================================
+// Retry Types
+// =============================================================================
+
+/** Retry policy configuration */
+export interface RetryPolicy {
+  max_retries: number;
+  initial_delay_ms: number;
+  max_delay_ms: number;
+  backoff_multiplier: number;
+  retryable_errors?: ErrorCode[];
+}
+
+// =============================================================================
+// JSON Schema Types (subset)
+// =============================================================================
+
+/** Simplified JSON Schema type */
+export interface JSONSchema {
+  type?: string | string[];
+  properties?: Record<string, JSONSchema>;
+  required?: string[];
+  items?: JSONSchema;
+  enum?: unknown[];
+  description?: string;
+  default?: unknown;
+  format?: string;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  additionalProperties?: boolean | JSONSchema;
+  $ref?: string;
+}
+
+// =============================================================================
+// Turn Lifecycle Types
+// =============================================================================
+
+/** Turn phase names */
+export type TurnPhase =
+  | 'init'
+  | 'normalize'
+  | 'resolve'
+  | 'infer'
+  | 'execute'
+  | 'persist'
+  | 'emit';
+
+/** Turn context */
+export interface TurnContext {
+  identity: AgentIdentity;
+  messages: Message[];
+  tools: ResolvedTool[];
+  state: StateOperations;
+  trace_context?: W3CTraceContext;
+  baggage?: W3CBaggage;
+}
+
+/** Turn result */
+export interface TurnResult {
+  response: AssistantMessage;
+  tool_executions: ToolExecution[];
+  state_changes: StateChange[];
+  usage: TokenUsage;
+  duration_ms: number;
+  phases: PhaseMetrics[];
+}
+
+/** Phase execution metrics */
+export interface PhaseMetrics {
+  phase: TurnPhase;
+  started_at: ISO8601Timestamp;
+  completed_at: ISO8601Timestamp;
+  duration_ms: number;
+  error?: OSSAError;
+}

package/dist/spec/v0.3.0/UNIFIED-SCHEMA.md

@@ -0,0 +1,120 @@
+# OSSA v0.3.0 - Unified Agent Schema
+
+## The Rocketship 🚀
+
+This schema unifies OSSA, GitLab Duo, Google A2A, and MCP into a single universal agent platform.
+
+### What Changed
+
+**Before (v0.2.x):**
+```yaml
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-20250514
+```
+
+**After (v0.3.0):**
+```yaml
+llm:
+  provider: ${LLM_PROVIDER:-anthropic}
+  model: ${LLM_MODEL:-claude-sonnet}
+  profile: ${LLM_PROFILE:-balanced}
+  fallback_models:
+    - provider: ${LLM_FALLBACK_PROVIDER_1:-openai}
+      model: ${LLM_FALLBACK_MODEL_1:-gpt-4o}
+```
+
+### Key Features
+
+1. **Zero Hardcoded Models** - All LLM config is runtime-configurable
+2. **Execution Profiles** - Google A2A compatible (fast/balanced/deep/safe)
+3. **Multi-Runtime Support** - Works with Duo, A2A, OSSA, MCP
+4. **Fallback Models** - Multi-provider resilience
+5. **Structured Functions** - A2A/OpenAI function calling format
+6. **Extensions** - Pluggable external behaviors
+
+### Compatibility Matrix
+
+| Feature | OSSA v0.2.x | Duo | A2A | v0.3.0 |
+|---------|-------------|-----|-----|--------|
+| Runtime-configurable models | ❌ | ❌ | ✅ | ✅ |
+| Execution profiles | ❌ | ❌ | ✅ | ✅ |
+| Multi-provider fallback | partial | ❌ | ✅ | ✅ |
+| Structured functions | ❌ | partial | ✅ | ✅ |
+| Extensions | partial | partial | ✅ | ✅ |
+
+### Migration
+
+```bash
+# Auto-migrate all agents
+./scripts/migrate-to-unified-llm.sh
+
+# Generate new agent
+./scripts/generate-agent.sh my-agent worker
+
+# Validate
+ossa validate examples/
+```
+
+### Environment Variables
+
+```bash
+# Primary LLM
+export LLM_PROVIDER=anthropic
+export LLM_MODEL=claude-sonnet-4
+export LLM_PROFILE=balanced
+
+# Fallbacks
+export LLM_FALLBACK_PROVIDER_1=openai
+export LLM_FALLBACK_MODEL_1=gpt-4o
+
+# Runtime
+export AGENT_RUNTIME=unified
+export AGENT_SCHEDULING=fair
+export AGENT_PRIORITY=normal
+```
+
+### Execution Profiles
+
+- **fast** - Quick responses (4K tokens, temp=0.0)
+- **balanced** - General ops (16K tokens, temp=0.1)
+- **deep** - Analysis (32K tokens, temp=0.2, reasoning enabled)
+- **safe** - Compliance (temp=0.0, validation required)
+
+### CI Enforcement
+
+Add to `.gitlab-ci.yml`:
+
+```yaml
+include:
+  - local: .gitlab/ci/validate-no-hardcoded-models.yml
+```
+
+This blocks any MR with hardcoded model names.
+
+### Example Agent
+
+See: `examples/unified/security-scanner.ossa.yaml`
+
+### Schema Files
+
+- `schemas/unified-llm.yaml` - LLM configuration
+- `schemas/runtime.yaml` - Runtime declaration
+- `schemas/capabilities.yaml` - Capability definitions
+- `schemas/functions.yaml` - Function declarations
+- `schemas/agent-unified.yaml` - Complete agent schema
+
+### Why This Matters
+
+1. **No More Breaking Changes** - Model updates don't require code changes
+2. **Multi-Provider** - Switch between Anthropic/OpenAI/Google/Groq instantly
+3. **Future-Proof** - New runtimes (A2A, Duo) work without modification
+4. **Cost Optimization** - Use cheap models for triage, expensive for analysis
+5. **Compliance** - Audit trail of which models were used when
+
+### Next Steps
+
+1. Run migration: `./scripts/migrate-to-unified-llm.sh`
+2. Update CI: Add validation rule
+3. Test: `ossa validate examples/`
+4. Deploy: Agents auto-detect runtime