@aparte/engine 0.2.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @aparte/engine — the framework-agnostic agent loop.
+ *
+ * Zero runtime dependencies, no DOM: usable from any in-browser or Node AI-chat app.
+ * The headline export is `runStreamAgent`, the headless extraction of
+ * `AparteClient._streamLoop` — inject it via core's `streamRunner` seam and core
+ * renders its events through `createStreamAdapter`. Parity between the two is proven
+ * by the stream-parity suite.
+ *
+ * Deliberately just the loop core drives, plus the agnostic context compactor. Opt-in
+ * *tools* (ask-question / RAG / skills / code) belong in `plugins/*`; product behaviour
+ * (memory, intent orchestration) and the not-yet-wired text agent loop live elsewhere.
+ */
+export * from './agent/stream-events.js';
+export * from './agent/stream-run.js';
+export * from './agent/parsers/artifact-xml-state-machine.js';
+export * from './conversation/compactor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,+CAA+C,CAAC;AAG9D,cAAc,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,545 @@
+const CLOSE_TAG = "</artifact>";
+const OPEN_TAG = "<artifact";
+const INLINE_MAX_LINES = 15;
+function deriveArtifactKind(mimeType, fallback = "unknown") {
+  const m = (mimeType || "").toLowerCase().trim();
+  const ant = m.match(/^application\/vnd\.ant\.([a-z0-9-]+)/);
+  if (ant) return ant[1];
+  if (m === "text/html" || m === "application/xhtml+xml") return "html";
+  if (m === "application/javascript" || m === "text/javascript") return "js";
+  if (m === "text/css") return "css";
+  if (m === "image/svg+xml") return "svg";
+  if (m === "application/json") return "json";
+  if (m === "text/markdown") return "markdown";
+  if (m === "text/csv") return "csv";
+  if (m === "text/plain") return "text";
+  if (m.includes("react")) return "react";
+  if (m.includes("html")) return "html";
+  if (m.includes("javascript")) return "js";
+  if (m.includes("css")) return "css";
+  if (m.includes("svg")) return "svg";
+  if (m.includes("json")) return "json";
+  if (m.includes("csv")) return "csv";
+  if (m.includes("markdown")) return "markdown";
+  return fallback;
+}
+class ArtifactXmlStateMachine {
+  constructor(hint, idGen) {
+    this.hint = hint;
+    this.idGen = idGen ?? (() => `artifact-xml-${this.seq++}`);
+  }
+  state = "normal";
+  /** Buffers the opening tag until its `>` arrives (may span deltas). */
+  scanBuf = "";
+  /** Buffers the tail that might be the start of a split `</artifact>`. */
+  closeBuf = "";
+  segId = null;
+  content = "";
+  mime = "";
+  kind = "";
+  title = "";
+  seq = 0;
+  idGen;
+  /** Feed one text delta; returns the ordered micro-events it produced. */
+  feed(delta) {
+    const out = [];
+    let remaining = delta;
+    while (remaining.length > 0) {
+      if (this.state === "normal") {
+        const tagStart = remaining.indexOf(OPEN_TAG);
+        if (tagStart === -1) {
+          out.push({ type: "chat-text", text: remaining });
+          remaining = "";
+        } else {
+          const before = remaining.slice(0, tagStart);
+          if (before) out.push({ type: "chat-text", text: before, reduced: true });
+          this.scanBuf = remaining.slice(tagStart);
+          remaining = "";
+          this.state = "scanning";
+        }
+      } else if (this.state === "scanning") {
+        this.scanBuf += remaining;
+        remaining = "";
+        const gtIdx = this.scanBuf.indexOf(">");
+        if (gtIdx !== -1) {
+          const tag = this.scanBuf.slice(0, gtIdx + 1);
+          this.mime = /mimeType=['"]([^'"]+)['"]/.exec(tag)?.[1] ?? this.hint.mimeType;
+          this.title = /title=['"]([^'"]+)['"]/.exec(tag)?.[1] ?? this.hint.kind;
+          this.kind = deriveArtifactKind(this.mime, this.hint.kind);
+          this.segId = this.idGen();
+          this.content = "";
+          out.push({ type: "artifact-open", id: this.segId, mimeType: this.mime, kind: this.kind, title: this.title });
+          this.state = "in-artifact";
+          remaining = this.scanBuf.slice(gtIdx + 1);
+          this.scanBuf = "";
+        }
+      } else {
+        const combined = this.closeBuf + remaining;
+        const closeIdx = combined.indexOf(CLOSE_TAG);
+        if (closeIdx !== -1) {
+          this.content += combined.slice(0, closeIdx);
+          const inline = this.content.split("\n").length < INLINE_MAX_LINES;
+          out.push({ type: "artifact-close", id: this.segId, content: this.content, inline });
+          this.state = "normal";
+          this.closeBuf = "";
+          remaining = combined.slice(closeIdx + CLOSE_TAG.length);
+        } else {
+          const safeLen = Math.max(0, combined.length - CLOSE_TAG.length + 1);
+          this.content += combined.slice(0, safeLen);
+          this.closeBuf = combined.slice(safeLen);
+          remaining = "";
+          if (this.segId) out.push({ type: "artifact-chunk", id: this.segId, content: this.content });
+        }
+      }
+    }
+    return out;
+  }
+  /**
+   * Flush a truncated artifact: if the stream ended mid-body (model cut off
+   * before `</artifact>`), emit a close with whatever was buffered. Mirrors
+   * `_streamLoop`'s finalize block (:1658-1669).
+   */
+  finalize() {
+    if (this.state === "in-artifact" && this.segId) {
+      this.content += this.closeBuf;
+      const inline = this.content.split("\n").length < INLINE_MAX_LINES;
+      const ev = { type: "artifact-close", id: this.segId, content: this.content, inline };
+      this.state = "normal";
+      this.closeBuf = "";
+      return [ev];
+    }
+    return [];
+  }
+  /** Current parser state (for the adapter to decide finalize routing). */
+  get currentState() {
+    return this.state;
+  }
+}
+const DEFAULT_TOOL_TIMEOUT_MS = 5 * 60 * 1e3;
+const DEFAULT_MAX_TURNS = 10;
+async function runStreamAgent(opts) {
+  const {
+    transportCall,
+    toolLookup,
+    toolConfigLookup,
+    approvalResolver,
+    emitter,
+    signal,
+    maxTurns = DEFAULT_MAX_TURNS,
+    toolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS
+  } = opts;
+  let baseRequest = opts.baseRequest;
+  let idSeq = 0;
+  const idGen = opts.idGen ?? ((prefix) => `${prefix}-${idSeq++}`);
+  const messages = [...baseRequest.messages];
+  const pipeline = baseRequest["_meta"]?.["pipeline"];
+  let pipelineIndex = 0;
+  let continueLoop = true;
+  let turns = 0;
+  let lastUsage;
+  emitter({ type: "run-start" });
+  while (continueLoop) {
+    if (signal.aborted) {
+      emitter({ type: "run-aborted" });
+      break;
+    }
+    turns++;
+    if (turns > maxTurns) {
+      emitter({ type: "turn-limit-exceeded", scope: "global", limit: maxTurns });
+      break;
+    }
+    const toolChoice = baseRequest["toolChoice"];
+    if (turns === 1 && toolChoice && typeof toolChoice === "object" && !Array.isArray(toolChoice) && toolChoice.input !== void 0) {
+      const tc = toolChoice;
+      const syntheticId = idGen("synthetic-tool");
+      emitter({ type: "tool-start", toolCallId: syntheticId, name: tc.name, input: tc.input });
+      const handler = toolLookup(tc.name);
+      if (!handler) {
+        emitter({ type: "tool-aborted", toolCallId: syntheticId });
+        continueLoop = false;
+        continue;
+      }
+      const outcome = await invokeToolHandler(handler, { id: syntheticId, name: tc.name, input: tc.input }, signal, toolTimeoutMs);
+      if (outcome.status === "aborted") {
+        emitter({ type: "tool-aborted", toolCallId: syntheticId });
+        continueLoop = false;
+        continue;
+      }
+      emitter({ type: "tool-resolved", toolCallId: syntheticId, result: outcome.content });
+      messages.push({ role: "tool_call", content: "", toolCalls: [{ id: syntheticId, name: tc.name, input: tc.input }] });
+      messages.push({ role: "tool_result", content: outcome.content, toolCallId: syntheticId });
+      baseRequest = { ...baseRequest, toolChoice: "none", tools: void 0 };
+    }
+    let phaseMessages = messages;
+    let phaseMeta = baseRequest["_meta"];
+    if (pipeline && pipelineIndex < pipeline.length) {
+      const phase = pipeline[pipelineIndex];
+      phaseMessages = [{ role: "system", content: phase.system }, ...messages];
+      if (phase.mode === "artifact") {
+        phaseMeta = { ...phaseMeta, artifactRaw: { mimeType: phase.mimeType, kind: phase.kind } };
+      } else {
+        const rest = { ...phaseMeta ?? {} };
+        delete rest["artifactRaw"];
+        delete rest["pipeline"];
+        phaseMeta = rest;
+      }
+    }
+    const request = { ...baseRequest, messages: phaseMessages, _meta: phaseMeta };
+    const response = await transportCall(request);
+    if (typeof response === "string") {
+      emitter({ type: "text-delta", delta: response });
+      break;
+    }
+    emitter({ type: "turn-start" });
+    const rawHint = request["_meta"]?.["artifactRaw"];
+    let rawSegId = null;
+    let rawContent = "";
+    if (rawHint) {
+      rawSegId = idGen("artifact-raw");
+      emitter({ type: "artifact-open", id: rawSegId, mimeType: rawHint.mimeType, kind: rawHint.kind, title: rawHint.kind });
+    }
+    const xmlHint = request["_meta"]?.["artifactXml"];
+    const xmlMachine = xmlHint && !rawHint ? new ArtifactXmlStateMachine(xmlHint, () => idGen("artifact-xml")) : null;
+    const emitXml = (events) => {
+      for (const ev of events) {
+        if (ev.type === "chat-text") emitter({ type: "text-delta", delta: ev.text, ...ev.reduced ? { reduced: true } : {} });
+        else if (ev.type === "artifact-open") emitter({ type: "artifact-open", id: ev.id, mimeType: ev.mimeType, kind: ev.kind, title: ev.title });
+        else if (ev.type === "artifact-chunk") emitter({ type: "artifact-chunk", id: ev.id, content: ev.content });
+        else emitter({ type: "artifact-close", id: ev.id, content: ev.content, inline: ev.inline });
+      }
+    };
+    let precedingText = "";
+    const toolCallsThisTurn = [];
+    const iterator = response[Symbol.asyncIterator]();
+    try {
+      while (true) {
+        if (signal.aborted) {
+          await iterator.return?.(void 0);
+          emitter({ type: "run-aborted" });
+          continueLoop = false;
+          break;
+        }
+        const step = await iterator.next();
+        if (step.done) break;
+        const event = step.value;
+        if (event.type === "thinking") {
+          emitter({ type: "thinking-delta", delta: event.delta });
+          continue;
+        }
+        if (event.type === "text") {
+          precedingText += event.delta;
+          if (rawSegId) {
+            rawContent += event.delta;
+            emitter({ type: "artifact-chunk", id: rawSegId, content: rawContent });
+            continue;
+          }
+          if (xmlMachine) {
+            emitXml(xmlMachine.feed(event.delta));
+            continue;
+          }
+          emitter({ type: "text-delta", delta: event.delta });
+          continue;
+        }
+        if (event.type === "done") {
+          if (event.usage) lastUsage = event.usage;
+          continue;
+        }
+        if (event.type === "error") {
+          throw new Error(event.message);
+        }
+        toolCallsThisTurn.push({ id: event.id, name: event.name, input: event.input });
+        if (event.name === "create_artifact") {
+          const input = event.input ?? {};
+          const mimeType = input.mimeType ?? "text/plain";
+          const kind = deriveArtifactKind(mimeType, "text");
+          emitter({ type: "artifact-ready", id: `artifact-${event.id}`, mimeType, kind, title: input.title ?? kind, content: input.content ?? "" });
+          messages.push({ role: "tool_call", content: "", toolCalls: [{ id: event.id, name: event.name, input: event.input }] });
+          messages.push({ role: "tool_result", content: "Artifact created successfully.", toolCallId: event.id });
+          continue;
+        }
+        emitter({ type: "tool-start", toolCallId: event.id, name: event.name, input: event.input });
+        const cfg = toolConfigLookup?.(event.name);
+        const effectiveMaxTurns = cfg?.maxTurns ?? maxTurns;
+        if (turns >= effectiveMaxTurns) {
+          emitter({ type: "turn-limit-exceeded", scope: "tool", limit: effectiveMaxTurns, toolCallId: event.id });
+          continueLoop = false;
+          break;
+        }
+        const handler = toolLookup(event.name);
+        if (!handler) {
+          emitter({ type: "tool-aborted", toolCallId: event.id });
+          continueLoop = false;
+          break;
+        }
+        let effectiveInput = event.input;
+        if (cfg?.needsApproval) {
+          emitter({ type: "tool-awaiting-approval", toolCallId: event.id, name: event.name, input: event.input });
+          const resolve = approvalResolver ?? (async () => ({ approved: false }));
+          const decision = await resolve(event.id, signal);
+          if (!decision.approved) {
+            const rejection = "Tool execution was rejected by the user.";
+            emitter({ type: "tool-rejected", toolCallId: event.id, reason: rejection });
+            pushToolCallEnvelope(messages, toolCallsThisTurn, precedingText);
+            messages.push({ role: "tool_result", content: rejection, toolCallId: event.id });
+            continueLoop = false;
+            break;
+          }
+          if (decision.payload && typeof decision.payload === "object" && !Array.isArray(decision.payload)) {
+            effectiveInput = { ...event.input, ...decision.payload };
+          }
+          emitter({ type: "tool-approved", toolCallId: event.id });
+        }
+        const outcome = await invokeToolHandler(
+          handler,
+          { id: event.id, name: event.name, input: effectiveInput },
+          signal,
+          toolTimeoutMs
+        );
+        if (outcome.status === "aborted") {
+          emitter({ type: "tool-aborted", toolCallId: event.id });
+          continueLoop = false;
+        } else {
+          emitter({ type: "tool-resolved", toolCallId: event.id, result: outcome.content });
+          pushToolCallEnvelope(messages, toolCallsThisTurn, precedingText);
+          messages.push({ role: "tool_result", content: outcome.content, toolCallId: event.id });
+        }
+      }
+      emitter({ type: "text-flush" });
+      if (rawSegId) {
+        const inline = rawContent.split("\n").length < 15;
+        emitter({ type: "artifact-close", id: rawSegId, content: rawContent, inline });
+      }
+      if (xmlMachine) emitXml(xmlMachine.finalize());
+    } finally {
+      await iterator.return?.(void 0).catch(() => {
+      });
+    }
+    if (toolCallsThisTurn.length === 0) {
+      if (pipeline && pipelineIndex < pipeline.length - 1) {
+        if (precedingText.trim()) {
+          messages.push({ role: "assistant", content: precedingText.trim() });
+        }
+        pipelineIndex++;
+        emitter({ type: "phase-advance", index: pipelineIndex });
+      } else {
+        continueLoop = false;
+      }
+    }
+  }
+  emitter({ type: "run-done", usage: lastUsage });
+  return lastUsage;
+}
+function pushToolCallEnvelope(messages, toolCallsThisTurn, precedingText) {
+  const exists = messages.some(
+    (m) => m.role === "tool_call" && m.toolCalls?.some((tc) => toolCallsThisTurn.some((t) => t.id === tc.id))
+  );
+  if (exists) return;
+  messages.push({
+    role: "tool_call",
+    content: "",
+    toolCalls: toolCallsThisTurn,
+    precedingText: precedingText.trim() || void 0
+  });
+}
+async function invokeToolHandler(handler, call, signal, toolTimeoutMs) {
+  if (signal.aborted) return { status: "aborted" };
+  const controller = new AbortController();
+  const onParentAbort = () => controller.abort();
+  signal.addEventListener("abort", onParentAbort, { once: true });
+  const timeout = setTimeout(() => controller.abort(), toolTimeoutMs);
+  try {
+    const result = await handler(call, controller.signal);
+    return { status: "resolved", content: result.content };
+  } catch (err) {
+    if (err?.name === "AbortError") return { status: "aborted" };
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+    signal.removeEventListener("abort", onParentAbort);
+  }
+}
+const DEFAULT_COMPACTION_CONFIG = {
+  // Conservative model-agnostic defaults — the consuming app overrides
+  // `contextWindow` / `reservedThinking` with its model's real values.
+  contextWindow: 8192,
+  reservedThinking: 0,
+  reservedGeneration: 2e3,
+  autocompactBufferPct: 0.1,
+  // ~3300 tok
+  safetyMargin: 500,
+  minHistoryBudget: 1e3,
+  summaryRatio: 0.1,
+  summaryMaxTokens: 400,
+  ragHistRatio: 0.25,
+  ragHistMaxTokens: 1e3,
+  triggerSummaryThresholdPct: 0.75,
+  summarizeEveryNTurns: 5,
+  summaryLabel: "Conversation summary:",
+  ragIntroLabel: "Relevant excerpts from earlier in the conversation:"
+};
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 3.8);
+}
+function estimateTokensJson(obj) {
+  if (!obj) return 0;
+  try {
+    return estimateTokens(JSON.stringify(obj));
+  } catch {
+    return 0;
+  }
+}
+function computeHistoryBudget(input) {
+  const cfg = { ...DEFAULT_COMPACTION_CONFIG, ...input.config ?? {} };
+  const systemTokens = estimateTokens(input.systemPrompt);
+  const toolsTokens = estimateTokensJson(input.toolsArray);
+  const autocompactBuffer = Math.floor(cfg.contextWindow * cfg.autocompactBufferPct);
+  const fixed = systemTokens + toolsTokens + cfg.reservedThinking + cfg.reservedGeneration + autocompactBuffer + cfg.safetyMargin;
+  const historyBudget = Math.max(cfg.minHistoryBudget, cfg.contextWindow - fixed);
+  return {
+    historyBudget,
+    breakdown: {
+      contextWindow: cfg.contextWindow,
+      systemPrompt: systemTokens,
+      tools: toolsTokens,
+      reservedThinking: cfg.reservedThinking,
+      reservedGeneration: cfg.reservedGeneration,
+      autocompactBuffer,
+      safetyMargin: cfg.safetyMargin,
+      historyAvailable: historyBudget
+    },
+    config: cfg
+  };
+}
+function splitHistoryBudget(historyBudget, cfg = DEFAULT_COMPACTION_CONFIG) {
+  const summary = Math.min(cfg.summaryMaxTokens, Math.floor(historyBudget * cfg.summaryRatio));
+  const ragHist = Math.min(cfg.ragHistMaxTokens, Math.floor(historyBudget * cfg.ragHistRatio));
+  const window = historyBudget - summary - ragHist;
+  return { summary, ragHist, window };
+}
+function assembleCompacted(params) {
+  const {
+    messages,
+    summary = "",
+    retrievedTurns = [],
+    windowBudget,
+    summaryBudget,
+    ragBudget,
+    systemContent,
+    summaryLabel = DEFAULT_COMPACTION_CONFIG.summaryLabel,
+    ragIntroLabel = DEFAULT_COMPACTION_CONFIG.ragIntroLabel
+  } = params;
+  const out = [];
+  const used = { system: 0, summary: 0, ragHist: 0, window: 0 };
+  const dropped = { ragHits: 0, oldTurns: 0, summary: false };
+  if (systemContent) {
+    out.push({ role: "system", content: systemContent });
+    used.system = estimateTokens(systemContent);
+  }
+  if (summary) {
+    const summaryWrapped = `${summaryLabel}
+${summary}`;
+    const summaryToks = estimateTokens(summaryWrapped);
+    if (summaryToks <= summaryBudget) {
+      out.push({ role: "system", content: summaryWrapped });
+      used.summary = summaryToks;
+    } else {
+      const ratio = summaryBudget / summaryToks * 0.95;
+      const truncated = summary.slice(0, Math.max(0, Math.floor(summary.length * ratio)));
+      const wrapped = `${summaryLabel}
+${truncated}…`;
+      out.push({ role: "system", content: wrapped });
+      used.summary = estimateTokens(wrapped);
+      dropped.summary = true;
+    }
+  }
+  if (retrievedTurns.length > 0) {
+    const sorted = [...retrievedTurns].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+    const lines = [];
+    const intro = `${ragIntroLabel}
+`;
+    let toks = estimateTokens(intro);
+    for (const t of sorted) {
+      const line = `[${t.role}] ${t.content}`;
+      const lt = estimateTokens(line);
+      if (toks + lt > ragBudget) {
+        dropped.ragHits++;
+        continue;
+      }
+      lines.push(line);
+      toks += lt;
+    }
+    if (lines.length > 0) {
+      const content = intro + lines.join("\n");
+      out.push({ role: "system", content });
+      used.ragHist = estimateTokens(content);
+    }
+  }
+  const nonSystem = messages.filter((m) => m.role !== "system");
+  if (nonSystem.length === 0) {
+    return { compactedMessages: out, used, dropped };
+  }
+  const reversedWindow = [];
+  let windowToks = 0;
+  const minKeep = Math.min(2, nonSystem.length);
+  for (let i = nonSystem.length - 1; i >= 0; i--) {
+    const m = nonSystem[i];
+    if (!m) continue;
+    const t = estimateTokens(m.content);
+    const idxFromEnd = nonSystem.length - 1 - i;
+    if (idxFromEnd < minKeep) {
+      reversedWindow.unshift(m);
+      windowToks += t;
+      continue;
+    }
+    if (windowToks + t > windowBudget) {
+      dropped.oldTurns += i + 1;
+      break;
+    }
+    reversedWindow.unshift(m);
+    windowToks += t;
+  }
+  out.push(...reversedWindow);
+  used.window = windowToks;
+  return { compactedMessages: out, used, dropped };
+}
+function compactConversation(input) {
+  const { messages, systemPrompt, toolsArray, summary, retrievedTurns, config } = input;
+  const budget = computeHistoryBudget({ systemPrompt, toolsArray, config });
+  const split = splitHistoryBudget(budget.historyBudget, budget.config);
+  const { compactedMessages, used, dropped } = assembleCompacted({
+    messages,
+    summary,
+    retrievedTurns,
+    windowBudget: split.window,
+    summaryBudget: split.summary,
+    ragBudget: split.ragHist,
+    systemContent: systemPrompt,
+    summaryLabel: budget.config.summaryLabel,
+    ragIntroLabel: budget.config.ragIntroLabel
+  });
+  const totalUsed = budget.breakdown.systemPrompt + budget.breakdown.tools + used.summary + used.ragHist + used.window;
+  const free = budget.config.contextWindow - totalUsed - budget.config.reservedThinking - budget.config.reservedGeneration - budget.breakdown.autocompactBuffer - budget.config.safetyMargin;
+  const breakdown = {
+    ...budget.breakdown,
+    historyAllocated: split,
+    historyUsed: used,
+    totalUsed,
+    free,
+    dropped
+  };
+  return { compactedMessages, breakdown };
+}
+export {
+  ArtifactXmlStateMachine,
+  DEFAULT_COMPACTION_CONFIG,
+  assembleCompacted,
+  compactConversation,
+  computeHistoryBudget,
+  deriveArtifactKind,
+  estimateTokens,
+  estimateTokensJson,
+  runStreamAgent,
+  splitHistoryBudget
+};
+//# sourceMappingURL=index.js.map