@memberjunction/ai-agents 5.28.0 → 5.29.0

package/dist/ArtifactToolManager.d.ts

@@ -0,0 +1,165 @@
+import { NativeFileInput } from '@memberjunction/ai-core-plus';
+/**
+ * An input artifact provided to an agent run.
+ */
+export interface InputArtifact {
+    name: string;
+    typeName: string;
+    content: string | Buffer;
+    /** MIME type of the artifact content (e.g., 'application/pdf').
+     *  Populated for file-backed artifacts from ArtifactVersion.MimeType. */
+    mimeType?: string;
+    /** Optional: class name from ArtifactType.ToolLibraryClass metadata.
+     *  When set, used for plugin-based resolution via ClassFactory. */
+    toolLibraryClass?: string;
+}
+/**
+ * A single artifact tool invocation requested by the LLM.
+ */
+export interface ArtifactToolCall {
+    /** Alpha-sequence artifact ID assigned at run start (A, B, ... Z, AA, AB, etc.) */
+    artifactId: string;
+    /** Tool name from the documented tool list */
+    tool: string;
+    /** Tool-specific input parameters */
+    input: Record<string, unknown>;
+}
+export interface ArtifactToolSnapshot {
+    artifacts: Array<{
+        alphaId: string;
+        name: string;
+        typeName: string;
+    }>;
+    resultCount: number;
+}
+/**
+ * A single tool invocation, projected from the internal result store.
+ * Used for audit / training-data / debugging.
+ */
+export interface ArtifactAccessLogEntry {
+    artifactId: string;
+    tool: string;
+    input: Record<string, unknown>;
+    success: boolean;
+    errorMessage?: string;
+    timestamp: Date;
+    durationMs: number;
+}
+/**
+ * Manages artifact tools for a single agent run.
+ *
+ * Follows the ScratchpadManager pattern:
+ * - Instantiated once per run
+ * - Holds references to input artifacts with alpha IDs
+ * - Generates manifest + tool documentation for prompt injection
+ * - Executes tool calls and stores results for next turn
+ * - Serializable for persistence
+ */
+export declare class ArtifactToolManager {
+    private artifacts;
+    private toolResults;
+    private nextAlphaIndex;
+    /** Initialize with input artifacts, assigning alpha IDs */
+    Initialize(inputArtifacts: InputArtifact[]): void;
+    /** Register a mid-run artifact and return its alpha ID */
+    RegisterArtifact(artifact: InputArtifact): string;
+    /** Reset all state */
+    Clear(): void;
+    /** Whether any artifacts are available */
+    HasArtifacts(): boolean;
+    /**
+     * Returns artifact content formatted as NativeFileInput candidates for the
+     * AIPromptRunner. Only artifacts with a known MIME type and string/Buffer
+     * content are included. The runner will check each against the driver's
+     * FileCapabilities before actually attaching them.
+     *
+     * For each candidate, eagerly extracts text content so the Prompts package
+     * can fall back to a plain-text injection when the driver doesn't support
+     * native file input (e.g., Cerebras, older OpenAI-compat providers).
+     */
+    GetNativeFileInputCandidates(): Promise<NativeFileInput[]>;
+    /**
+     * Best-effort text extraction for fallback when the driver doesn't support
+     * native file input. Returns null if extraction fails or isn't applicable
+     * (e.g., images, audio).
+     */
+    private extractTextFallback;
+    /** Extract all text from a PDF buffer using pdfjs-dist. Returns null on failure. */
+    private extractPdfText;
+    /** Markdown manifest: artifact IDs, names, types */
+    ToManifestString(): string;
+    /** Markdown tool documentation grouped by artifact type */
+    GetToolDocumentation(): string;
+    /**
+     * Max characters for the tool results section injected into the prompt.
+     * Prevents context overflow when tool results contain large datasets.
+     * Results are truncated from oldest first, with a summary of what was dropped.
+     */
+    private static readonly MAX_RESULTS_CHARS;
+    /**
+     * Max characters for a single tool result's data section.
+     * Individual results that exceed this are truncated with a note,
+     * preventing one huge result from consuming the entire budget.
+     */
+    private static readonly MAX_SINGLE_RESULT_CHARS;
+    /** Markdown results from previous turns */
+    GetPendingResults(): string;
+    /** One-line summary for compact contexts */
+    GetSummary(): string;
+    /** Execute tool calls from LLM response */
+    ExecuteToolCalls(calls: ArtifactToolCall[]): Promise<void>;
+    /** Snapshot for persistence */
+    ToJSON(): ArtifactToolSnapshot;
+    /**
+     * Access log for this run — one entry per tool invocation, in call order.
+     * Useful for audit trails, training data capture, and debugging.
+     * Projected from the internal result store (no parallel state).
+     */
+    GetAccessLog(): ArtifactAccessLogEntry[];
+    /**
+     * Determines whether artifact content should be externalized to MJStorage
+     * instead of being stored inline.
+     */
+    static ShouldExternalizeContent(contentLength: number, options?: {
+        maxInlineChars?: number;
+    }): {
+        shouldExternalize: boolean;
+        reason: string;
+    };
+    /**
+     * Builds a truncated inline preview of a tables-based content JSON by keeping
+     * only the first `maxRowsPerTable` rows per table and attaching truncation metadata.
+     */
+    static BuildInlinePreview(contentJson: string, maxRowsPerTable?: number): string;
+    /** Generate next alpha-sequence ID: A, B, ... Z, AA, AB, ... */
+    private NextAlphaId;
+    /**
+     * Resolve a tool library for an artifact type, walking the ParentID chain
+     * of `MJ: Artifact Types` to collect libraries from the leaf type and all
+     * ancestors. Child libraries override parent libraries for same-named tools.
+     *
+     * Resolution order:
+     *  1. If the metadata engine is loaded, walk `typeName → parent → ...` via
+     *     `ArtifactMetadataEngine`, instantiating each level's `ToolLibraryClass`
+     *     via ClassFactory. Returns a CompositeArtifactToolLibrary.
+     *  2. If the engine isn't loaded or the type isn't found, resolve the single
+     *     leaf library using the `toolLibraryClass` hint plus name-based fallback.
+     *
+     * The engine is expected to be configured by AgentRunner before Initialize
+     * is called, so path (1) is the normal case.
+     */
+    private ResolveLibrary;
+    /**
+     * Walk the ParentID chain for `typeName` in ArtifactMetadataEngine,
+     * instantiating each level's ToolLibraryClass via ClassFactory.
+     * Returns the chain leaf-first. Levels without a ToolLibraryClass are
+     * skipped. Returns [] if the engine isn't loaded or the type isn't found.
+     */
+    private ResolveLibraryChain;
+    /**
+     * Single-library fallback when the metadata engine isn't available.
+     * Uses the provided `toolLibraryClass` hint first, then name-based heuristics.
+     */
+    private ResolveLeafLibrary;
+}
+//# sourceMappingURL=ArtifactToolManager.d.ts.map

package/dist/ArtifactToolManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArtifactToolManager.d.ts","sourceRoot":"","sources":["../src/ArtifactToolManager.ts"],"names":[],"mappings":"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"}