@witqq/agent-sdk 0.8.0 → 0.9.0

package/dist/backends/mock-llm.cjs

@@ -0,0 +1,719 @@
+'use strict';
+
+// src/types/errors.ts
+var RECOVERABLE_CODES = /* @__PURE__ */ new Set([
+  "TIMEOUT" /* TIMEOUT */,
+  "RATE_LIMIT" /* RATE_LIMIT */,
+  "NETWORK" /* NETWORK */,
+  "TOOL_EXECUTION" /* TOOL_EXECUTION */,
+  "MODEL_OVERLOADED" /* MODEL_OVERLOADED */,
+  "PROVIDER_ERROR" /* PROVIDER_ERROR */
+]);
+function isRecoverableErrorCode(code) {
+  return RECOVERABLE_CODES.has(code);
+}
+
+// src/errors.ts
+var AgentSDKError = class extends Error {
+  /** @internal Marker for cross-bundle identity checks */
+  _agentSDKError = true;
+  /** Machine-readable error code. Prefer values from the ErrorCode enum. */
+  code;
+  /** Whether this error is safe to retry */
+  retryable;
+  /** HTTP status code hint for error classification */
+  httpStatus;
+  constructor(message, options) {
+    super(message, options);
+    this.name = "AgentSDKError";
+    this.code = options?.code;
+    this.retryable = options?.retryable ?? false;
+    this.httpStatus = options?.httpStatus;
+  }
+  /** Check if an error is an AgentSDKError (works across bundled copies) */
+  static is(error) {
+    return error instanceof Error && "_agentSDKError" in error && error._agentSDKError === true;
+  }
+};
+var ReentrancyError = class extends AgentSDKError {
+  constructor() {
+    super("Agent is already running. Await the current run before starting another.", {
+      code: "REENTRANCY" /* REENTRANCY */
+    });
+    this.name = "ReentrancyError";
+  }
+};
+var DisposedError = class extends AgentSDKError {
+  constructor(entity) {
+    super(`${entity} has been disposed and cannot be used.`, {
+      code: "DISPOSED" /* DISPOSED */
+    });
+    this.name = "DisposedError";
+  }
+};
+var AbortError = class extends AgentSDKError {
+  constructor() {
+    super("Agent run was aborted.", { code: "ABORTED" /* ABORTED */ });
+    this.name = "AbortError";
+  }
+};
+var ActivityTimeoutError = class extends AgentSDKError {
+  constructor(timeoutMs) {
+    super(`Stream activity timeout: no event received within ${timeoutMs}ms.`, {
+      code: "TIMEOUT" /* TIMEOUT */,
+      retryable: true
+    });
+    this.name = "ActivityTimeoutError";
+  }
+};
+
+// src/base-agent.ts
+var BaseAgent = class {
+  state = "idle";
+  abortController = null;
+  config;
+  _cleanupExternalSignal = null;
+  _streamMiddleware = [];
+  /** CLI session ID for persistent mode. Override in backends that support it. */
+  get sessionId() {
+    return void 0;
+  }
+  constructor(config) {
+    this.config = Object.freeze({ ...config });
+  }
+  // ─── Public Interface ─────────────────────────────────────────
+  async run(prompt, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "running";
+    try {
+      const messages = [{ role: "user", content: prompt }];
+      const result = await this.withRetry(
+        () => this.executeRun(messages, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
+      return result;
+    } finally {
+      this.cleanupRun();
+    }
+  }
+  async runWithContext(messages, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "running";
+    try {
+      const result = await this.withRetry(
+        () => this.executeRun(messages, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
+      return result;
+    } finally {
+      this.cleanupRun();
+    }
+  }
+  async runStructured(prompt, schema, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "running";
+    try {
+      const messages = [{ role: "user", content: prompt }];
+      const result = await this.withRetry(
+        () => this.executeRunStructured(messages, schema, options, ac.signal),
+        options
+      );
+      this.enrichAndNotifyUsage(result, options);
+      return result;
+    } finally {
+      this.cleanupRun();
+    }
+  }
+  async *stream(prompt, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "streaming";
+    try {
+      const messages = [{ role: "user", content: prompt }];
+      yield* this.streamWithRetry(
+        () => this.applyStreamPipeline(this.executeStream(messages, options, ac.signal), options, ac),
+        options
+      );
+    } finally {
+      this.cleanupRun();
+    }
+  }
+  async *streamWithContext(messages, options) {
+    this.guardReentrancy();
+    this.guardDisposed();
+    const ac = this.createAbortController(options?.signal);
+    this.state = "streaming";
+    try {
+      yield* this.streamWithRetry(
+        () => this.applyStreamPipeline(this.executeStream(messages, options, ac.signal), options, ac),
+        options
+      );
+    } finally {
+      this.cleanupRun();
+    }
+  }
+  /** Register a stream middleware. Applied in registration order after built-in transforms. */
+  addStreamMiddleware(middleware) {
+    this.guardDisposed();
+    this._streamMiddleware.push(middleware);
+  }
+  /** Apply built-in transforms (enrich→timeout→heartbeat) then custom middleware */
+  async *applyStreamPipeline(source, options, ac) {
+    let stream = this.enrichStream(source, options);
+    stream = this.activityTimeoutStream(stream, options?.activityTimeoutMs, ac);
+    stream = this.heartbeatStream(stream);
+    if (this._streamMiddleware.length > 0) {
+      const ctx = {
+        model: options.model,
+        backend: this.backendName,
+        abortController: ac,
+        config: Object.freeze({ ...this.config })
+      };
+      for (const mw of this._streamMiddleware) {
+        stream = mw(stream, ctx);
+      }
+    }
+    yield* stream;
+  }
+  abort() {
+    if (this.abortController) {
+      this.abortController.abort();
+    }
+  }
+  /** Default interrupt — falls back to abort(). Backends may override with graceful shutdown. */
+  async interrupt() {
+    this.abort();
+  }
+  getState() {
+    return this.state;
+  }
+  getConfig() {
+    return this.config;
+  }
+  /** Mark agent as disposed. Override to add cleanup. */
+  dispose() {
+    this._cleanupExternalSignal?.();
+    this._cleanupExternalSignal = null;
+    this.abort();
+    this.state = "disposed";
+  }
+  // ─── Retry Logic ─────────────────────────────────────────────
+  /** Check if an error should be retried given the retry configuration. */
+  isRetryableError(error, retry) {
+    if (error instanceof AbortError || error instanceof ReentrancyError || error instanceof DisposedError) {
+      return false;
+    }
+    if (AgentSDKError.is(error)) {
+      if (retry.retryableErrors && retry.retryableErrors.length > 0 && error.code) {
+        return retry.retryableErrors.includes(error.code);
+      }
+      if (error.retryable) return true;
+      if (error.code) return isRecoverableErrorCode(error.code);
+    }
+    return false;
+  }
+  /** Execute a function with retry logic per RetryConfig. */
+  async withRetry(fn, options) {
+    const retry = options?.retry;
+    if (!retry || !retry.maxRetries || retry.maxRetries <= 0) {
+      return fn();
+    }
+    const maxRetries = retry.maxRetries;
+    const initialDelay = retry.initialDelayMs ?? 1e3;
+    const multiplier = retry.backoffMultiplier ?? 2;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (err) {
+        lastError = err;
+        if (attempt >= maxRetries || !this.isRetryableError(err, retry)) {
+          throw err;
+        }
+        const delay = initialDelay * Math.pow(multiplier, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (options?.signal?.aborted || this.abortController?.signal.aborted) {
+          throw err;
+        }
+      }
+    }
+    throw lastError;
+  }
+  /** Execute a stream factory with pre-stream retry: retries until first event, then committed. */
+  async *streamWithRetry(factory, options) {
+    const retry = options?.retry;
+    if (!retry || !retry.maxRetries || retry.maxRetries <= 0) {
+      yield* factory();
+      return;
+    }
+    const maxRetries = retry.maxRetries;
+    const initialDelay = retry.initialDelayMs ?? 1e3;
+    const multiplier = retry.backoffMultiplier ?? 2;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const stream = factory();
+        const iterator = stream[Symbol.asyncIterator]();
+        const first = await iterator.next();
+        if (first.done) return;
+        yield first.value;
+        while (true) {
+          const next = await iterator.next();
+          if (next.done) break;
+          yield next.value;
+        }
+        return;
+      } catch (err) {
+        if (attempt >= maxRetries || !this.isRetryableError(err, retry)) {
+          throw err;
+        }
+        const delay = initialDelay * Math.pow(multiplier, attempt);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        if (options?.signal?.aborted || this.abortController?.signal.aborted) {
+          throw err;
+        }
+      }
+    }
+  }
+  // ─── CallOptions Resolution ──────────────────────────────────
+  /** Resolve tools to use for this call (per-call override > config default) */
+  resolveTools(options) {
+    return options?.tools ?? this.config.tools ?? [];
+  }
+  // ─── Usage Enrichment ───────────────────────────────────────────
+  /** Enrich result usage with model/backend and fire onUsage callback */
+  enrichAndNotifyUsage(result, options) {
+    if (result.usage) {
+      result.usage = {
+        ...result.usage,
+        model: options.model,
+        backend: this.backendName
+      };
+      this.callOnUsage(result.usage);
+    }
+  }
+  /** Wrap a stream to enrich usage_update events and fire onUsage callback */
+  async *enrichStream(source, options) {
+    const model = options.model;
+    for await (const event of source) {
+      if (event.type === "usage_update") {
+        const usage = {
+          promptTokens: event.promptTokens,
+          completionTokens: event.completionTokens,
+          model,
+          backend: this.backendName
+        };
+        this.callOnUsage(usage);
+        yield { type: "usage_update", ...usage };
+      } else {
+        yield event;
+      }
+    }
+  }
+  /** Fire onUsage callback (fire-and-forget: errors logged, not propagated) */
+  callOnUsage(usage) {
+    if (!this.config.onUsage) return;
+    try {
+      this.config.onUsage(usage);
+    } catch (e) {
+      console.warn(
+        "[agent-sdk] onUsage callback error:",
+        e instanceof Error ? e.message : String(e)
+      );
+    }
+  }
+  // ─── Heartbeat ───────────────────────────────────────────────
+  /** Wrap a stream to emit heartbeat events at configured intervals.
+   *  When heartbeatInterval is not set, passes through directly. */
+  async *heartbeatStream(source) {
+    const interval = this.config.heartbeatInterval;
+    if (!interval || interval <= 0) {
+      yield* source;
+      return;
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    let pendingEvent = null;
+    let heartbeatResolve = null;
+    const timer = setInterval(() => {
+      if (heartbeatResolve) {
+        const resolve = heartbeatResolve;
+        heartbeatResolve = null;
+        resolve();
+      }
+    }, interval);
+    try {
+      while (true) {
+        if (!pendingEvent) {
+          pendingEvent = iterator.next();
+        }
+        const heartbeatPromise = new Promise((resolve) => {
+          heartbeatResolve = resolve;
+        });
+        const eventDone = pendingEvent.then(
+          (r) => ({ kind: "event", result: r })
+        );
+        const heartbeatDone = heartbeatPromise.then(
+          () => ({ kind: "heartbeat" })
+        );
+        const winner = await Promise.race([eventDone, heartbeatDone]);
+        if (winner.kind === "heartbeat") {
+          yield { type: "heartbeat" };
+        } else {
+          pendingEvent = null;
+          heartbeatResolve = null;
+          if (winner.result.done) break;
+          yield winner.result.value;
+        }
+      }
+    } finally {
+      clearInterval(timer);
+      heartbeatResolve = null;
+    }
+  }
+  // ─── Activity Timeout ────────────────────────────────────────
+  /** Wrap a stream to abort on inactivity. Resets timer on every event.
+   *  When timeoutMs is not set, passes through directly. */
+  async *activityTimeoutStream(source, timeoutMs, ac) {
+    if (!timeoutMs || timeoutMs <= 0) {
+      yield* source;
+      return;
+    }
+    const iterator = source[Symbol.asyncIterator]();
+    let timerId;
+    try {
+      while (true) {
+        const timeoutPromise = new Promise((_, reject) => {
+          timerId = setTimeout(() => reject(new ActivityTimeoutError(timeoutMs)), timeoutMs);
+        });
+        const result = await Promise.race([iterator.next(), timeoutPromise]);
+        clearTimeout(timerId);
+        if (result.done) break;
+        yield result.value;
+      }
+    } catch (err) {
+      if (err instanceof ActivityTimeoutError) {
+        ac.abort(err);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timerId);
+    }
+  }
+  // ─── Guards ───────────────────────────────────────────────────
+  guardReentrancy() {
+    if (this.state === "running" || this.state === "streaming") {
+      throw new ReentrancyError();
+    }
+  }
+  guardDisposed() {
+    if (this.state === "disposed") {
+      throw new DisposedError("Agent");
+    }
+  }
+  /** Throw AbortError if signal is already aborted */
+  checkAbort(signal) {
+    if (signal.aborted) {
+      throw new AbortError();
+    }
+  }
+  // ─── Internal Helpers ─────────────────────────────────────────
+  /** Clean up after a run completes (success, error, or abort). */
+  cleanupRun() {
+    this._cleanupExternalSignal?.();
+    this._cleanupExternalSignal = null;
+    this.state = "idle";
+    this.abortController = null;
+  }
+  createAbortController(externalSignal) {
+    const ac = new AbortController();
+    this.abortController = ac;
+    this._cleanupExternalSignal = null;
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        ac.abort();
+      } else {
+        const listener = () => ac.abort();
+        externalSignal.addEventListener("abort", listener, { once: true });
+        this._cleanupExternalSignal = () => externalSignal.removeEventListener("abort", listener);
+      }
+    }
+    return ac;
+  }
+};
+
+// src/backends/mock-llm.ts
+function extractPrompt(messages) {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role === "user") {
+      return typeof msg.content === "string" ? msg.content : msg.content.filter((p) => p.type === "text").map((p) => p.text).join("");
+    }
+  }
+  return "";
+}
+function resolveResponse(mode, messages, callIndex) {
+  switch (mode.type) {
+    case "echo":
+      return extractPrompt(messages);
+    case "static":
+      return mode.response;
+    case "scripted": {
+      if (mode.loop) {
+        return mode.responses[callIndex % mode.responses.length];
+      }
+      if (callIndex < mode.responses.length) {
+        return mode.responses[callIndex];
+      }
+      return mode.responses[mode.responses.length - 1];
+    }
+    case "error":
+      throw new AgentSDKError(mode.error, {
+        code: mode.code ?? "backend_error",
+        retryable: mode.recoverable ?? false
+      });
+  }
+}
+async function applyLatency(latency, signal) {
+  if (!latency) return;
+  const ms = latency.type === "fixed" ? latency.ms : latency.minMs + Math.random() * (latency.maxMs - latency.minMs);
+  if (ms <= 0) return;
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    if (signal.aborted) {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function chunkText(text, streaming) {
+  if (streaming?.chunkSize && streaming.chunkSize > 0) {
+    const chunks = [];
+    for (let i = 0; i < text.length; i += streaming.chunkSize) {
+      chunks.push(text.slice(i, i + streaming.chunkSize));
+    }
+    return chunks;
+  }
+  return text.split(/(\s+)/).filter(Boolean);
+}
+async function chunkDelay(streaming, signal) {
+  const ms = streaming?.chunkDelayMs;
+  if (!ms || ms <= 0) return;
+  await new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    if (signal.aborted) {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+      return;
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+var MockLLMAgent = class extends BaseAgent {
+  backendName = "mock-llm";
+  mode;
+  latency;
+  streaming;
+  finishReason;
+  permissions;
+  toolCallConfigs;
+  configuredStructuredOutput;
+  callIndex = 0;
+  constructor(config, options) {
+    super(config);
+    this.mode = options.mode ?? { type: "echo" };
+    this.latency = options.latency;
+    this.streaming = options.streaming;
+    this.finishReason = options.finishReason ?? "stop";
+    this.permissions = options.permissions;
+    this.toolCallConfigs = options.toolCalls ?? [];
+    this.configuredStructuredOutput = options.structuredOutput;
+  }
+  async executeRun(messages, _options, signal) {
+    this.checkAbort(signal);
+    await applyLatency(this.latency, signal);
+    this.checkAbort(signal);
+    const idx = this.callIndex++;
+    const output = resolveResponse(this.mode, messages, idx);
+    const toolCalls = this.toolCallConfigs.map((tc) => ({
+      toolName: tc.toolName,
+      args: tc.args ?? {},
+      result: tc.result ?? null,
+      approved: true
+    }));
+    return {
+      output,
+      structuredOutput: void 0,
+      toolCalls,
+      messages: [
+        ...messages,
+        { role: "assistant", content: output }
+      ],
+      usage: { promptTokens: 10, completionTokens: output.length }
+    };
+  }
+  async executeRunStructured(messages, _schema, _options, signal) {
+    this.checkAbort(signal);
+    await applyLatency(this.latency, signal);
+    this.checkAbort(signal);
+    const idx = this.callIndex++;
+    const output = resolveResponse(this.mode, messages, idx);
+    let parsed;
+    if (this.configuredStructuredOutput !== void 0) {
+      parsed = this.configuredStructuredOutput;
+    } else {
+      try {
+        parsed = JSON.parse(output);
+      } catch {
+        parsed = output;
+      }
+    }
+    return {
+      output,
+      structuredOutput: parsed,
+      toolCalls: [],
+      messages: [
+        ...messages,
+        { role: "assistant", content: output }
+      ],
+      usage: { promptTokens: 10, completionTokens: output.length }
+    };
+  }
+  async *executeStream(messages, _options, signal) {
+    this.checkAbort(signal);
+    await applyLatency(this.latency, signal);
+    this.checkAbort(signal);
+    if (this.permissions) {
+      yield* this.simulatePermissions(signal);
+    }
+    if (this.toolCallConfigs.length > 0) {
+      yield* this.simulateToolCalls(signal);
+    }
+    const idx = this.callIndex++;
+    const output = resolveResponse(this.mode, messages, idx);
+    const chunks = chunkText(output, this.streaming);
+    for (let i = 0; i < chunks.length; i++) {
+      this.checkAbort(signal);
+      if (i > 0) {
+        await chunkDelay(this.streaming, signal);
+      }
+      yield { type: "text_delta", text: chunks[i] };
+    }
+    yield {
+      type: "usage_update",
+      promptTokens: 10,
+      completionTokens: output.length
+    };
+    yield {
+      type: "done",
+      finalOutput: output,
+      finishReason: this.finishReason
+    };
+  }
+  async *simulateToolCalls(signal) {
+    for (let i = 0; i < this.toolCallConfigs.length; i++) {
+      this.checkAbort(signal);
+      const tc = this.toolCallConfigs[i];
+      const toolCallId = tc.toolCallId ?? `mock-tc-${i}`;
+      yield {
+        type: "tool_call_start",
+        toolCallId,
+        toolName: tc.toolName,
+        args: tc.args ?? {}
+      };
+      yield {
+        type: "tool_call_end",
+        toolCallId,
+        toolName: tc.toolName,
+        result: tc.result ?? null
+      };
+    }
+  }
+  async *simulatePermissions(signal) {
+    const perms = this.permissions;
+    for (const toolName of perms.toolNames) {
+      this.checkAbort(signal);
+      const request = {
+        toolName,
+        toolArgs: {}
+      };
+      yield { type: "permission_request", request };
+      if (perms.denyTools?.includes(toolName)) {
+        yield {
+          type: "permission_response",
+          toolName,
+          decision: { allowed: false, reason: "Denied by mock configuration" }
+        };
+      } else if (perms.autoApprove) {
+        yield {
+          type: "permission_response",
+          toolName,
+          decision: { allowed: true, scope: "once" }
+        };
+      } else {
+        const supervisor = this.getConfig().supervisor;
+        if (supervisor?.onPermission) {
+          const decision = await supervisor.onPermission(request, signal);
+          yield { type: "permission_response", toolName, decision };
+        } else {
+          yield {
+            type: "permission_response",
+            toolName,
+            decision: { allowed: true, scope: "once" }
+          };
+        }
+      }
+    }
+  }
+};
+var MockLLMService = class {
+  name = "mock-llm";
+  options;
+  models;
+  constructor(options = {}) {
+    this.options = options;
+    this.models = (options.models ?? [
+      { id: "mock-fast", name: "Mock Fast" },
+      { id: "mock-quality", name: "Mock Quality" }
+    ]).map((m) => ({
+      id: m.id,
+      name: m.name,
+      description: m.description
+    }));
+  }
+  createAgent(config) {
+    return new MockLLMAgent(config, this.options);
+  }
+  async listModels() {
+    return this.models;
+  }
+  async validate() {
+    return { valid: true, errors: [] };
+  }
+  async dispose() {
+  }
+};
+function createMockLLMService(options = {}) {
+  return new MockLLMService(options);
+}
+
+exports.createMockLLMService = createMockLLMService;
+//# sourceMappingURL=mock-llm.cjs.map
+//# sourceMappingURL=mock-llm.cjs.map