@modelprofile.com/flexharness-agent 6.0.0

package/dist_ts_agent/smartagent.interfaces.d.ts

@@ -0,0 +1,275 @@
+import type { ISmartAiCacheOptions, ToolSet, ModelMessage, TSmartAiLanguageModel, ProviderOptions, IToolExecutionContext, IToolJobState, TSmartAiCacheRetention, TSmartAiCacheSetting } from './plugins.js';
+import type { IAgentRuntimeEventPayload, IToolExecutionIntentEvent, TAgentEvent, TAgentGenerationOutcome, TAgentToolResultOutput } from './smartagent.events.js';
+import type { TAgentEventArchive, TAgentEventStore } from './smartagent.persistence.js';
+export type { ProviderOptions };
+export interface IAgentCacheOptions extends ISmartAiCacheOptions {
+}
+export type TAgentCacheRetention = TSmartAiCacheRetention;
+export type TAgentCacheSetting = TSmartAiCacheSetting;
+export type TAgentPrompt = Extract<ModelMessage, {
+    role: 'user';
+}>['content'];
+export interface IAgentToolCallRecord {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    output?: unknown;
+    error?: string;
+}
+export interface IAgentToolCallStartEvent {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+export interface IAgentToolCallUpdateEvent extends IAgentToolCallStartEvent {
+    /** Transient streamed output. The authoritative final output is delivered through onToolCallFinish. */
+    output: unknown;
+}
+export type TAgentToolCallFinishEvent = (IAgentToolCallStartEvent & {
+    success: true;
+    output: unknown;
+}) | (IAgentToolCallStartEvent & {
+    success: false;
+    error: string;
+});
+export interface IAgentContextOverflowInvocationOptions {
+    abortSignal?: AbortSignal;
+}
+export interface IAgentContextBuildOptions {
+    events: readonly TAgentEvent[];
+}
+export type TAgentContextBuilder = (options: IAgentContextBuildOptions) => ModelMessage[];
+export interface IAgentContextCompactionOptions {
+    abortSignal?: AbortSignal;
+    reason: 'context-overflow' | 'retention' | 'manual';
+}
+export type TAgentContextCompactor = (messages: ModelMessage[], events: readonly TAgentEvent[], options: IAgentContextCompactionOptions) => Promise<ModelMessage[]>;
+export interface IAgentEventRetentionOptions {
+    /** Compact and archive once the active event count exceeds this value. */
+    maxEvents: number;
+}
+export interface IAgentSessionChange {
+    type: 'committed' | 'updated' | 'archived';
+    events: readonly TAgentEvent[];
+}
+export type TAgentSessionChangeListener = (change: IAgentSessionChange) => void | Promise<void>;
+export interface IAgentSessionOptions {
+    /** Default SmartAI language model. May be omitted when every generation supplies a model. */
+    model?: TSmartAiLanguageModel;
+    /** System prompt override */
+    system?: string;
+    /** Tools available to the agent */
+    tools?: ToolSet;
+    /** Provider-specific AI SDK request options passed through to streamText() */
+    providerOptions?: ProviderOptions;
+    /** Stable session id used as provider prompt-cache affinity key where supported. */
+    sessionId?: string;
+    /** Optional event store. Transactional persistence requires IAgentEventStoreV2. */
+    eventStore?: TAgentEventStore;
+    /** Prompt-cache policy. Default: 'auto'. Set false to disable smartagent cache defaults. */
+    cache?: TAgentCacheSetting;
+    /**
+     * Maximum number of LLM↔tool round trips.
+     * Each step may execute multiple tools in parallel.
+     * Default: 20
+     */
+    maxSteps?: number;
+    /** Initial canonical events. */
+    events?: readonly TAgentEvent[];
+    /** Initial AI SDK messages, converted to canonical events at the session boundary. */
+    messages?: ModelMessage[];
+    /** Optional host execution context, including background jobs. */
+    executionContext?: IToolExecutionContext;
+    /** Projects canonical events into model messages. Default: buildModelMessages(). */
+    contextBuilder?: TAgentContextBuilder;
+    /** Explicit context compactor used by manual and event-retention compaction. */
+    contextCompactor?: TAgentContextCompactor;
+    /** Optional bounded active-event policy. Requires contextCompactor and eventStore.archive. */
+    eventRetention?: IAgentEventRetentionOptions;
+    /** Maximum wait for each session change listener. Default: 30 seconds. */
+    changeListenerTimeoutMs?: number;
+    /** Maximum queued changes per listener before that listener is removed. Default: 1000. */
+    maxPendingSessionChanges?: number;
+    /** Maximum wait for each generation lease cleanup attempt. Default: 30 seconds. */
+    generationLeaseCleanupTimeoutMs?: number;
+    /** Recent archived transaction identities retained for idempotency/reuse checks. Default: 1000. */
+    maxArchivedTransactionTombstones?: number;
+    /** Projects persisted transactional interruption reasons. Defaults to the thrown error string. */
+    transactionOutcomeErrorProjector?: (error: unknown) => string;
+    /** Called for each streamed text delta */
+    onToken?: (delta: string) => void;
+    /** Called when the model starts a streamed reasoning summary */
+    onReasoningStart?: (id: string, providerMetadata?: unknown) => void;
+    /** Called for each streamed reasoning summary delta */
+    onReasoningDelta?: (id: string, delta: string, providerMetadata?: unknown) => void;
+    /** Called when a streamed reasoning summary completes */
+    onReasoningEnd?: (id: string, text: string, providerMetadata?: unknown) => void;
+    /** Called when a tool call starts, with its stable AI SDK call id. */
+    onToolCallStart?: (event: IAgentToolCallStartEvent) => void;
+    /**
+     * Called immediately for each distinct streamed tool output. Updates are transient and are not
+     * persisted; the last update may equal the authoritative output later sent to onToolCallFinish.
+     */
+    onToolCallUpdate?: (event: IAgentToolCallUpdateEvent) => void;
+    /** Called when a tool call finishes, with its stable AI SDK call id and success state. */
+    onToolCallFinish?: (event: TAgentToolCallFinishEvent) => void;
+    /** @deprecated Use onToolCallStart instead. */
+    onToolCall?: (toolName: string, input: unknown) => void;
+    /** @deprecated Use onToolCallFinish instead. */
+    onToolResult?: (toolName: string, result: unknown) => void;
+    /**
+     * Called when total token usage approaches the model's context limit.
+     * Receives the full message history and must return a compacted replacement.
+     * If not provided, generation throws a ContextOverflowError instead.
+     */
+    onContextOverflow?: (messages: ModelMessage[], invocationOptions: IAgentContextOverflowInvocationOptions) => Promise<ModelMessage[]>;
+    /** Maximum context-overflow compaction retries before throwing. Default: 3. */
+    maxContextOverflowRetries?: number;
+}
+export interface IAgentRunOptions extends IAgentSessionOptions {
+    /** The language model to use, for example from ModelRegistry.getModel(). */
+    model: TSmartAiLanguageModel;
+    /** Initial user message or task description */
+    prompt: TAgentPrompt;
+    /**
+     * Validate the completed run. Return a string to reject the run and reprompt,
+     * or return void to accept the result.
+     */
+    validateCompletion?: (result: IAgentRunResult) => Promise<string | void> | string | void;
+    /** Number of validation-triggered reprompts allowed. Default: 0 */
+    maxValidationRetries?: number;
+    /** AbortSignal to cancel this run. Background jobs have independent cancellation. */
+    abort?: AbortSignal;
+}
+export interface IAgentGenerationHandle {
+    readonly generationId: string;
+    readonly claimToken: string;
+}
+export interface IAgentBeginGenerationOptions {
+    /** Stable caller-owned identity used to make begin retries deterministic. */
+    generationId?: string;
+}
+export interface IAgentGenerationPreparationContext {
+    generationId: string;
+    abortSignal: AbortSignal;
+}
+export interface IAgentGenerationLease {
+    model?: TSmartAiLanguageModel;
+    system?: string;
+    tools?: ToolSet;
+    providerOptions?: ProviderOptions;
+    cache?: TAgentCacheSetting;
+    maxSteps?: number;
+    /**
+     * Must be safe to call repeatedly and concurrently after failure or timeout.
+     * A timeout does not cancel the original close attempt, so a retry may overlap it.
+     */
+    close?(): Promise<void>;
+}
+export declare class AgentGenerationLeaseCleanupError extends Error {
+    readonly lease: IAgentGenerationLease;
+    readonly cleanupCause: unknown;
+    private readonly retryCleanupFunction;
+    constructor(lease: IAgentGenerationLease, cleanupCause: unknown, retryCleanupFunction: () => Promise<void>);
+    retryCleanup(): Promise<void>;
+}
+export type TAgentGenerationPrepare = (context: IAgentGenerationPreparationContext) => Promise<IAgentGenerationLease> | IAgentGenerationLease;
+export interface IAgentGenerateOptions {
+    /** Per-generation model override. A prepared lease takes precedence. */
+    model?: TSmartAiLanguageModel;
+    /** Per-generation system prompt override. A prepared lease takes precedence. */
+    system?: string;
+    /** Per-generation tool override. A prepared lease takes precedence. */
+    tools?: ToolSet;
+    /** Per-generation provider options override. A prepared lease takes precedence. */
+    providerOptions?: ProviderOptions;
+    /** Per-generation prompt-cache override. A prepared lease takes precedence. */
+    cache?: TAgentCacheSetting;
+    /** Maximum completed model steps for this generation. */
+    maxSteps?: number;
+    /** Cancels only this generation and its synchronous tool executions. */
+    abort?: AbortSignal;
+    /** Opt-in transactional claim returned by beginGeneration(). */
+    transaction?: IAgentGenerationHandle;
+    /**
+     * Optionally acquires generation-scoped resources in transactional or legacy mode.
+     * Called at most once, only if execution reaches preparation. Persisted transactions
+     * have durable V2 execution authority first; legacy/process-local calls do not.
+     * The callback owns cleanup of partial acquisition if it throws before returning a lease.
+     */
+    prepare?: TAgentGenerationPrepare;
+}
+export interface IAgentScheduleGenerateOptions extends IAgentGenerateOptions {
+    /** Coalescing identity for this scheduled generation. */
+    key: string;
+    /** Quiet period before the generation is queued. Reset by same-key calls. Default: 50ms. */
+    debounceMs?: number;
+}
+export interface IAgentCompactOptions {
+    abort?: AbortSignal;
+    reason?: 'retention' | 'manual';
+}
+export type TAgentToolExecutionReconciliationOptions = {
+    resolution: 'executed';
+    output: unknown;
+    modelOutput: TAgentToolResultOutput;
+} | {
+    resolution: 'not-executed' | 'abandoned-unknown';
+    error?: string;
+};
+export interface IAgentRunResult {
+    /** Final text output from the model */
+    text: string;
+    /** Active model-message projection after any configured projection or compaction. */
+    messages: ModelMessage[];
+    /** Total steps taken */
+    steps: number;
+    /** Finish reason from the final step */
+    finishReason: string;
+    /** Accumulated token usage across all steps */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens: number;
+        cacheWriteTokens: number;
+    };
+    /** Tool calls observed during the run, including inputs and outputs/errors when available */
+    toolCalls: IAgentToolCallRecord[];
+}
+export interface IAgentGenerateResult extends IAgentRunResult {
+    /** Raw canonical events remain available independently from model messages. */
+    events: readonly TAgentEvent[];
+}
+export interface IAgentSessionAbortOptions {
+    /** Also abort all currently running jobs owned by executionContext.jobs. Default: false. */
+    abortBackgroundJobs?: boolean;
+}
+export interface IAgentSession {
+    /** True once close() has released all retryable runtime cleanup ownership. */
+    readonly closeCleanupCompleted: boolean;
+    pushEvent(event: TAgentEvent): Promise<void>;
+    pushUserMessage(content: TAgentPrompt): Promise<void>;
+    pushRuntimeEvent(event: IAgentRuntimeEventPayload): Promise<void>;
+    beginGeneration(content: TAgentPrompt, options?: IAgentBeginGenerationOptions): Promise<IAgentGenerationHandle>;
+    generate(options?: IAgentGenerateOptions): Promise<IAgentGenerateResult>;
+    finalizeGeneration(transaction: IAgentGenerationHandle, outcome: TAgentGenerationOutcome): Promise<void>;
+    listUncertainToolExecutions(): IToolExecutionIntentEvent[];
+    reconcileToolExecution(intentId: string, reconciliation: TAgentToolExecutionReconciliationOptions): Promise<void>;
+    scheduleGenerate(options: IAgentScheduleGenerateOptions): Promise<IAgentGenerateResult>;
+    cancelScheduledGeneration(key: string, reason?: unknown): boolean;
+    compact(options?: IAgentCompactOptions): Promise<void>;
+    archiveCompactedEvents(compactionEventId?: string): Promise<TAgentEventArchive | undefined>;
+    subscribe(listener: TAgentSessionChangeListener): () => void;
+    getEvents(): readonly TAgentEvent[];
+    getModelMessages(): ModelMessage[];
+    getBackgroundExecution(executionId: string): Promise<IToolJobState>;
+    abortBackgroundExecution(executionId: string): Promise<void>;
+    abortCurrentGeneration(reason?: unknown): void;
+    abortSession(reason?: unknown, options?: IAgentSessionAbortOptions): Promise<void>;
+    /** Rejects when called from an active prepare, lease cleanup, tool, or compactor callback. */
+    close(): Promise<void>;
+}
+export declare class ContextOverflowError extends Error {
+    constructor(message?: string);
+}

package/dist_ts_agent/smartagent.interfaces.js

@@ -0,0 +1,24 @@
+export class AgentGenerationLeaseCleanupError extends Error {
+    lease;
+    cleanupCause;
+    retryCleanupFunction;
+    constructor(lease, cleanupCause, retryCleanupFunction) {
+        super(`Generation lease cleanup failed: ${cleanupCause instanceof Error
+            ? cleanupCause.message
+            : String(cleanupCause)}`);
+        this.name = 'AgentGenerationLeaseCleanupError';
+        this.lease = lease;
+        this.cleanupCause = cleanupCause;
+        this.retryCleanupFunction = retryCleanupFunction;
+    }
+    retryCleanup() {
+        return this.retryCleanupFunction();
+    }
+}
+export class ContextOverflowError extends Error {
+    constructor(message = 'Agent context limit reached and no onContextOverflow handler provided') {
+        super(message);
+        this.name = 'ContextOverflowError';
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic21hcnRhZ2VudC5pbnRlcmZhY2VzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHNfYWdlbnQvc21hcnRhZ2VudC5pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXNOQSxNQUFNLE9BQU8sZ0NBQWlDLFNBQVEsS0FBSztJQUN6QyxLQUFLLENBQXdCO0lBQzdCLFlBQVksQ0FBVTtJQUNyQixvQkFBb0IsQ0FBc0I7SUFFM0QsWUFDRSxLQUE0QixFQUM1QixZQUFxQixFQUNyQixvQkFBeUM7UUFFekMsS0FBSyxDQUNILG9DQUFvQyxZQUFZLFlBQVksS0FBSztZQUMvRCxDQUFDLENBQUMsWUFBWSxDQUFDLE9BQU87WUFDdEIsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxZQUFZLENBQUMsRUFBRSxDQUMzQixDQUFDO1FBQ0YsSUFBSSxDQUFDLElBQUksR0FBRyxrQ0FBa0MsQ0FBQztRQUMvQyxJQUFJLENBQUMsS0FBSyxHQUFHLEtBQUssQ0FBQztRQUNuQixJQUFJLENBQUMsWUFBWSxHQUFHLFlBQVksQ0FBQztRQUNqQyxJQUFJLENBQUMsb0JBQW9CLEdBQUcsb0JBQW9CLENBQUM7SUFDbkQsQ0FBQztJQUVNLFlBQVk7UUFDakIsT0FBTyxJQUFJLENBQUMsb0JBQW9CLEVBQUUsQ0FBQztJQUNyQyxDQUFDO0NBQ0Y7QUF5SEQsTUFBTSxPQUFPLG9CQUFxQixTQUFRLEtBQUs7SUFDN0MsWUFBWSxPQUFPLEdBQUcsdUVBQXVFO1FBQzNGLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztRQUNmLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7SUFDckMsQ0FBQztDQUNGIn0=

package/dist_ts_agent/smartagent.persistence.d.ts

@@ -0,0 +1,88 @@
+import type { TAgentEvent } from './smartagent.events.js';
+interface IAgentEventSnapshotBase {
+    sessionId: string;
+    revision: number;
+    updatedAt: number;
+    events: TAgentEvent[];
+}
+/** Legacy schema-1 snapshot contract used by IAgentEventStore. */
+export interface IAgentEventSnapshot extends IAgentEventSnapshotBase {
+    schemaVersion: 1;
+}
+export interface IAgentEventSnapshotV2 extends IAgentEventSnapshotBase {
+    schemaVersion: 2;
+}
+export type TAgentEventSnapshot = IAgentEventSnapshot | IAgentEventSnapshotV2;
+interface IAgentEventArchiveBase {
+    sessionId: string;
+    archiveId: string;
+    createdAt: number;
+    events: TAgentEvent[];
+}
+/** Legacy schema-1 archive contract used by IAgentEventStore. */
+export interface IAgentEventArchive extends IAgentEventArchiveBase {
+    schemaVersion: 1;
+}
+export interface IAgentEventArchiveV2 extends IAgentEventArchiveBase {
+    schemaVersion: 2;
+}
+export type TAgentEventArchive = IAgentEventArchive | IAgentEventArchiveV2;
+/** Legacy custom-store contract. It must read and write schema 1 only. */
+export interface IAgentEventStore {
+    load(sessionId: string): Promise<IAgentEventSnapshot | undefined>;
+    save(sessionId: string, events: readonly TAgentEvent[], expectedRevision: number): Promise<number>;
+    archive?(archive: IAgentEventArchive): Promise<void>;
+    loadArchive?(sessionId: string, archiveId: string): Promise<IAgentEventArchive | undefined>;
+}
+/** Schema-2 capability required for persisted transactional generations. */
+export interface IAgentEventStoreV2 {
+    readonly eventSchemaVersion: 2;
+    load(sessionId: string): Promise<TAgentEventSnapshot | undefined>;
+    save(sessionId: string, events: readonly TAgentEvent[], expectedRevision: number): Promise<number>;
+    archive?(archive: IAgentEventArchiveV2): Promise<void>;
+    loadArchive?(sessionId: string, archiveId: string): Promise<TAgentEventArchive | undefined>;
+}
+export type TAgentEventStore = IAgentEventStore | IAgentEventStoreV2;
+export declare const isAgentEventStoreV2: (store: TAgentEventStore | undefined) => store is IAgentEventStoreV2;
+/** Validates and returns a canonical schema-2 Agent event snapshot. */
+export declare const validateAgentEventSnapshotV2: (value: unknown, expectedSessionId?: string) => IAgentEventSnapshotV2;
+/** Validates and returns a canonical schema-2 Agent event archive. */
+export declare const validateAgentEventArchiveV2: (value: unknown, expectedSessionId?: string, expectedArchiveId?: string) => IAgentEventArchiveV2;
+export declare class AgentEventStoreConflictError extends Error {
+    readonly sessionId: string;
+    readonly expectedRevision: number;
+    readonly actualRevision: number;
+    constructor(sessionId: string, expectedRevision: number, actualRevision: number);
+}
+export declare class InMemoryAgentEventStore implements IAgentEventStoreV2 {
+    readonly eventSchemaVersion: 2;
+    private readonly snapshots;
+    private readonly archives;
+    load(sessionId: string): Promise<TAgentEventSnapshot | undefined>;
+    save(sessionId: string, events: readonly TAgentEvent[], expectedRevision: number): Promise<number>;
+    archive(archive: IAgentEventArchiveV2): Promise<void>;
+    loadArchive(sessionId: string, archiveId: string): Promise<TAgentEventArchive | undefined>;
+}
+export interface IFileAgentEventStoreOptions {
+    rootDir: string;
+    /** Maximum time spent waiting for another writer. Default: 10 seconds. */
+    lockTimeoutMs?: number;
+}
+export declare class FileAgentEventStore implements IAgentEventStoreV2 {
+    readonly eventSchemaVersion: 2;
+    private readonly rootDir;
+    private readonly lockTimeoutMs;
+    constructor(options: IFileAgentEventStoreOptions);
+    private sessionKey;
+    private snapshotPath;
+    private archivePath;
+    private readValue;
+    private syncDirectory;
+    private writeAtomic;
+    private withSessionLock;
+    load(sessionId: string): Promise<TAgentEventSnapshot | undefined>;
+    save(sessionId: string, events: readonly TAgentEvent[], expectedRevision: number): Promise<number>;
+    archive(archive: IAgentEventArchiveV2): Promise<void>;
+    loadArchive(sessionId: string, archiveId: string): Promise<TAgentEventArchive | undefined>;
+}
+export {};