lynkr 1.0.1 → 2.0.0

package/CITATIONS.bib

@@ -0,0 +1,6 @@
+@article{zhang2024ace,
+  title={Agentic Context Engineering},
+  author={Zhang et al.},
+  journal={arXiv:2510.04618},
+  year={2024}
+}

package/README.md

@@ -44,7 +44,8 @@
 10. [Troubleshooting](#troubleshooting)
 11. [Roadmap & Known Gaps](#roadmap--known-gaps)
 12. [FAQ](#faq)
-13. [License](#license)
+13. [References](#references)
+14. [License](#license)
 
 ---
 
@@ -1345,6 +1346,7 @@ Replace `<workspace>` and `<endpoint-name>` with your Databricks workspace host
 - **503 Service Unavailable errors during normal load** – Check load shedding thresholds (`LOAD_SHEDDING_*`). Lower values may trigger too aggressively. Check `/metrics/observability` for memory usage patterns.
 - **Circuit breaker stuck in OPEN state** – Check `/metrics/circuit-breakers` to see failure counts. Verify backend service (Databricks/Azure) is accessible. Circuit will automatically attempt recovery after `CIRCUIT_BREAKER_TIMEOUT` (default: 60s).
 - **"Circuit breaker is OPEN" errors** – The circuit breaker detected too many failures and is protecting against cascading failures. Wait for timeout or fix the underlying issue. Check logs for root cause of failures.
+  - **Azure OpenAI specific**: If using Azure OpenAI and seeing circuit breaker errors, verify your `AZURE_OPENAI_ENDPOINT` includes the full path (including `/openai/deployments/YOUR-DEPLOYMENT/chat/completions`). Missing endpoint variable or undefined returns can trigger circuit breaker protection.
 - **High latency after adding production features** – This is unexpected; middleware adds only ~7μs overhead. Check `/metrics/prometheus` for actual latency distribution. Verify network latency to backend services.
 - **Health check endpoint returns 503 but service seems healthy** – Check individual health check components in the response JSON. Database connectivity or memory issues may trigger this. Review logs for specific health check failures.
 - **Metrics endpoint shows incorrect data** – Metrics are in-memory and reset on restart. For persistent metrics, configure Prometheus scraping. Check that `METRICS_ENABLED=true`.
@@ -1538,6 +1540,16 @@ The graceful shutdown and health check endpoints ensure zero-downtime deployment
 
 ---
 
+## References
+
+Lynkr's design also includes ACE Framework informed by research in agentic AI systems and context engineering:
+
+- **Zhang et al. (2024)**. *Agentic Context Engineering*. arXiv:2510.04618. [arXiv](https://arxiv.org/abs/2510.04618)
+
+For BibTeX citations, see [CITATIONS.bib](CITATIONS.bib).
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

package/monitor-agents.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Monitor agent activity in real-time
+
+echo "🔍 Monitoring Agent Activity"
+echo "=============================="
+echo ""
+
+while true; do
+  clear
+  echo "🔍 Agent Statistics (refreshing every 3s)"
+  echo "=========================================="
+  echo ""
+
+  # Get stats
+  curl -s http://localhost:8080/v1/agents/stats | jq -r '.stats[] |
+    "Agent: \(.agent_type)
+    Executions: \(.total_executions) (\(.completed) completed, \(.failed) failed)
+    Avg Duration: \(.avg_duration_ms)ms
+    Tokens: \(.total_input_tokens) in / \(.total_output_tokens) out
+    "' || echo "Proxy not responding..."
+
+  echo ""
+  echo "Latest transcripts:"
+  ls -lt data/agent-transcripts/*.jsonl 2>/dev/null | head -3 || echo "No transcripts yet"
+
+  echo ""
+  echo "Press Ctrl+C to stop monitoring"
+
+  sleep 3
+done

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lynkr",
-  "version": "1.0.1",
-  "description": "Self-hosted Claude Code proxy with Databricks and Azure Anthropic adapters, workspace tooling, and MCP integration.",
+  "version": "2.0.0",
+  "description": "Self-hosted Claude Code proxy with Databricks,Azure  adapters, workspace tooling, and MCP integration.",
   "main": "index.js",
   "bin": {
     "lynkr": "./bin/cli.js",
@@ -41,6 +41,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
+    "@azure/openai": "^2.0.0",
     "better-sqlite3": "^9.4.0",
     "compression": "^1.7.4",
     "diff": "^5.2.0",
@@ -48,6 +49,8 @@
     "express": "^5.1.0",
     "express-rate-limit": "^8.2.1",
     "fast-glob": "^3.3.2",
+    "js-yaml": "^4.1.1",
+    "openai": "^6.14.0",
     "pino": "^8.17.2",
     "pino-http": "^8.6.0",
     "tree-sitter": "^0.20.1",

package/src/agents/context-manager.js

@@ -0,0 +1,220 @@
+const fs = require("fs");
+const path = require("path");
+const logger = require("../logger");
+
+class ContextManager {
+  constructor() {
+    this.transcriptsDir = path.join(process.cwd(), "data", "agent-transcripts");
+    this.ensureTranscriptsDir();
+  }
+
+  ensureTranscriptsDir() {
+    if (!fs.existsSync(this.transcriptsDir)) {
+      fs.mkdirSync(this.transcriptsDir, { recursive: true });
+    }
+  }
+
+  /**
+   * Create fresh context for subagent
+   * @param {Object} agentDef - Agent definition
+   * @param {string} taskPrompt - Task from main agent
+   * @param {Object} mainContext - Minimal context from main agent
+   * @returns {Object} - Fresh context for subagent
+   */
+  createSubagentContext(agentDef, taskPrompt, mainContext = {}) {
+    const agentId = this.generateAgentId();
+    const transcriptPath = path.join(this.transcriptsDir, `agent-${agentId}.jsonl`);
+
+    // Initialize transcript file
+    fs.writeFileSync(transcriptPath, "");
+
+    // Build minimal context (NOT full main agent history)
+    const messages = [];
+
+    // System prompt from agent definition
+    messages.push({
+      role: "system",
+      content: agentDef.systemPrompt
+    });
+
+    // Optional: Add minimal context from main agent
+    if (mainContext.relevant_context) {
+      messages.push({
+        role: "system",
+        content: `Context from main agent:\n${mainContext.relevant_context}`
+      });
+    }
+
+    // Task prompt
+    messages.push({
+      role: "user",
+      content: taskPrompt
+    });
+
+    const context = {
+      agentId,
+      agentName: agentDef.name,
+      transcriptPath,
+      messages,
+      steps: 0,
+      maxSteps: agentDef.maxSteps,
+      model: agentDef.model,
+      allowedTools: agentDef.allowedTools,
+      startTime: Date.now(),
+
+      // Token tracking
+      inputTokens: 0,
+      outputTokens: 0,
+
+      // State
+      terminated: false,
+      result: null
+    };
+
+    this.writeTranscriptEntry(transcriptPath, {
+      type: "agent_start",
+      agentId,
+      agentName: agentDef.name,
+      taskPrompt,
+      timestamp: Date.now()
+    });
+
+    logger.info({ agentId, agentName: agentDef.name }, "Created fresh subagent context");
+
+    return context;
+  }
+
+  /**
+   * Add message to subagent context
+   */
+  addMessage(context, message) {
+    context.messages.push(message);
+
+    this.writeTranscriptEntry(context.transcriptPath, {
+      type: "message",
+      agentId: context.agentId,
+      message,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Record tool execution in transcript
+   */
+  recordToolCall(context, toolName, input, output, error = null) {
+    this.writeTranscriptEntry(context.transcriptPath, {
+      type: "tool_call",
+      agentId: context.agentId,
+      step: context.steps,
+      toolName,
+      input,
+      output: error ? null : output,
+      error: error ? error.message : null,
+      timestamp: Date.now()
+    });
+  }
+
+  /**
+   * Complete subagent execution
+   */
+  completeExecution(context, result) {
+    context.terminated = true;
+    context.result = result;
+
+    this.writeTranscriptEntry(context.transcriptPath, {
+      type: "agent_complete",
+      agentId: context.agentId,
+      result,
+      stats: {
+        steps: context.steps,
+        durationMs: Date.now() - context.startTime,
+        inputTokens: context.inputTokens,
+        outputTokens: context.outputTokens
+      },
+      timestamp: Date.now()
+    });
+
+    logger.info({
+      agentId: context.agentId,
+      steps: context.steps,
+      durationMs: Date.now() - context.startTime
+    }, "Subagent execution completed");
+  }
+
+  /**
+   * Fail subagent execution
+   */
+  failExecution(context, error) {
+    context.terminated = true;
+
+    this.writeTranscriptEntry(context.transcriptPath, {
+      type: "agent_failed",
+      agentId: context.agentId,
+      error: error.message,
+      stats: {
+        steps: context.steps,
+        durationMs: Date.now() - context.startTime
+      },
+      timestamp: Date.now()
+    });
+
+    logger.error({
+      agentId: context.agentId,
+      error: error.message
+    }, "Subagent execution failed");
+  }
+
+  /**
+   * Write entry to transcript file (JSONL format)
+   */
+  writeTranscriptEntry(transcriptPath, entry) {
+    try {
+      fs.appendFileSync(transcriptPath, JSON.stringify(entry) + "\n");
+    } catch (error) {
+      logger.warn({ error: error.message }, "Failed to write transcript entry");
+    }
+  }
+
+  /**
+   * Read transcript for debugging
+   */
+  readTranscript(agentId) {
+    const transcriptPath = path.join(this.transcriptsDir, `agent-${agentId}.jsonl`);
+
+    if (!fs.existsSync(transcriptPath)) {
+      return null;
+    }
+
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(l => l.trim());
+    return lines.map(line => JSON.parse(line));
+  }
+
+  /**
+   * Generate unique agent ID
+   */
+  generateAgentId() {
+    return `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  }
+
+  /**
+   * Clean old transcripts (older than 7 days)
+   */
+  cleanOldTranscripts() {
+    const maxAge = 7 * 24 * 60 * 60 * 1000; // 7 days
+    const now = Date.now();
+
+    const files = fs.readdirSync(this.transcriptsDir);
+
+    for (const file of files) {
+      const filePath = path.join(this.transcriptsDir, file);
+      const stats = fs.statSync(filePath);
+
+      if (now - stats.mtimeMs > maxAge) {
+        fs.unlinkSync(filePath);
+        logger.debug({ file }, "Cleaned old transcript");
+      }
+    }
+  }
+}
+
+module.exports = ContextManager;