@tangle-network/agent-runtime 0.8.0 → 0.9.0

package/dist/index.js

@@ -290,6 +290,279 @@ function stringValue(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
 
+// src/chat-turn.ts
+import { mergeAgentProfiles } from "@tangle-network/sandbox";
+var RUNTIME_PATH = "/runtime/agents/run/stream";
+async function* runChatTurn(options) {
+  const turnProfile = options.overlay ? composeTurnProfile(options.profile, options.overlay) : options.profile;
+  const url = `${options.sandbox.runtimeUrl}${RUNTIME_PATH}`;
+  const backendType = turnProfile.metadata?.backend?.type ?? "claude-code";
+  const body = JSON.stringify({
+    backend: {
+      type: backendType,
+      profile: turnProfile,
+      ...options.modelOverride ? { model: { default: options.modelOverride } } : {}
+    },
+    messages: [...options.priorMessages, { role: "user", content: options.message }]
+  });
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "text/event-stream"
+  };
+  if (options.sandbox.authHeader) {
+    headers[options.sandbox.authHeader.name] = options.sandbox.authHeader.value;
+  }
+  const fetchImpl = options.fetch ?? fetch;
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers,
+    body,
+    signal: options.signal
+  });
+  if (!response.ok || !response.body) {
+    const text = response.body ? await response.text() : "";
+    throw new ChatTurnError(
+      `runChatTurn: sandbox returned ${response.status} ${response.statusText}: ${text.slice(0, 500)}`,
+      response.status
+    );
+  }
+  yield* parseSseStream(response.body);
+}
+function composeTurnProfile(base, overlay) {
+  const partial = {};
+  if (overlay.promptOverlay) partial.prompt = overlay.promptOverlay;
+  if (overlay.resourcesOverlay) partial.resources = overlay.resourcesOverlay;
+  if (overlay.subagentsOverlay) partial.subagents = overlay.subagentsOverlay;
+  if (overlay.metadata) partial.metadata = overlay.metadata;
+  return mergeAgentProfiles(base, partial) ?? base;
+}
+async function* parseSseStream(stream) {
+  const decoder = new TextDecoder();
+  const reader = stream.getReader();
+  let buffer = "";
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let idx = buffer.indexOf("\n");
+      while (idx >= 0) {
+        const line = buffer.slice(0, idx).replace(/\r$/, "").trim();
+        buffer = buffer.slice(idx + 1);
+        idx = buffer.indexOf("\n");
+        if (!line) continue;
+        const payload = line.startsWith("data:") ? line.slice(5).trim() : line;
+        if (payload === "[DONE]" || payload === "") continue;
+        try {
+          const parsed = JSON.parse(payload);
+          yield parsed;
+        } catch {
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+var ChatTurnError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ChatTurnError";
+  }
+  status;
+};
+function sandboxAsChatTurnTarget(instance, opts) {
+  const base = instance.url ?? instance.connection?.runtimeUrl ?? "";
+  if (!base) {
+    throw new ChatTurnError(
+      `sandboxAsChatTurnTarget: SandboxInstance has neither .url nor .connection.runtimeUrl set`
+    );
+  }
+  return {
+    id: instance.id,
+    runtimeUrl: base.replace(/\/+$/, ""),
+    authHeader: opts?.authHeader
+  };
+}
+
+// src/intent-router.ts
+var DEFAULT_PATTERN_WEIGHT = 1.5;
+var DEFAULT_MIN_SCORE = 1;
+function isMatcher(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return Array.isArray(v.keywords) || Array.isArray(v.patterns) || typeof v.minScore === "number";
+}
+function readMatcher(subagent) {
+  const m = subagent.metadata;
+  if (!m) return null;
+  const raw = m.matchers ?? m.matcher ?? null;
+  if (!raw) return null;
+  if (Array.isArray(raw)) {
+    const merged = { keywords: [], patterns: [], minScore: DEFAULT_MIN_SCORE };
+    for (const entry of raw) {
+      if (!isMatcher(entry)) continue;
+      merged.keywords = [...merged.keywords ?? [], ...entry.keywords ?? []];
+      merged.patterns = [...merged.patterns ?? [], ...entry.patterns ?? []];
+      if (entry.minScore !== void 0) merged.minScore = entry.minScore;
+    }
+    return merged;
+  }
+  if (isMatcher(raw)) return raw;
+  return null;
+}
+function classifyIntent(profile, message, opts = {}) {
+  const lower = message.toLowerCase();
+  const subagents = profile.subagents ?? {};
+  const skip = new Set(opts.skip ?? []);
+  const defaultMinScore = opts.defaultMinScore ?? DEFAULT_MIN_SCORE;
+  const scores = {};
+  const evaluated = {};
+  let bestId = null;
+  let bestScore = -Infinity;
+  let bestSubagent = null;
+  for (const [id, subagent] of Object.entries(subagents)) {
+    if (skip.has(id)) continue;
+    if (opts.filter && !opts.filter(subagent, id)) continue;
+    const matcher = readMatcher(subagent);
+    if (!matcher) {
+      evaluated[id] = { keywordHits: 0, patternHits: 0, minScore: defaultMinScore };
+      scores[id] = 0;
+      continue;
+    }
+    const weight = matcher.weight ?? 1;
+    let kHits = 0;
+    for (const kw of matcher.keywords ?? []) {
+      if (kw && lower.includes(kw.toLowerCase())) kHits += 1;
+    }
+    let pHits = 0;
+    for (const p of matcher.patterns ?? []) {
+      const re = p instanceof RegExp ? p : new RegExp(p, "i");
+      if (re.test(message)) pHits += 1;
+    }
+    const score = kHits * weight + pHits * DEFAULT_PATTERN_WEIGHT * weight;
+    const minScore = matcher.minScore ?? defaultMinScore;
+    scores[id] = score;
+    evaluated[id] = { keywordHits: kHits, patternHits: pHits, minScore };
+    if (score >= minScore && score > bestScore) {
+      bestScore = score;
+      bestId = id;
+      bestSubagent = subagent;
+    }
+  }
+  if (bestId === null) {
+    return { id: null, subagent: null, score: 0, scores, evaluated };
+  }
+  return { id: bestId, subagent: bestSubagent, score: bestScore, scores, evaluated };
+}
+
+// src/profile-conformance.ts
+var DEFAULT_SHELL_CAPS = [
+  "bash",
+  "sh",
+  "python",
+  "node",
+  "curl",
+  "web",
+  "browser",
+  "shell"
+];
+var DEFAULT_MIN_PROMPT_CHARS = 800;
+function checkSystemPrompt(profile, minChars) {
+  const prompt = profile.prompt?.systemPrompt;
+  if (!prompt || prompt.trim().length < minChars) {
+    return [
+      {
+        severity: "error",
+        code: "system-prompt-too-short",
+        path: "prompt.systemPrompt",
+        message: `prompt.systemPrompt is ${prompt?.length ?? 0} chars; min required is ${minChars}. Profiles below this threshold are almost always placeholders.`
+      }
+    ];
+  }
+  return [];
+}
+function checkToolsVsMcp(profile, opts) {
+  const issues = [];
+  const shellCaps = new Set(opts.knownShellCapabilities ?? DEFAULT_SHELL_CAPS);
+  const allowedWithoutMcp = new Set(opts.toolsAllowedWithoutMcp ?? []);
+  const tools = profile.tools ?? {};
+  const mcp = profile.mcp ?? {};
+  for (const [name, value] of Object.entries(tools)) {
+    if (shellCaps.has(name)) {
+      issues.push({
+        severity: "error",
+        code: "shell-capability-as-tool",
+        path: `tools.${name}`,
+        message: `'${name}' is a shell capability, not a tool. Move to permissions and remove from tools.`
+      });
+      continue;
+    }
+    if (allowedWithoutMcp.has(name)) continue;
+    if (value === false) continue;
+    if (!mcp[name]) {
+      issues.push({
+        severity: "error",
+        code: "decorative-tool-without-mcp",
+        path: `tools.${name}`,
+        message: `'${name}' declared in tools but no corresponding mcp[${name}] AgentProfileMcpServer. Either wire an MCP server, list this name in toolsAllowedWithoutMcp (if it's a file-mounted CLI binary), or remove from tools.`
+      });
+    }
+  }
+  return issues;
+}
+function checkSubagentShape(subagent, id) {
+  const issues = [];
+  if (!subagent.description || subagent.description.trim().length < 40) {
+    issues.push({
+      severity: "error",
+      code: "subagent-description-too-short",
+      path: `subagents.${id}.description`,
+      message: `subagents.${id}.description is missing or too short. Required for routing UX + audit trail.`
+    });
+  }
+  if (!subagent.prompt || subagent.prompt.trim().length < 100) {
+    issues.push({
+      severity: "error",
+      code: "subagent-prompt-too-short",
+      path: `subagents.${id}.prompt`,
+      message: `subagents.${id}.prompt is missing or below 100 chars. Either ship the specialist prompt or move this subagent under metadata.plannedSubagents.`
+    });
+  }
+  return issues;
+}
+function checkScaffoldSubagents(profile, strict) {
+  const issues = [];
+  const subagents = profile.subagents ?? {};
+  for (const [id, subagent] of Object.entries(subagents)) {
+    const meta = subagent.metadata;
+    const status = meta?.status;
+    if (status === "scaffold" || status === "not-implemented" || meta?.implemented === false) {
+      issues.push({
+        severity: strict ? "error" : "warn",
+        code: "subagent-scaffold-shipped",
+        path: `subagents.${id}`,
+        message: `subagents.${id} is a scaffold (metadata.status='${status}'). Router must gate on metadata.status === 'full' OR caller must opt into scaffolds explicitly.`
+      });
+    }
+  }
+  return issues;
+}
+function assertProfileConformance(profile, opts = {}) {
+  const issues = [
+    ...checkSystemPrompt(profile, opts.minSystemPromptChars ?? DEFAULT_MIN_PROMPT_CHARS),
+    ...checkToolsVsMcp(profile, opts),
+    ...checkScaffoldSubagents(profile, opts.strictNoScaffolds ?? false)
+  ];
+  for (const [id, subagent] of Object.entries(profile.subagents ?? {})) {
+    issues.push(...checkSubagentShape(subagent, id));
+  }
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warn");
+  return { valid: errors.length === 0, errors, warnings };
+}
+
 // src/readiness.ts
 var DEFAULT_MINIMUM_READINESS_SCORE = 0.7;
 function decideKnowledgeReadiness(report, options = {}) {
@@ -1296,9 +1569,9 @@ function projectToTraceEvent(event) {
           phase: "tool_call",
           toolName: event.toolName,
           toolCallId: event.toolCallId
-          // Args intentionally omitted at this layer; consumers attach the
-          // payload to a `ToolSpan` if they need to retain it. Trace events
-          // are point-in-time markers, not the canonical store for tool I/O.
+          // Args omitted — trace events are point-in-time markers, not the
+          // canonical store for tool I/O. Attach payloads to a `ToolSpan`
+          // when retention is required.
         }
       };
     case "tool_result":
@@ -1363,6 +1636,7 @@ export {
   AgentEvalError2 as AgentEvalError,
   BackendTransportError,
   CaptureIntegrityError,
+  ChatTurnError,
   ConfigError,
   InMemoryRuntimeSessionStore,
   JudgeError,
@@ -1372,6 +1646,9 @@ export {
   SessionMismatchError,
   ValidationError,
   VerificationError,
+  assertProfileConformance,
+  classifyIntent,
+  composeTurnProfile,
   createIterableBackend,
   createOpenAICompatibleBackend,
   createRuntimeEventCollector,
@@ -1383,7 +1660,9 @@ export {
   readinessServerSentEvent,
   runAgentTask,
   runAgentTaskStream,
+  runChatTurn,
   runtimeStreamServerSentEvent,
+  sandboxAsChatTurnTarget,
   sanitizeAgentRuntimeEvent,
   sanitizeKnowledgeReadinessReport,
   sanitizeRuntimeStreamEvent,