@ethosagent/core 0.4.1 → 0.4.3

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, ToolResult, VoidHooks, ModifyingHooks, ClaimingHooks, ToolDefinitionLite, CompletionOptions, CompletionChunk, LLMProviderRegistry, LLMProviderFactory, MemoryProviderRegistry, MemoryProviderFactory, RequestDumpRecord, ScopedFetch, ScopedFs, ScopedFsEntry, ScopedProcess, SpawnOpts, ProcessResult, ScopedSecretsResolver, ToolResultReducerRegistry, ToolResultReducer, ToolFilterOpts } 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, ToolTransport, ToolProgressEvent, ToolExecuteRequest, NotificationRouter, NotifyOptions, NotificationAdapter, ToolDefinitionLite, CompletionOptions, CompletionChunk, LLMProviderRegistry, LLMProviderFactory, MemoryProviderRegistry, MemoryProviderFactory, RequestDumpRecord, ScopedFetch, ScopedFs, ScopedFsEntry, ScopedProcess, SpawnOpts, ProcessResult, ScopedSecretsResolver, SimpleCompletion, SimpleCompletionOptions, ToolResultReducerRegistry, ToolResultReducer, 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", "dry_run_summary"];
+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", "tool_approval_required", "tool_approval_response", "evaluators_complete", "credential_required", "notification_received"];
 type KnownAgentEventType = (typeof KNOWN_AGENT_EVENT_TYPES)[number];
 /**
  * Returns true when the event's `type` is one a current consumer knows
@@ -239,6 +239,41 @@ type AgentEvent = {
     type: 'dry_run_summary';
     plan: DryRunToolPlan[];
     capped: number;
+} | {
+    type: 'tool_approval_required';
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: 'tool_approval_response';
+    toolCallId: string;
+    approved: boolean;
+    reason?: string;
+} | {
+    type: 'evaluators_complete';
+    results: Array<{
+        name: string;
+        pass: boolean;
+        reason?: string;
+        score?: number;
+    }>;
+} | {
+    type: 'credential_required';
+    pluginId: string;
+    credentialKey: string;
+    kind: 'oauth' | 'api_key' | 'text';
+    label: string;
+    description?: string;
+    authUrl?: string;
+    sessionKey: string;
+    pendingUserMessage: string;
+} | {
+    type: 'notification_received';
+    pluginId: string;
+    sessionKey: string;
+    message: string;
+    startTurn: boolean;
+    payload?: Record<string, unknown>;
 };
 interface AgentLoopConfig {
     llm: LLMProvider;
@@ -337,6 +372,28 @@ interface AgentLoopConfig {
      * record of each LLM request/response for offline analysis and debugging.
      */
     requestDumpStore?: RequestDumpStore;
+    /** v2.2 — Callback to emit tool invocation metrics to the diagnostic store.
+     *  Wiring provides this; core never imports DiagnosticStore directly. */
+    onToolMetric?: (opts: {
+        pluginId: string;
+        toolName: string;
+        ok: boolean;
+        durationMs: number;
+        sessionId: string;
+        turnId: string;
+    }) => void;
+    /** v2.2 — Pre-turn credential check. Returns the first missing credential,
+     *  or null if all required credentials are present. Opt-in: when undefined,
+     *  the check is skipped. Wiring provides this when plugins declare required
+     *  credentials. */
+    credentialCheck?: (sessionKey: string, pendingUserMessage: string) => Promise<{
+        pluginId: string;
+        credentialKey: string;
+        kind: 'oauth' | 'api_key' | 'text';
+        label: string;
+        description?: string;
+        authUrl?: string;
+    } | null>;
     options?: {
         maxIterations?: number;
         historyLimit?: number;
@@ -449,10 +506,16 @@ declare class AgentLoop {
     private readonly teamId?;
     /** Per-personality MCP tool policy from mcp.yaml (NOT on PersonalityConfig). */
     private readonly mcpPolicy?;
+    /** v2.2 — Callback to emit per-tool invocation metrics to the diagnostic store. */
+    private readonly onToolMetric?;
+    /** v2.2 — Pre-turn credential check callback. */
+    private readonly credentialCheck?;
     /** Per-session accumulated spend in USD. Keyed by sessionKey. Reset via resetSessionCost(). */
     private readonly sessionCosts;
     /** FW-28 — per-session mtime registry. Keyed by sessionKey → (absPath → record). */
     private readonly sessionReadMtimes;
+    /** v2: per-run key/value store threaded into ToolContext for plugin communication. */
+    private readonly contextStore;
     constructor(config: AgentLoopConfig);
     /**
      * Resolve a pending clarify request — called by an interactive surface when
@@ -591,6 +654,17 @@ declare function estimateTokens(text: string): number;
 declare function estimateMessageTokens(message: Message): number;
 declare function estimateMessagesTokens(input: Message | Message[] | string): number;
 
+declare class ContextStore {
+    private readonly store;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T): void;
+    clear(): void;
+    asContextMethods(): {
+        getContext: <T>(key: string) => T | undefined;
+        setContext: <T>(key: string, value: T) => void;
+    };
+}
+
 declare class InMemorySessionStore implements SessionStore {
     private sessions;
     private messages;
@@ -684,6 +758,23 @@ declare class DefaultHookRegistry implements HookRegistry {
     private remove;
 }
 
+interface LocalToolTransportLiveCtx {
+    emit: (event: ToolProgressEvent) => void;
+    readMtimes?: Map<string, {
+        mtimeMs: number;
+        readAtTurn: number;
+    }>;
+    storage?: _ethosagent_types.Storage;
+    inboundAttachments?: Attachment[];
+}
+declare class LocalToolTransport implements ToolTransport {
+    private readonly lookup;
+    private readonly backends?;
+    private readonly getLiveCtx?;
+    constructor(lookup: (name: string) => Tool | undefined, backends?: CapabilityBackends | undefined, getLiveCtx?: (() => LocalToolTransportLiveCtx) | undefined);
+    execute(request: ToolExecuteRequest, signal: AbortSignal): Promise<ToolResult>;
+}
+
 /**
  * Pass-through decorator that makes the wiring intent explicit: this provider
  * uses eager prefetch (all content injected at session start).  The AgentLoop
@@ -779,6 +870,13 @@ declare class LastWriteWinsPolicy implements MemoryProvider {
     list(ctx: MemoryContext, opts?: ListOpts): Promise<MemoryEntryRef[]>;
 }
 
+declare class DefaultNotificationRouter implements NotificationRouter {
+    private readonly adapters;
+    route(pluginId: string, opts: NotifyOptions): Promise<void>;
+    register(sessionKey: string, adapter: NotificationAdapter): void;
+    deregister(sessionKey: string): void;
+}
+
 /**
  * Verify that `target` resolves to a path within (or equal to) `base`.
  * Both paths are resolved to absolute before comparison.
@@ -967,6 +1065,17 @@ declare class ScopedSecretsImpl implements ScopedSecretsResolver {
     get(ref: SecretRef): Promise<string>;
 }
 
+declare class SimpleCompletionImpl implements SimpleCompletion {
+    private readonly provider;
+    private readonly defaultModel;
+    private readonly onUsage;
+    constructor(provider: LLMProvider, defaultModel: string, onUsage: (tokens: {
+        input: number;
+        output: number;
+    }) => void);
+    complete(prompt: string, options?: SimpleCompletionOptions): Promise<string>;
+}
+
 declare function parseTemporalBound(input: string): Date | undefined;
 declare function toJournalKey(date: Date): string;
 declare function applyTemporalDecay(results: SearchResult[], options?: {
@@ -982,9 +1091,14 @@ declare class DefaultToolResultReducerRegistry implements ToolResultReducerRegis
 
 declare class DefaultToolRegistry implements ToolRegistry {
     private readonly tools;
+    private readonly resultCache;
     private readonly backends?;
     private readonly reducers?;
-    constructor(backends?: CapabilityBackends, reducers?: ToolResultReducerRegistry);
+    private readonly transport;
+    private turnLiveCtx;
+    constructor(backends?: CapabilityBackends, reducers?: ToolResultReducerRegistry, transport?: ToolTransport);
+    private cacheGet;
+    private cacheSet;
     register(tool: Tool, opts?: {
         pluginId?: string;
     }): void;
@@ -1002,6 +1116,8 @@ declare class DefaultToolRegistry implements ToolRegistry {
     get(name: string): Tool | undefined;
     getAvailable(): Tool[];
     getForToolset(toolset: string): Tool[];
+    /** v2.2 — Return the plugin id that registered a tool, if any. */
+    getPluginId(name: string): string | undefined;
     toDefinitions(allowedTools?: string[], filterOpts?: ToolFilterOpts): {
         name: string;
         description: string;
@@ -1016,11 +1132,12 @@ declare class DefaultToolRegistry implements ToolRegistry {
      * Used by IngestFilter to check skill.required_tools ⊆ effective_reach.
      */
     toolNamesForPersonality(personality: PersonalityConfig): Set<string>;
+    private applyFilters;
     executeParallel(calls: Array<{
         toolCallId: string;
         name: string;
         args: unknown;
-    }>, ctx: ToolContext, allowedTools?: string[], filterOpts?: ToolFilterOpts, turnAttachments?: _ethosagent_types.Attachment[]): Promise<Array<{
+    }>, ctx: ToolContext, allowedTools?: string[], filterOpts?: ToolFilterOpts, turnAttachments?: _ethosagent_types.Attachment[], filters?: _ethosagent_types.ToolInvocationFilter[]): Promise<Array<{
         toolCallId: string;
         name: string;
         result: ToolResult;
@@ -1051,4 +1168,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, DefaultToolResultReducerRegistry, 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, applyTemporalDecay, assertWithinBase, buildAttachmentAnnotation, deriveBotKey, estimateMessageTokens, estimateMessagesTokens, estimateTokens, isKnownAgentEvent, makeTestToolContext, parseTemporalBound, redactArgs, resolveCapabilities, stripAnsiEscapes, synthesizeDryRunCapResult, synthesizeDryRunResult, toJournalKey, 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, ContextStore, DefaultContextEngineRegistry, type DefaultContextEngineRegistryOptions, DefaultHookRegistry, DefaultLLMProviderRegistry, DefaultMemoryProviderRegistry, DefaultNotificationRouter, DefaultPersonalityRegistry, DefaultToolRegistry, DefaultToolResultReducerRegistry, DropOldestEngine, type DryRunToolPlan, EagerPrefetchPolicy, FileClarifyStore, InMemoryRequestDumpStore, InMemorySessionStore, type InMemoryToolContextOptions, KNOWN_AGENT_EVENT_TYPES, type KnownAgentEventType, LastWriteWinsPolicy, LazyOnDemandPolicy, LocalToolTransport, type LocalToolTransportLiveCtx, NoopMemoryProvider, type PluginFactory, PluginRegistry, ReferencePreservingEngine, type RunOptions, ScopedFetchImpl, ScopedFsImpl, ScopedProcessImpl, ScopedSecretsImpl, type SecretsBackend, SemanticSummaryEngine, SimpleCompletionImpl, SsrfError, type SummarizerFn, type ValidateUrlOptions, applyTemporalDecay, assertWithinBase, buildAttachmentAnnotation, deriveBotKey, estimateMessageTokens, estimateMessagesTokens, estimateTokens, isKnownAgentEvent, makeTestToolContext, parseTemporalBound, redactArgs, resolveCapabilities, stripAnsiEscapes, synthesizeDryRunCapResult, synthesizeDryRunResult, toJournalKey, validateRegistration, validateUrl };