@ethosagent/core 0.2.7 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,175 @@
 import * as _ethosagent_types from '@ethosagent/types';
-import { HookRegistry, LLMProvider, ToolRegistry, PersonalityRegistry, MemoryProvider, SessionStore, ContextInjector, Storage, Session, SessionFilter, StoredMessage, SessionUsage, SearchResult, MemoryLoadContext, MemoryUpdate, PersonalityConfig, VoidHooks, ModifyingHooks, ClaimingHooks, Message, ToolDefinitionLite, CompletionOptions, CompletionChunk, Tool, ToolFilterOpts, ToolContext, 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, VoidHooks, ModifyingHooks, ClaimingHooks, ToolDefinitionLite, CompletionOptions, CompletionChunk, LLMProviderRegistry, LLMProviderFactory, MemoryProviderRegistry, MemoryProviderFactory, RequestDumpRecord, ScopedFetch, ScopedFs, ScopedFsEntry, ScopedProcess, SpawnOpts, ProcessResult, ScopedSecretsResolver, ToolFilterOpts, ToolResult } from '@ethosagent/types';
+export { MemoryConflictError } from '@ethosagent/types';
+import * as _ethosagent_safety_watcher from '@ethosagent/safety-watcher';
+import { InjectionClassifier } from '@ethosagent/safety-injection';
+import { NetworkPolicy } from '@ethosagent/safety-network';
 
+/** Raised by `request()` when a clarify is already pending for the session (plan Q5). */
+declare class ClarifyBusyError extends Error {
+    readonly code: "CLARIFY_BUSY";
+    constructor();
+}
+/** Raised by `request()` when the timeout fires and no `default` was provided (plan Q4/C). */
+declare class ClarifyTimedOutNoDefaultError extends Error {
+    readonly code: "CLARIFY_TIMED_OUT_NO_DEFAULT";
+    constructor();
+}
+/** Raised by `request()` when no interactive surface has registered a presenter. */
+declare class ClarifyNoSurfaceError extends Error {
+    readonly code: "CLARIFY_NO_SURFACE";
+    constructor();
+}
+interface ClarifyRequestInput {
+    question: string;
+    options?: string[];
+    default?: string;
+    timeoutMs: number;
+    answerableBy: ClarifyAnswerableBy;
+    sessionId: string;
+    surfaceType: ClarifySurfaceType;
+    surfaceContext?: Record<string, unknown>;
+    /** When the turn aborts, the pending clarify resolves as cancelled. */
+    abortSignal?: AbortSignal;
+}
+/** A surface registers this to present a pending clarify to the user. */
+type ClarifyPresenter = (req: PendingClarify) => void | Promise<void>;
+/**
+ * Fired when a pending clarify resolves (user answer, timeout, or cancel) —
+ * surfaces use it to tear down the prompt/modal/card they presented. The
+ * `row` carries the session id and request id; `response` is `null` for the
+ * timeout-no-default case (no answer was produced).
+ */
+type ClarifyResolvedListener = (row: PendingClarify, response: ClarifyResponse | null) => void;
+declare class ClarifyBridge {
+    readonly store: ClarifyStore;
+    private readonly pending;
+    private presenter;
+    private readonly resolvedListeners;
+    /**
+     * `store` is exposed read-only so a surface (e.g. TelegramClarifySurface)
+     * can patch `surfaceContext` after presenting the prompt and look up rows
+     * by id without proxying every call through the bridge.
+     */
+    constructor(store: ClarifyStore);
+    /** A surface registers how it presents a pending clarify to the user. */
+    setPresenter(presenter: ClarifyPresenter): void;
+    /**
+     * Subscribe to clarify resolutions so a surface can tear down its prompt
+     * when the request is answered, times out, or is cancelled. Returns an
+     * unsubscribe function.
+     */
+    onResolved(listener: ClarifyResolvedListener): () => void;
+    /** True iff a clarify is currently pending for the given session. */
+    hasPending(sessionId: string): boolean;
+    /** Pending rows still awaiting an answer — for SSE reconnect re-presentation. */
+    listPending(sessionId?: string): PendingClarify[];
+    /**
+     * Persisted pending rows from the store — for boot-time hydration (a surface
+     * that outlives a single process needs to find rows that survived a
+     * restart). `listPending()` only sees in-memory rows; this is the source of
+     * truth across restarts.
+     */
+    listPersisted(filter?: {
+        surfaceType?: string;
+        sessionId?: string;
+    }): Promise<PendingClarify[]>;
+    /**
+     * Issue a clarify request. Resolves when the user answers, the timeout fires
+     * (with `default`), or the turn aborts (as cancelled). Rejects with
+     * `ClarifyBusyError` if one is already pending for the session, or with
+     * `ClarifyTimedOutNoDefaultError` on timeout when no `default` was given.
+     */
+    request(input: ClarifyRequestInput): Promise<ClarifyResponse>;
+    /**
+     * Resolve a pending clarify. Called by a surface when the user answers or
+     * cancels, and internally on timeout. Unknown / already-resolved ids are
+     * swallowed (another surface or the timeout beat this one).
+     *
+     * Degraded-mode fallback: when no in-process entry exists but the row is
+     * still persisted (gateway crashed mid-clarify, then the user tapped the
+     * button after restart), still clear the row and notify listeners so the
+     * surface can edit its UI to the resolved state. The original `request()`
+     * promise is gone — the agent waiting on it died with the process — so
+     * the answer can't reach the LLM, but at least the visible prompt updates.
+     */
+    respond(response: ClarifyResponse): Promise<void>;
+    private notifyResolved;
+    /**
+     * Restart recovery: fire timeout responses for any persisted rows that have
+     * already passed their deadline. Called on boot and on an interval by
+     * surfaces that outlive a single turn (web-api, gateway).
+     *
+     * Listeners are notified for swept rows so surfaces can edit their UI in
+     * place — a card whose prompt timed out while the process was down should
+     * still update to the "timed out" state instead of hanging on buttons.
+     */
+    sweep(now?: Date): Promise<void>;
+    private fireTimeout;
+}
+
+interface RecordEventOpts {
+    traceId?: string;
+    spanId?: string;
+    code?: string;
+    cause?: string;
+    details?: Record<string, unknown>;
+    severity?: EventSeverity;
+}
+interface AgentLoopObservability {
+    startTurnTrace(opts: {
+        sessionId?: string;
+        personalityId?: string;
+        snapshotId?: string;
+        obsConfig?: PersonalityObservabilityConfig;
+        attrs?: Record<string, unknown>;
+    }): string;
+    endTrace(traceId: string, status: 'ok' | 'error' | 'aborted'): void;
+    startSpan(opts: {
+        traceId: string;
+        parentSpanId?: string;
+        kind: SpanKind;
+        name: string;
+        attrs?: Record<string, unknown>;
+        obsConfig?: PersonalityObservabilityConfig;
+    }): string;
+    endSpan(spanId: string, status: 'ok' | 'error' | 'blocked', attrs?: Record<string, unknown>): void;
+    recordSafetyBlock(opts: RecordEventOpts): void;
+    recordCompaction(opts: RecordEventOpts): void;
+    recordTierEscalation(opts: RecordEventOpts & {
+        from: string;
+        to: string;
+        reason: string;
+        personalityId: string;
+    }): void;
+    recordTierOverride(opts: RecordEventOpts & {
+        actor: 'user' | 'framework';
+        tier: string;
+        personalityId: string;
+    }): void;
+    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"];
+type KnownAgentEventType = (typeof KNOWN_AGENT_EVENT_TYPES)[number];
+/**
+ * Returns true when the event's `type` is one a current consumer knows
+ * about. Useful for development-mode warnings:
+ *
+ *     for await (const event of loop.run(...)) {
+ *       if (!isKnownAgentEvent(event)) {
+ *         console.warn('Unknown AgentEvent type:', event.type);
+ *         continue;
+ *       }
+ *       switch (event.type) { ... }
+ *     }
+ *
+ * Production code should silently skip unknown events; this helper is for
+ * test runs and dev surfaces that want to alert on newly-added variants.
+ */
+declare function isKnownAgentEvent(event: {
+    type: string;
+}): event is AgentEvent;
 type AgentEvent = {
     type: 'text_delta';
     text: string;
@@ -17,14 +186,14 @@ type AgentEvent = {
     toolName: string;
     message: string;
     percent?: number;
-    audience: 'internal' | 'user';
+    audience: 'internal' | 'user' | 'dashboard';
 } | {
     type: 'tool_end';
     toolCallId: string;
     toolName: string;
     ok: boolean;
     durationMs: number;
-    audience?: 'internal' | 'user';
+    audience?: 'internal' | 'user' | 'dashboard';
     /**
      * Tool output body — the success value when `ok`, or the error
      * message when `ok: false`. Optional so consumers that only care
@@ -67,6 +236,12 @@ interface AgentLoopConfig {
     tools?: ToolRegistry;
     personalities?: PersonalityRegistry;
     memory?: MemoryProvider;
+    /**
+     * Phase 3 — team id. When set, AgentLoop stamps `teamId` on every
+     * `ToolContext` so team memory tools can route to the correct team scope.
+     * Absent when running solo.
+     */
+    teamId?: string;
     session?: SessionStore;
     hooks?: HookRegistry;
     injectors?: ContextInjector[];
@@ -90,7 +265,63 @@ interface AgentLoopConfig {
      * `storage` is set.
      */
     dataDir?: string;
+    /**
+     * Optional observability adapter. When provided, AgentLoop records traces,
+     * spans, and events for LLM calls, tool calls, and errors via typed
+     * domain helpers. When absent, behaviour is identical to before — no
+     * observability writes occur.
+     */
+    observability?: AgentLoopObservability;
+    /**
+     * Ch.3c — Tier-2 LLM injection classifier. When provided, AgentLoop calls
+     * it after wrapping any `outputIsUntrusted` tool result whose Tier-1
+     * pattern check fired, whose content is > 500 chars, or when the active
+     * personality's `safety.injectionDefense.classifier.alwaysCallLLM` is set.
+     * When unset, only Tier-1 (regex) classification runs.
+     */
+    injectionClassifier?: InjectionClassifier;
+    /**
+     * Ch.6a — In-process watcher. When provided, AgentLoop forwards every
+     * tool_start / tool_end / usage event into watcher.observe() and acts
+     * on non-`allow` decisions:
+     *   - `terminate` → yield an `error` event and end the turn
+     *   - `pause`     → yield a user-visible `tool_progress` chip and end
+     *                    the turn (the user's next message resumes; the
+     *                    watcher's state is fresh per run via resetTurn())
+     *   - `force_approval` → set a per-iteration flag that promotes the
+     *                    next tool to requiresApproval (TODO — needs the
+     *                    approval-hook plumbing; for v1 we treat it as
+     *                    `pause` to fail safe)
+     * `allow` is the no-op path. Watcher decisions are recorded as
+     * `audit.watcher` events on the optional ObservabilityWriter.
+     */
+    watcher?: _ethosagent_safety_watcher.Watcher;
     modelRouting?: Record<string, string>;
+    /**
+     * Per-personality memory provider registry. Maps provider names ('markdown',
+     * 'vector', plugin-registered names) to factory functions. When a personality
+     * declares `memory.provider`, AgentLoop resolves from this map.
+     */
+    memoryProviders?: Map<string, (options?: Record<string, unknown>) => MemoryProvider | Promise<MemoryProvider>>;
+    /**
+     * E4 — Pluggable context-engine registry. When unset, AgentLoop builds
+     * a `DefaultContextEngineRegistry` (drop_oldest + semantic_summary
+     * placeholder + reference_preserving). Each personality picks an engine
+     * via `personality.context_engine`; unknown names fall back to
+     * `drop_oldest` with a one-line warning.
+     */
+    contextEngines?: ContextEngineRegistry;
+    /**
+     * Bridge for the `clarify` tool — the agent asks the user a structured
+     * question mid-turn and waits. Optional: when unset, the `clarify` tool
+     * reports `CLARIFY_NO_SURFACE` and the agent falls back to plain prose.
+     */
+    clarifyBridge?: ClarifyBridge;
+    /**
+     * Optional request dump store. When provided, AgentLoop appends a full
+     * record of each LLM request/response for offline analysis and debugging.
+     */
+    requestDumpStore?: RequestDumpStore;
     options?: {
         maxIterations?: number;
         historyLimit?: number;
@@ -128,6 +359,26 @@ interface RunOptions {
      * `MAX_SPAWN_DEPTH` can be enforced across recursive sub-agent calls.
      */
     agentId?: string;
+    /**
+     * FW-9 — `steer` busy-input mode. Surfaces (CLI REPL) push user-typed text
+     * here while the agent is mid-turn. AgentLoop drains the sink at the
+     * iteration seam (after tool_results land, before the next LLM call) and
+     * folds each entry in as a `[USER STEER]: <text>` text block on the user
+     * message carrying the tool_results.
+     *
+     * Pre-first-iteration (no tool_results yet) and idle (no run in flight)
+     * steering falls back to `queue` at the surface, never reaching AgentLoop.
+     */
+    steerSink?: SteerSink;
+    /** Per-turn inbound attachments from the user message. Persisted as an
+     *  `<attachments>` annotation prepended to the user text. Threaded to the
+     *  capability resolver via `ToolRegistry.setTurnAttachments()`. */
+    attachments?: _ethosagent_types.Attachment[];
+    /**
+     * Override model tier for this run only (from /tier command).
+     * Consumed once; does not persist across runs.
+     */
+    tierOverride?: _ethosagent_types.ModelTierName;
 }
 declare class AgentLoop {
     private readonly llm;
@@ -151,11 +402,30 @@ declare class AgentLoop {
     private readonly maxIdenticalToolCalls;
     private readonly streamingTimeoutMs;
     private readonly modelRouting;
+    private readonly memoryProviders;
     private readonly storage?;
     private readonly dataDir?;
+    private readonly observability?;
+    private readonly injectionClassifier?;
+    private readonly watcher?;
+    private readonly contextEngines;
+    /** Bridge for the `clarify` tool; undefined when no interactive surface is wired. */
+    readonly clarifyBridge?: ClarifyBridge;
+    /** Optional request dump store for full LLM request/response recording. */
+    private readonly requestDumpStore?;
+    /** Phase 3 — team id stamped onto ToolContext when loop runs inside a team. */
+    private readonly teamId?;
     /** 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;
     constructor(config: AgentLoopConfig);
+    /**
+     * Resolve a pending clarify request — called by an interactive surface when
+     * the user answers or cancels. No-op when no clarify bridge is wired or the
+     * request id is unknown (already resolved / timed out).
+     */
+    respondToClarify(response: _ethosagent_types.ClarifyResponse): Promise<void>;
     /** Returns all available tools for inventory display (e.g. TUI splash screen). */
     getAvailableTools(): _ethosagent_types.Tool[];
     /** Returns all registered personalities for inventory display. */
@@ -166,15 +436,118 @@ declare class AgentLoop {
     getSessionCost(sessionKey: string): number;
     /** Resets the session spend counter — call after /new or /personality switch. */
     resetSessionCost(sessionKey: string): void;
+    /**
+     * Resolve the effective model for an LLM call, respecting tier config.
+     * Returns the model string to pass as modelOverride, and the tier name used.
+     */
+    private resolveModelWithTier;
     run(text: string, opts?: RunOptions): AsyncGenerator<AgentEvent>;
     private handleChunk;
+    private dedupHistory;
     private toLLMMessages;
+    private handleUntrustedResult;
+    private maybeCompact;
     private buildScopedStorage;
 }
 
+declare function buildAttachmentAnnotation(attachments: Attachment[]): string;
+
+interface CapabilityBackends {
+    kvStoreFactory?: (tool: string, scopeId: string) => KeyValueStore;
+    secretsBackend?: (ref: SecretRef) => Promise<string>;
+    storage?: Storage;
+    personalityFsReach?: {
+        read: string[];
+        write: string[];
+    };
+    /**
+     * Full personality network policy. The `allow` list is intersected
+     * with each tool's declared `allowedHosts`; `deny` and
+     * `allow_private_urls` plus the always-on safety floor (cloud-metadata,
+     * private-network, scheme, DNS-rebinding) flow through `safeFetch`.
+     */
+    personalityNetworkPolicy?: NetworkPolicy;
+    attachmentCache?: _ethosagent_types.AttachmentCache;
+    inboundAttachments?: _ethosagent_types.Attachment[];
+}
+type ResolvedFields = Partial<Pick<ToolContext, 'kvStore' | 'secretsResolver' | 'scopedFetch' | 'scopedFs' | 'scopedProcess' | 'attachments'>>;
+interface CapabilityScopeIds {
+    sessionId: string;
+    personalityId?: string;
+}
+declare function resolveCapabilities(toolName: string, capabilities: ToolCapabilities | undefined, scopeIds: CapabilityScopeIds, backends: CapabilityBackends): ResolvedFields;
+
+interface CapabilityValidationError {
+    tool: string;
+    capability: string;
+    message: string;
+}
+declare function validateRegistration(tool: Tool, personality: PersonalityConfig): CapabilityValidationError[];
+
+declare class FileClarifyStore implements ClarifyStore {
+    private readonly storage;
+    private readonly root;
+    private readonly pendingPath;
+    /** Serializes the read-modify-write cycle within this process. */
+    private mutex;
+    /** `root` is the absolute `~/.ethos/clarify` directory (caller-resolved). */
+    constructor(storage: Storage, root: string);
+    add(req: PendingClarify): Promise<void>;
+    get(requestId: string): Promise<PendingClarify | null>;
+    list(filter?: {
+        surfaceType?: string;
+        sessionId?: string;
+    }): Promise<PendingClarify[]>;
+    remove(requestId: string): Promise<void>;
+    update(requestId: string, patch: Partial<PendingClarify>): Promise<void>;
+    expired(now: Date): Promise<PendingClarify[]>;
+    private readAll;
+    /** Run a read-modify-write under the per-process mutex with an atomic write. */
+    private mutate;
+}
+
+declare class DropOldestEngine implements ContextEngine {
+    readonly name = "drop_oldest";
+    compact(opts: ContextEngineCompactInput): Promise<ContextEngineCompactOutput>;
+}
+
+declare class ReferencePreservingEngine implements ContextEngine {
+    readonly name = "reference_preserving";
+    compact(opts: ContextEngineCompactInput): Promise<ContextEngineCompactOutput>;
+}
+
+type SummarizerFn = (middle: Message[], targetTokens: number) => Promise<string>;
+declare class SemanticSummaryEngine implements ContextEngine {
+    readonly name = "semantic_summary";
+    private readonly summarize;
+    constructor(opts?: {
+        summarize?: SummarizerFn;
+    });
+    compact(opts: ContextEngineCompactInput): Promise<ContextEngineCompactOutput>;
+}
+
+interface DefaultContextEngineRegistryOptions {
+    /** Optional summarizer wired into the SemanticSummaryEngine. Without it
+     *  that engine falls back to a placeholder summary (no LLM call). */
+    summarize?: SummarizerFn;
+}
+declare class DefaultContextEngineRegistry implements ContextEngineRegistry {
+    private readonly engines;
+    constructor(opts?: DefaultContextEngineRegistryOptions);
+    register(engine: ContextEngine): void;
+    get(name: string): ContextEngine | undefined;
+    names(): string[];
+}
+
+declare function estimateTokens(text: string): number;
+declare function estimateMessageTokens(message: Message): number;
+declare function estimateMessagesTokens(input: Message | Message[] | string): number;
+
 declare class InMemorySessionStore implements SessionStore {
     private sessions;
     private messages;
+    private compressions;
+    private turnState;
     private idCounter;
     createSession(data: Omit<Session, 'id' | 'createdAt' | 'updatedAt'>): Promise<Session>;
     getSession(id: string): Promise<Session | null>;
@@ -192,13 +565,36 @@ declare class InMemorySessionStore implements SessionStore {
         limit?: number;
         sessionId?: string;
     }): Promise<SearchResult[]>;
+    recordCompression(event: Omit<CompressionEvent, 'id' | 'createdAt'>): Promise<CompressionEvent>;
+    listCompressions(sessionId: string): Promise<CompressionEvent[]>;
+    recordTurnStart(sessionId: string): Promise<{
+        turnNumber: number;
+        lastCompactionTurn: number;
+    }>;
+    recordCompactionTurn(sessionId: string, turnNumber: number): Promise<void>;
     pruneOldSessions(olderThan: Date): Promise<number>;
     vacuum(): Promise<void>;
 }
 
+interface InMemoryToolContextOptions {
+    sessionId?: string;
+    sessionKey?: string;
+    platform?: string;
+    workingDir?: string;
+    personalityId?: string;
+    currentTurn?: number;
+    messageCount?: number;
+    resultBudgetChars?: number;
+    withStorage?: boolean;
+}
+declare function makeTestToolContext(opts?: InMemoryToolContextOptions): ToolContext;
+
 declare class NoopMemoryProvider implements MemoryProvider {
-    prefetch(_ctx: MemoryLoadContext): Promise<null>;
-    sync(_ctx: MemoryLoadContext, _updates: MemoryUpdate[]): Promise<void>;
+    prefetch(_ctx: MemoryContext): Promise<MemorySnapshot | null>;
+    read(_key: string, _ctx: MemoryContext): Promise<MemoryEntry | null>;
+    search(_query: string, _ctx: MemoryContext, _opts?: SearchOpts): Promise<MemoryEntry[]>;
+    sync(_updates: MemoryUpdate[], _ctx: MemoryContext): Promise<void>;
+    list(_ctx: MemoryContext, _opts?: ListOpts): Promise<MemoryEntryRef[]>;
 }
 
 declare class DefaultPersonalityRegistry implements PersonalityRegistry {
@@ -234,6 +630,115 @@ declare class DefaultHookRegistry implements HookRegistry {
     private remove;
 }
 
+/**
+ * Pass-through decorator that makes the wiring intent explicit: this provider
+ * uses eager prefetch (all content injected at session start).  The AgentLoop
+ * already calls `prefetch()` on every session open; this wrapper delegates all
+ * five methods unchanged.  Used for personality memory.
+ */
+declare class EagerPrefetchPolicy implements MemoryProvider {
+    private readonly inner;
+    constructor(inner: MemoryProvider);
+    prefetch(ctx: MemoryContext): Promise<MemorySnapshot | null>;
+    read(key: string, ctx: MemoryContext): Promise<MemoryEntry | null>;
+    search(query: string, ctx: MemoryContext, opts?: SearchOpts): Promise<MemoryEntry[]>;
+    sync(updates: MemoryUpdate[], ctx: MemoryContext): Promise<void>;
+    list(ctx: MemoryContext, opts?: ListOpts): Promise<MemoryEntryRef[]>;
+}
+/**
+ * Suppresses bulk prefetch.  `prefetch()` returns null so the AgentLoop does
+ * not inject all content at session start.  The existing
+ * `createTeamMemoryIndexInjector` in wiring handles the lightweight topic-index
+ * injection via `list()`.  All other methods delegate unchanged.
+ *
+ * Used for team memory: agents see a topic index and load content on demand via
+ * team_memory_read.
+ */
+declare class LazyOnDemandPolicy implements MemoryProvider {
+    private readonly inner;
+    constructor(inner: MemoryProvider);
+    prefetch(_ctx: MemoryContext): Promise<MemorySnapshot | null>;
+    read(key: string, ctx: MemoryContext): Promise<MemoryEntry | null>;
+    search(query: string, ctx: MemoryContext, opts?: SearchOpts): Promise<MemoryEntry[]>;
+    sync(updates: MemoryUpdate[], ctx: MemoryContext): Promise<void>;
+    list(ctx: MemoryContext, opts?: ListOpts): Promise<MemoryEntryRef[]>;
+}
+/**
+ * Wraps `sync()` with an optimistic-concurrency precondition check.
+ *
+ * The policy records the `mtime` (from `MemoryEntry.metadata.lastUpdatedAt`)
+ * each time `read()` or `search()` returns an entry, keyed by
+ * `${scopeId}:${key}`.  When `sync()` is called for a key the policy has a
+ * read-timestamp for, it re-reads the current `mtime` from the inner provider
+ * and rejects the write with a `MemoryConflictError` if the file has been
+ * modified since the caller last saw it.
+ *
+ * Keys never read (no timestamp recorded) pass through unconditionally —
+ * this avoids blocking blind adds on new keys.
+ *
+ * **Known limitation — not fully atomic:** the mtime check and the subsequent
+ * `inner.sync()` are not a single atomic operation.  Two concurrent writers
+ * that both pass the mtime check in the same millisecond can both write.  This
+ * is an inherent property of the decorator approach over a filesystem backend;
+ * a fully atomic compare-and-swap would require support in the storage layer.
+ * The policy catches the common case of sequential-but-concurrent agents where
+ * writes are spaced by network and tool-call latency.
+ *
+ * **Instance scope:** one `LastWriteWinsPolicy` instance tracks timestamps for
+ * one caller (typically one AgentLoop / session).  Do not share an instance
+ * across concurrent callers — the read-timestamp map is not thread-isolated and
+ * cross-caller reads would invalidate each other's preconditions.
+ *
+ * Used for team memory to prevent silent overwrites when two agents write the
+ * same file within the same session boundary.
+ */
+declare class LastWriteWinsPolicy implements MemoryProvider {
+    private readonly inner;
+    /** scopeId:key → mtime at last read (ms). */
+    private readonly lastReadAt;
+    constructor(inner: MemoryProvider);
+    prefetch(ctx: MemoryContext): Promise<MemorySnapshot | null>;
+    /** Records the entry's mtime so sync() can detect concurrent modifications. */
+    read(key: string, ctx: MemoryContext): Promise<MemoryEntry | null>;
+    /**
+     * Records mtimes for entries returned by search so that a write based on
+     * search results also benefits from conflict detection.
+     *
+     * Only sets the mtime when no prior timestamp is recorded for the key.
+     * Overwriting an existing timestamp from a search result would allow a
+     * stale write to pass: caller reads at mtime 1, external writer bumps to
+     * mtime 2, caller searches and the result records mtime 2, caller syncs
+     * stale content — conflict check passes because currentAt === recordedAt.
+     * Preserving the oldest (first-read) mtime ensures that risk does not apply.
+     */
+    search(query: string, ctx: MemoryContext, opts?: SearchOpts): Promise<MemoryEntry[]>;
+    /**
+     * For each key that was previously read, check the current mtime against
+     * the recorded read-timestamp.  Rejects the entire call if any key has been
+     * modified by another writer since the caller last read it.
+     *
+     * After a successful write, updates `lastReadAt` baselines so that a second
+     * `sync()` call on the same key does not spuriously fail.  Keys that were
+     * deleted are removed from the tracker so they can be re-added later.
+     */
+    sync(updates: MemoryUpdate[], ctx: MemoryContext): Promise<void>;
+    list(ctx: MemoryContext, opts?: ListOpts): Promise<MemoryEntryRef[]>;
+}
+
+/**
+ * Verify that `target` resolves to a path within (or equal to) `base`.
+ * Both paths are resolved to absolute before comparison.
+ *
+ * @throws BoundaryEscapeError if the resolved target escapes the base
+ */
+declare function assertWithinBase(base: string, target: string): void;
+declare class BoundaryEscapeError extends Error {
+    readonly code: "path-boundary-escape";
+    readonly base: string;
+    readonly resolved: string;
+    constructor(base: string, resolved: string);
+}
+
 type PluginFactory<T, C = unknown> = (config: C) => T | null;
 declare class PluginRegistry<T, C = unknown> {
     private readonly factories;
@@ -275,11 +780,155 @@ declare class ChainedProvider implements LLMProvider {
     private activeEntry;
 }
 
+declare class DefaultLLMProviderRegistry implements LLMProviderRegistry {
+    private readonly factories;
+    register(name: string, factory: LLMProviderFactory): void;
+    get(name: string): LLMProviderFactory | undefined;
+    list(): string[];
+}
+
+declare class DefaultMemoryProviderRegistry implements MemoryProviderRegistry {
+    private readonly factories;
+    register(name: string, factory: MemoryProviderFactory): void;
+    get(name: string): MemoryProviderFactory | undefined;
+    list(): string[];
+}
+
+/**
+ * Bounded in-memory request dump store for tests. Not suitable for production
+ * — use JsonlRequestDumpStore (or a durable implementation) instead.
+ * Caps at `maxRecords` to prevent unbounded memory growth.
+ */
+declare class InMemoryRequestDumpStore implements RequestDumpStore {
+    private records;
+    private readonly maxRecords;
+    constructor(opts?: {
+        maxRecords?: number;
+    });
+    append(record: RequestDumpRecord): Promise<void>;
+    recent(opts: {
+        limit: number;
+        sessionId?: string;
+        since?: Date;
+        includeContent?: boolean;
+    }): Promise<RequestDumpRecord[]>;
+    close(): Promise<void>;
+    getAll(): RequestDumpRecord[];
+}
+
+/**
+ * Strip ANSI escape sequences from untrusted output before rendering.
+ * Prevents terminal manipulation via LLM-generated or tool-fetched content.
+ *
+ * Covers:
+ * - CSI sequences (including private modes like ?25l, ?2004h): ESC[ ... <final>
+ * - OSC sequences terminated with BEL (\x07) or ST (ESC\): ESC] ... BEL|ST
+ * - Character set selection (G0/G1): ESC( <charset>
+ * - Other single-character escape sequences: ESC + one char
+ */
+declare function stripAnsiEscapes(input: string): string;
+
+/**
+ * Test seam — `safeFetch`'s injection points, mirrored on the wrapper so
+ * tests can stub DNS + fetch hermetically. Production wiring leaves
+ * these undefined; `safeFetch` defaults to `node:dns/promises#lookup`
+ * and `globalThis.fetch`.
+ */
+interface ScopedFetchTestSeam {
+    fetchImpl?: typeof fetch;
+    resolveHost?: (hostname: string) => Promise<string[]>;
+}
+/**
+ * Scoped network capability. Enforces two layers in order:
+ *
+ *  1. **Declared host allowlist** — the intersection of the tool's
+ *     `capabilities.network.allowedHosts` with the personality's
+ *     `safety.network.allow`, resolved at registration time.
+ *  2. **Non-overridable safety floor** — `safeFetch` runs scheme +
+ *     cloud-metadata + private-network + per-redirect-hop revalidation
+ *     regardless of declared hosts. A tool declaring `'*'` does NOT
+ *     bypass the floor; a personality permitting `169.254.169.254` is
+ *     still denied at the cloud-metadata layer.
+ *
+ * The two layers are not redundant: the allowlist is the policy
+ * surface tool authors and operators reason about; the floor catches
+ * the categories an allowlist can't (SSRF via redirect, DNS rebinding
+ * partial mitigation, file/data/javascript schemes).
+ */
+declare class ScopedFetchImpl implements ScopedFetch {
+    private readonly allowedHosts;
+    private readonly policy;
+    private readonly testSeam;
+    constructor(allowedHosts: Set<string>, policy: NetworkPolicy, testSeam?: ScopedFetchTestSeam);
+    fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+    private isHostAllowed;
+}
+
+/**
+ * Scoped filesystem capability. Enforces two layers on every call:
+ *
+ *  1. **Non-overridable deny floor** — `defaultAlwaysDeny()` lists
+ *     `.ssh`, `.aws/credentials`, `/etc/passwd`, `/root`, etc. A path
+ *     that touches any of these denies even when the capability and
+ *     personality both grant the parent (mirror of
+ *     `safety-network`'s cloud-metadata block).
+ *
+ *  2. **Declared reach allowlist** — the intersection of the tool's
+ *     `capabilities.fs_reach` with the personality's `fs_reach`,
+ *     resolved at registration time. Paths outside the allow set are
+ *     rejected with `PATH_NOT_REACHABLE`.
+ *
+ * The floor cannot be disabled by configuration. Tests that need to
+ * exercise a forbidden path override `$HOME` before constructing the
+ * wrapper.
+ */
+declare class ScopedFsImpl implements ScopedFs {
+    private readonly storage;
+    private readonly readPaths;
+    private readonly writePaths;
+    private readonly denyPaths;
+    constructor(storage: Storage, readPaths: Set<string>, writePaths: Set<string>);
+    read(path: string): Promise<string>;
+    readBytes(path: string): Promise<Uint8Array>;
+    write(path: string, content: string | Uint8Array): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    list(path: string): Promise<string[]>;
+    mtime(path: string): Promise<number | null>;
+    mkdir(dir: string): Promise<void>;
+    listEntries(dir: string): Promise<ScopedFsEntry[]>;
+    private checkReach;
+}
+
+declare class ScopedProcessImpl implements ScopedProcess {
+    private readonly allowedBinaries;
+    constructor(allowedBinaries: Set<string>);
+    spawn(binary: string, args: string[], opts?: SpawnOpts): Promise<ProcessResult>;
+}
+
+type SecretsBackend = (ref: SecretRef) => Promise<string>;
+declare class ScopedSecretsImpl implements ScopedSecretsResolver {
+    private readonly declaredRefs;
+    private readonly backend;
+    constructor(declaredRefs: Set<string>, backend: SecretsBackend);
+    get(ref: SecretRef): Promise<string>;
+}
+
 declare class DefaultToolRegistry implements ToolRegistry {
     private readonly tools;
+    private readonly backends?;
+    constructor(backends?: CapabilityBackends);
     register(tool: Tool, opts?: {
         pluginId?: string;
     }): void;
+    /**
+     * Validate every tool reachable for this personality (per
+     * `toolNamesForPersonality`) against the personality's policy. Only
+     * the tools the personality could actually call are checked — a
+     * personality that doesn't list `web_search` in its toolset does not
+     * fail because `web_search` declared `api.exa.ai` that's missing from
+     * `network.allow`.
+     */
+    validateToolsForPersonality(personality: PersonalityConfig): CapabilityValidationError[];
     registerAll(tools: Tool[]): void;
     unregister(name: string): void;
     get(name: string): Tool | undefined;
@@ -303,11 +952,35 @@ declare class DefaultToolRegistry implements ToolRegistry {
         toolCallId: string;
         name: string;
         args: unknown;
-    }>, ctx: ToolContext, allowedTools?: string[], filterOpts?: ToolFilterOpts): Promise<Array<{
+    }>, ctx: ToolContext, allowedTools?: string[], filterOpts?: ToolFilterOpts, turnAttachments?: _ethosagent_types.Attachment[]): Promise<Array<{
         toolCallId: string;
         name: string;
         result: ToolResult;
     }>>;
 }
 
-export { type AgentEvent, AgentLoop, type AgentLoopConfig, ChainedProvider, type ChainedProviderOptions, DefaultHookRegistry, DefaultPersonalityRegistry, DefaultToolRegistry, InMemorySessionStore, NoopMemoryProvider, type PluginFactory, PluginRegistry, type RunOptions };
+interface ValidateUrlOptions {
+    /** Allow requests to localhost/127.0.0.1 (default: false).
+     *  Useful for local LLM providers like Ollama. */
+    allowLocalhost?: boolean;
+    /** Additional hosts to allow even if they resolve to private IPs. */
+    trustedHosts?: string[];
+}
+declare class SsrfError extends Error {
+    constructor(url: string, reason: string);
+}
+/**
+ * Synchronous SSRF validator. Checks:
+ * 1. URL is well-formed
+ * 2. Scheme is http or https
+ * 3. No embedded credentials
+ * 4. Hostname is not a cloud metadata endpoint
+ * 5. If hostname is a literal IP, it must not be in a private range
+ * 6. Hostname is not `localhost` or `.local` / `.internal`
+ *
+ * Does NOT perform DNS resolution — use `safeFetch` from `@ethosagent/safety-network`
+ * for runtime fetches where DNS rebinding is a concern.
+ */
+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 };