@ethosagent/core 0.3.5 → 0.3.7

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _ethosagent_types from '@ethosagent/types';
-import { ClarifyStore, PendingClarify, ClarifyResponse, ClarifyAnswerableBy, ClarifySurfaceType, PersonalityObservabilityConfig, SpanKind, EventSeverity, HookRegistry, LLMProvider, ToolRegistry, PersonalityRegistry, MemoryProvider, SessionStore, ContextInjector, Storage, ContextEngineRegistry, RequestDumpStore, SteerSink, Attachment, KeyValueStore, SecretRef, ToolCapabilities, ToolContext, Tool, PersonalityConfig, ContextEngine, ContextEngineCompactInput, ContextEngineCompactOutput, Message, Session, SessionFilter, StoredMessage, SessionUsage, SearchResult, CompressionEvent, MemoryContext, MemorySnapshot, MemoryEntry, SearchOpts, MemoryUpdate, ListOpts, MemoryEntryRef, VoidHooks, ModifyingHooks, ClaimingHooks, ToolDefinitionLite, CompletionOptions, CompletionChunk, LLMProviderRegistry, LLMProviderFactory, MemoryProviderRegistry, MemoryProviderFactory, RequestDumpRecord, ScopedFetch, ScopedFs, ScopedFsEntry, ScopedProcess, SpawnOpts, ProcessResult, ScopedSecretsResolver, ToolFilterOpts, ToolResult } from '@ethosagent/types';
+import { ClarifyStore, PendingClarify, ClarifyResponse, ClarifyAnswerableBy, ClarifySurfaceType, PersonalityObservabilityConfig, SpanKind, EventSeverity, HookRegistry, LLMProvider, ToolRegistry, PersonalityRegistry, MemoryProvider, SessionStore, ContextInjector, Storage, ContextEngineRegistry, RequestDumpStore, SteerSink, Attachment, KeyValueStore, SecretRef, ToolCapabilities, ToolContext, Tool, PersonalityConfig, ContextEngine, ContextEngineCompactInput, ContextEngineCompactOutput, Message, Session, SessionFilter, StoredMessage, SessionUsage, SearchResult, CompressionEvent, MemoryContext, MemorySnapshot, MemoryEntry, SearchOpts, MemoryUpdate, ListOpts, MemoryEntryRef, ToolResult, VoidHooks, ModifyingHooks, ClaimingHooks, ToolDefinitionLite, CompletionOptions, CompletionChunk, LLMProviderRegistry, LLMProviderFactory, MemoryProviderRegistry, MemoryProviderFactory, RequestDumpRecord, ScopedFetch, ScopedFs, ScopedFsEntry, ScopedProcess, SpawnOpts, ProcessResult, ScopedSecretsResolver, ToolFilterOpts } from '@ethosagent/types';
 export { MemoryConflictError } from '@ethosagent/types';
 import * as _ethosagent_safety_watcher from '@ethosagent/safety-watcher';
 import { InjectionClassifier } from '@ethosagent/safety-injection';
@@ -150,7 +150,7 @@ interface AgentLoopObservability {
     flush(): void;
 }
 
-declare const KNOWN_AGENT_EVENT_TYPES: readonly ["text_delta", "thinking_delta", "tool_start", "tool_progress", "tool_end", "usage", "error", "done", "context_meta", "run_start"];
+declare const KNOWN_AGENT_EVENT_TYPES: readonly ["text_delta", "thinking_delta", "tool_start", "tool_progress", "tool_end", "usage", "error", "done", "context_meta", "run_start", "dry_run_summary"];
 type KnownAgentEventType = (typeof KNOWN_AGENT_EVENT_TYPES)[number];
 /**
  * Returns true when the event's `type` is one a current consumer knows
@@ -170,6 +170,11 @@ type KnownAgentEventType = (typeof KNOWN_AGENT_EVENT_TYPES)[number];
 declare function isKnownAgentEvent(event: {
     type: string;
 }): event is AgentEvent;
+interface DryRunToolPlan {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+}
 type AgentEvent = {
     type: 'text_delta';
     text: string;
@@ -230,6 +235,10 @@ type AgentEvent = {
     provider: string;
     model: string;
     source: 'team-coordinator' | 'team-personality' | 'personality' | 'global';
+} | {
+    type: 'dry_run_summary';
+    plan: DryRunToolPlan[];
+    capped: number;
 };
 interface AgentLoopConfig {
     llm: LLMProvider;
@@ -353,6 +362,14 @@ interface RunOptions {
     sessionKey?: string;
     personalityId?: string;
     abortSignal?: AbortSignal;
+    /** Sampling temperature forwarded to the LLM provider. */
+    temperature?: number;
+    /** Top-P (nucleus sampling) forwarded to the LLM provider. */
+    topP?: number;
+    /** Maps to CompletionOptions.maxTokens — separate name to avoid collision with AgentLoop's own maxTokens semantics. */
+    maxCompletionTokens?: number;
+    /** RNG seed forwarded to providers that support it (e.g. OpenAI-compat). */
+    seed?: number;
     /**
      * Identifier surfaced to tools as `ToolContext.agentId`. Delegation tools
      * use this to thread spawn depth (`depth:N`) into child loops so
@@ -379,6 +396,8 @@ interface RunOptions {
      * Consumed once; does not persist across runs.
      */
     tierOverride?: _ethosagent_types.ModelTierName;
+    dryRun?: boolean;
+    dryRunMaxToolCalls?: number;
 }
 declare class AgentLoop {
     private readonly llm;
@@ -452,6 +471,20 @@ declare class AgentLoop {
 
 declare function buildAttachmentAnnotation(attachments: Attachment[]): string;
 
+/**
+ * Derive a stable `botKey` from an opaque seed string.
+ *
+ * Returns the first 24 hex chars of sha256(seed) — 96 bits, wide enough
+ * that birthday collisions are cosmologically unlikely. The value is used
+ * as a routing/lane key and as a duplicate-detection key in bot binding
+ * validation.
+ *
+ * Every adapter and config layer that needs a stable bot identity must
+ * call this function rather than rolling its own hash. Two sources of
+ * truth for the algorithm means two sources of divergence.
+ */
+declare function deriveBotKey(seed: string): string;
+
 interface CapabilityBackends {
     kvStoreFactory?: (tool: string, scopeId: string) => KeyValueStore;
     secretsBackend?: (ref: SecretRef) => Promise<string>;
@@ -609,6 +642,10 @@ declare class DefaultPersonalityRegistry implements PersonalityRegistry {
     remove(id: string): void;
 }
 
+declare function redactArgs(args: unknown): unknown;
+declare function synthesizeDryRunResult(toolName: string, args: unknown): ToolResult;
+declare function synthesizeDryRunCapResult(_toolName: string, cap: number): ToolResult;
+
 declare class DefaultHookRegistry implements HookRegistry {
     private readonly voidHandlers;
     private readonly modifyingHandlers;
@@ -983,4 +1020,4 @@ declare class SsrfError extends Error {
  */
 declare function validateUrl(urlStr: string, opts?: ValidateUrlOptions): URL;
 
-export { type AgentEvent, AgentLoop, type AgentLoopConfig, type AgentLoopObservability, BoundaryEscapeError, type CapabilityBackends, type CapabilityScopeIds, type CapabilityValidationError, ChainedProvider, type ChainedProviderOptions, ClarifyBridge, ClarifyBusyError, ClarifyNoSurfaceError, type ClarifyPresenter, type ClarifyRequestInput, type ClarifyResolvedListener, ClarifyTimedOutNoDefaultError, DefaultContextEngineRegistry, type DefaultContextEngineRegistryOptions, DefaultHookRegistry, DefaultLLMProviderRegistry, DefaultMemoryProviderRegistry, DefaultPersonalityRegistry, DefaultToolRegistry, DropOldestEngine, EagerPrefetchPolicy, FileClarifyStore, InMemoryRequestDumpStore, InMemorySessionStore, type InMemoryToolContextOptions, KNOWN_AGENT_EVENT_TYPES, type KnownAgentEventType, LastWriteWinsPolicy, LazyOnDemandPolicy, NoopMemoryProvider, type PluginFactory, PluginRegistry, ReferencePreservingEngine, type RunOptions, ScopedFetchImpl, ScopedFsImpl, ScopedProcessImpl, ScopedSecretsImpl, type SecretsBackend, SemanticSummaryEngine, SsrfError, type SummarizerFn, type ValidateUrlOptions, assertWithinBase, buildAttachmentAnnotation, estimateMessageTokens, estimateMessagesTokens, estimateTokens, isKnownAgentEvent, makeTestToolContext, resolveCapabilities, stripAnsiEscapes, validateRegistration, validateUrl };
+export { type AgentEvent, AgentLoop, type AgentLoopConfig, type AgentLoopObservability, BoundaryEscapeError, type CapabilityBackends, type CapabilityScopeIds, type CapabilityValidationError, ChainedProvider, type ChainedProviderOptions, ClarifyBridge, ClarifyBusyError, ClarifyNoSurfaceError, type ClarifyPresenter, type ClarifyRequestInput, type ClarifyResolvedListener, ClarifyTimedOutNoDefaultError, DefaultContextEngineRegistry, type DefaultContextEngineRegistryOptions, DefaultHookRegistry, DefaultLLMProviderRegistry, DefaultMemoryProviderRegistry, DefaultPersonalityRegistry, DefaultToolRegistry, DropOldestEngine, type DryRunToolPlan, EagerPrefetchPolicy, FileClarifyStore, InMemoryRequestDumpStore, InMemorySessionStore, type InMemoryToolContextOptions, KNOWN_AGENT_EVENT_TYPES, type KnownAgentEventType, LastWriteWinsPolicy, LazyOnDemandPolicy, NoopMemoryProvider, type PluginFactory, PluginRegistry, ReferencePreservingEngine, type RunOptions, ScopedFetchImpl, ScopedFsImpl, ScopedProcessImpl, ScopedSecretsImpl, type SecretsBackend, SemanticSummaryEngine, SsrfError, type SummarizerFn, type ValidateUrlOptions, assertWithinBase, buildAttachmentAnnotation, deriveBotKey, estimateMessageTokens, estimateMessagesTokens, estimateTokens, isKnownAgentEvent, makeTestToolContext, redactArgs, resolveCapabilities, stripAnsiEscapes, synthesizeDryRunCapResult, synthesizeDryRunResult, validateRegistration, validateUrl };

package/dist/index.js

@@ -1,3 +1,63 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/dry-run.ts
+var dry_run_exports = {};
+__export(dry_run_exports, {
+  redactArgs: () => redactArgs,
+  synthesizeDryRunCapResult: () => synthesizeDryRunCapResult,
+  synthesizeDryRunResult: () => synthesizeDryRunResult
+});
+import { redactString } from "@ethosagent/safety-redact";
+function redactArgs(args) {
+  if (typeof args === "string") {
+    const redacted = redactString(args);
+    if (redacted.length > MAX_STRING_LENGTH) {
+      return `${redacted.slice(0, MAX_STRING_LENGTH)}...[truncated, ${redacted.length} chars]`;
+    }
+    return redacted;
+  }
+  if (Array.isArray(args)) {
+    return args.map(redactArgs);
+  }
+  if (args !== null && typeof args === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+      out[k] = redactArgs(v);
+    }
+    return out;
+  }
+  return args;
+}
+function synthesizeDryRunResult(toolName, args) {
+  const redacted = redactArgs(args);
+  return {
+    ok: true,
+    value: `[dry-run] ${toolName} would be called with: ${JSON.stringify(redacted)}`
+  };
+}
+function synthesizeDryRunCapResult(_toolName, cap) {
+  return {
+    ok: false,
+    error: `[dry-run] tool call cap (${cap}) reached \u2014 stopping tool execution for this turn`,
+    code: "not_available"
+  };
+}
+var MAX_STRING_LENGTH;
+var init_dry_run = __esm({
+  "src/dry-run.ts"() {
+    "use strict";
+    MAX_STRING_LENGTH = 500;
+  }
+});
+
 // src/agent-loop.ts
 import { createHash as createHash3, randomUUID } from "crypto";
 import { homedir as homedir2 } from "os";
@@ -141,6 +201,9 @@ function encodeAttr(value) {
   return value.replace(/[\r\n]+/g, " ").replace(/[<>]/g, "").replace(/"/g, "'").slice(0, 256);
 }
 
+// src/agent-loop.ts
+import { redactString as redactString2 } from "@ethosagent/safety-redact";
+
 // ../storage-fs/src/default-deny.ts
 import { homedir } from "os";
 function defaultAlwaysDeny() {
@@ -168,6 +231,38 @@ function defaultAlwaysDeny() {
   ];
 }
 
+// ../storage-fs/src/env-secrets.ts
+import { readFileSync } from "fs";
+var ENV_TO_REF = {
+  ANTHROPIC_API_KEY: "providers/anthropic/apiKey",
+  OPENAI_API_KEY: "providers/openai/apiKey",
+  OPENROUTER_API_KEY: "providers/openrouter/apiKey",
+  GEMINI_API_KEY: "providers/gemini/apiKey",
+  GROQ_API_KEY: "providers/groq/apiKey",
+  DEEPSEEK_API_KEY: "providers/deepseek/apiKey",
+  OLLAMA_HOST: "providers/ollama/host",
+  EXA_API_KEY: "providers/exa/apiKey",
+  REPLICATE_API_TOKEN: "providers/replicate/apiToken",
+  TELEGRAM_BOT_TOKEN: "channels/telegram/default/botToken",
+  SLACK_BOT_TOKEN: "channels/slack/default/botToken",
+  SLACK_APP_TOKEN: "channels/slack/default/appToken",
+  SLACK_SIGNING_SECRET: "channels/slack/default/signingSecret",
+  DISCORD_BOT_TOKEN: "channels/discord/default/botToken",
+  WHATSAPP_ACCESS_TOKEN: "channels/whatsapp/default/accessToken",
+  WHATSAPP_PHONE_NUMBER_ID: "channels/whatsapp/default/phoneNumberId",
+  SMTP_HOST: "channels/email/default/smtp/host",
+  SMTP_PORT: "channels/email/default/smtp/port",
+  SMTP_USER: "channels/email/default/smtp/user",
+  SMTP_PASSWORD: "channels/email/default/smtp/password",
+  IMAP_HOST: "channels/email/default/imap/host",
+  IMAP_USER: "channels/email/default/imap/user",
+  IMAP_PASSWORD: "channels/email/default/imap/password"
+};
+var REF_TO_ENV = /* @__PURE__ */ new Map();
+for (const [envKey, ref] of Object.entries(ENV_TO_REF)) {
+  REF_TO_ENV.set(ref, envKey);
+}
+
 // ../storage-fs/src/fs-attachment-cache.ts
 import { createHash } from "crypto";
 import { join, resolve, sep } from "path";
@@ -672,6 +767,9 @@ var DefaultPersonalityRegistry = class {
   }
 };
 
+// src/agent-loop.ts
+init_dry_run();
+
 // src/hook-registry.ts
 function isAllowed(h, allowedPlugins) {
   if (allowedPlugins === void 0) return true;
@@ -1557,6 +1655,14 @@ var DefaultToolRegistry = class {
             }
           };
         }
+        if (ctx.dryRun) {
+          const { synthesizeDryRunResult: synthesizeDryRunResult2 } = await Promise.resolve().then(() => (init_dry_run(), dry_run_exports));
+          return {
+            toolCallId: call.toolCallId,
+            name: call.name,
+            result: synthesizeDryRunResult2(call.name, call.args)
+          };
+        }
         const budget = Math.min(perCallBudget, entry.tool.maxResultChars ?? perCallBudget);
         const toolCtx = { ...ctx, resultBudgetChars: budget };
         try {
@@ -1622,7 +1728,8 @@ var KNOWN_AGENT_EVENT_TYPES = [
   "error",
   "done",
   "context_meta",
-  "run_start"
+  "run_start",
+  "dry_run_summary"
 ];
 function isKnownAgentEvent(event) {
   return KNOWN_AGENT_EVENT_TYPES.includes(event.type);
@@ -1895,7 +2002,7 @@ ${text}` : text;
         const heading = orderHints[e.key] ?? e.key;
         blocks.push(`## ${heading}
 
-${e.content.trim()}`);
+${redactString2(e.content.trim())}`);
       }
       if (blocks.length > 0) {
         let rendered = `## Memory
@@ -1926,6 +2033,11 @@ ${rendered.slice(-MEMORY_MAX_CHARS)}`;
       if (buildResult.prependSystem) systemParts.unshift(buildResult.prependSystem);
       if (buildResult.appendSystem) systemParts.push(buildResult.appendSystem);
     }
+    if (opts.dryRun) {
+      systemParts.push(
+        'IMPORTANT: You are in DRY-RUN mode. Every tool call will be intercepted and return a stub result \u2014 no tool actually executes. Plan your tool calls as normal but do NOT retry or loop when you see "[dry-run]" in the result. After your first batch of tool calls, summarize what you would have done and stop.'
+      );
+    }
     const systemPrompt = systemParts.join("\n\n").trim() || void 0;
     let llmMessages = this.toLLMMessages(this.dedupHistory(history));
     const compacted = await this.maybeCompact(llmMessages, systemPrompt ?? "", personality, {
@@ -1951,6 +2063,10 @@ ${rendered.slice(-MEMORY_MAX_CHARS)}`;
     let totalToolCalls = 0;
     let successfulToolCalls = 0;
     const toolNameCounts = /* @__PURE__ */ new Map();
+    const dryRunCap = opts.dryRun ? opts.dryRunMaxToolCalls ?? 5 : Infinity;
+    let dryRunCallCount = 0;
+    let dryRunCapped = 0;
+    const dryRunPlan = [];
     const dgConfig = personality.safety?.injectionDefense?.postReadDowngrade;
     const dgEnabled = injectionDefenseEnabled && dgConfig?.enabled !== false;
     const dgTurns = dgConfig?.turns ?? 2;
@@ -2078,7 +2194,11 @@ ${rendered.slice(-MEMORY_MAX_CHARS)}`;
           cacheSystemPrompt: true,
           abortSignal: combinedSignal,
           ...iterModelOverride ? { modelOverride: iterModelOverride } : {},
-          ...cacheBreakpoints ? { cacheBreakpoints } : {}
+          ...cacheBreakpoints ? { cacheBreakpoints } : {},
+          ...opts.temperature !== void 0 ? { temperature: opts.temperature } : {},
+          ...opts.topP !== void 0 ? { topP: opts.topP } : {},
+          ...opts.maxCompletionTokens !== void 0 ? { maxTokens: opts.maxCompletionTokens } : {},
+          ...opts.seed !== void 0 ? { seed: opts.seed } : {}
         });
         for await (const chunk of stream) {
           if (abortSignal.aborted) break;
@@ -2240,6 +2360,7 @@ ${rendered.slice(-MEMORY_MAX_CHARS)}`;
         memoryScope: personality.memoryScope,
         memoryScopeId: memScopeId,
         ...this.teamId !== void 0 && { teamId: this.teamId },
+        ...opts.dryRun ? { dryRun: true } : {},
         currentTurn: turnCount,
         messageCount: allMessages.length + turnCount,
         abortSignal,
@@ -2351,6 +2472,21 @@ ${rendered.slice(-MEMORY_MAX_CHARS)}`;
         opts.attachments
       ) : [];
       const execResultMap = new Map(execResults.map((r) => [r.toolCallId, r]));
+      if (opts.dryRun) {
+        for (const input of execInputs) {
+          dryRunPlan.push({
+            toolCallId: input.toolCallId,
+            toolName: input.name,
+            args: redactArgs(input.args)
+          });
+          dryRunCallCount++;
+          if (dryRunCallCount >= dryRunCap) {
+            const remaining = execInputs.length - execInputs.indexOf(input) - 1;
+            dryRunCapped += remaining;
+            break;
+          }
+        }
+      }
       if (typeof personality.model === "object" && personality.provider === this.llm.name) {
         for (const r of execResults) {
           if (r.name === "think_deeper" && r.result.ok) {
@@ -2510,6 +2646,13 @@ ${rendered.slice(-MEMORY_MAX_CHARS)}`;
     if (traceId) this.observability?.endTrace(traceId, "ok");
     this.observability?.flush();
     yield { type: "done", text: fullText, turnCount };
+    if (opts.dryRun && dryRunPlan.length > 0) {
+      yield {
+        type: "dry_run_summary",
+        plan: dryRunPlan,
+        capped: dryRunCapped
+      };
+    }
   }
   *handleChunk(chunk, pendingToolCalls, onText) {
     switch (chunk.type) {
@@ -2813,6 +2956,12 @@ function describeSource(toolName, args) {
   return void 0;
 }
 
+// src/bot-key.ts
+import { createHash as createHash4 } from "crypto";
+function deriveBotKey(seed) {
+  return createHash4("sha256").update(seed).digest("hex").slice(0, 24);
+}
+
 // src/clarify/clarify-bridge.ts
 import { randomUUID as randomUUID2 } from "crypto";
 var ClarifyBusyError = class extends Error {
@@ -3123,6 +3272,9 @@ function makeTestToolContext(opts) {
   return ctx;
 }
 
+// src/index.ts
+init_dry_run();
+
 // src/memory-policies.ts
 import { MemoryConflictError } from "@ethosagent/types";
 import { MemoryConflictError as MemoryConflictError2 } from "@ethosagent/types";
@@ -3626,13 +3778,17 @@ export {
   SsrfError,
   assertWithinBase,
   buildAttachmentAnnotation,
+  deriveBotKey,
   estimateMessageTokens,
   estimateMessagesTokens,
   estimateTokens,
   isKnownAgentEvent,
   makeTestToolContext,
+  redactArgs,
   resolveCapabilities,
   stripAnsiEscapes,
+  synthesizeDryRunCapResult,
+  synthesizeDryRunResult,
   validateRegistration,
   validateUrl2 as validateUrl
 };